| This is gdb.info, produced by makeinfo version 4.13 from |
| ../../../src/gdb/doc/gdb.texinfo. |
| |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Gdb: (gdb). The GNU debugger. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU debugger GDB. |
| |
| This is the Ninth Edition, of `Debugging with GDB: the GNU |
| Source-Level Debugger' for GDB Version 6.8. |
| |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, |
| 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 |
| Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.1 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| |
| |
| File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir) |
| |
| Debugging with GDB |
| ****************** |
| |
| This file describes GDB, the GNU symbolic debugger. |
| |
| This is the Ninth Edition, for GDB Version 6.8. |
| |
| Copyright (C) 1988-2006 Free Software Foundation, Inc. |
| |
| This edition of the GDB manual is dedicated to the memory of Fred |
| Fish. Fred was a long-standing contributor to GDB and to Free software |
| in general. We will miss him. |
| |
| * Menu: |
| |
| * Summary:: Summary of GDB |
| * Sample Session:: A sample GDB session |
| |
| * Invocation:: Getting in and out of GDB |
| * Commands:: GDB commands |
| * Running:: Running programs under GDB |
| * Stopping:: Stopping and continuing |
| * Stack:: Examining the stack |
| * Source:: Examining source files |
| * Data:: Examining data |
| * Macros:: Preprocessor Macros |
| * Tracepoints:: Debugging remote targets non-intrusively |
| * Overlays:: Debugging programs that use overlays |
| |
| * Languages:: Using GDB with different languages |
| |
| * Symbols:: Examining the symbol table |
| * Altering:: Altering execution |
| * GDB Files:: GDB files |
| * Targets:: Specifying a debugging target |
| * Remote Debugging:: Debugging remote programs |
| * Configurations:: Configuration-specific information |
| * Controlling GDB:: Controlling GDB |
| * Sequences:: Canned sequences of commands |
| * Interpreters:: Command Interpreters |
| * TUI:: GDB Text User Interface |
| * Emacs:: Using GDB under GNU Emacs |
| * GDB/MI:: GDB's Machine Interface. |
| * Annotations:: GDB's annotation interface. |
| |
| * GDB Bugs:: Reporting bugs in GDB |
| |
| * Command Line Editing:: Command Line Editing |
| * Using History Interactively:: Using History Interactively |
| * Formatting Documentation:: How to format and print GDB documentation |
| * Installing GDB:: Installing GDB |
| * Maintenance Commands:: Maintenance Commands |
| * Remote Protocol:: GDB Remote Serial Protocol |
| * Agent Expressions:: The GDB Agent Expression Mechanism |
| * Target Descriptions:: How targets can describe themselves to |
| GDB |
| * Copying:: GNU General Public License says |
| how you can copy and share GDB |
| * GNU Free Documentation License:: The license for this documentation |
| * Index:: Index |
| |
| |
| File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top |
| |
| Summary of GDB |
| ************** |
| |
| The purpose of a debugger such as GDB is to allow you to see what is |
| going on "inside" another program while it executes--or what another |
| program was doing at the moment it crashed. |
| |
| GDB can do four main kinds of things (plus other things in support of |
| these) to help you catch bugs in the act: |
| |
| * Start your program, specifying anything that might affect its |
| behavior. |
| |
| * Make your program stop on specified conditions. |
| |
| * Examine what has happened, when your program has stopped. |
| |
| * Change things in your program, so you can experiment with |
| correcting the effects of one bug and go on to learn about another. |
| |
| You can use GDB to debug programs written in C and C++. For more |
| information, see *note Supported Languages: Supported Languages. For |
| more information, see *note C and C++: C. |
| |
| Support for Modula-2 is partial. For information on Modula-2, see |
| *note Modula-2: Modula-2. |
| |
| Debugging Pascal programs which use sets, subranges, file variables, |
| or nested functions does not currently work. GDB does not support |
| entering expressions, printing values, or similar features using Pascal |
| syntax. |
| |
| GDB can be used to debug programs written in Fortran, although it |
| may be necessary to refer to some variables with a trailing underscore. |
| |
| GDB can be used to debug programs written in Objective-C, using |
| either the Apple/NeXT or the GNU Objective-C runtime. |
| |
| * Menu: |
| |
| * Free Software:: Freely redistributable software |
| * Contributors:: Contributors to GDB |
| |
| |
| File: gdb.info, Node: Free Software, Next: Contributors, Up: Summary |
| |
| Free Software |
| ============= |
| |
| GDB is "free software", protected by the GNU General Public License |
| (GPL). The GPL gives you the freedom to copy or adapt a licensed |
| program--but every person getting a copy also gets with it the freedom |
| to modify that copy (which means that they must get access to the |
| source code), and the freedom to distribute further copies. Typical |
| software companies use copyrights to limit your freedoms; the Free |
| Software Foundation uses the GPL to preserve these freedoms. |
| |
| Fundamentally, the General Public License is a license which says |
| that you have these freedoms and that you cannot take these freedoms |
| away from anyone else. |
| |
| Free Software Needs Free Documentation |
| ====================================== |
| |
| The biggest deficiency in the free software community today is not in |
| the software--it is the lack of good free documentation that we can |
| include with the free software. Many of our most important programs do |
| not come with free reference manuals and free introductory texts. |
| Documentation is an essential part of any software package; when an |
| important free software package does not come with a free manual and a |
| free tutorial, that is a major gap. We have many such gaps today. |
| |
| Consider Perl, for instance. The tutorial manuals that people |
| normally use are non-free. How did this come about? Because the |
| authors of those manuals published them with restrictive terms--no |
| copying, no modification, source files not available--which exclude |
| them from the free software world. |
| |
| That wasn't the first time this sort of thing happened, and it was |
| far from the last. Many times we have heard a GNU user eagerly |
| describe a manual that he is writing, his intended contribution to the |
| community, only to learn that he had ruined everything by signing a |
| publication contract to make it non-free. |
| |
| Free documentation, like free software, is a matter of freedom, not |
| price. The problem with the non-free manual is not that publishers |
| charge a price for printed copies--that in itself is fine. (The Free |
| Software Foundation sells printed copies of manuals, too.) The problem |
| is the restrictions on the use of the manual. Free manuals are |
| available in source code form, and give you permission to copy and |
| modify. Non-free manuals do not allow this. |
| |
| The criteria of freedom for a free manual are roughly the same as for |
| free software. Redistribution (including the normal kinds of |
| commercial redistribution) must be permitted, so that the manual can |
| accompany every copy of the program, both on-line and on paper. |
| |
| Permission for modification of the technical content is crucial too. |
| When people modify the software, adding or changing features, if they |
| are conscientious they will change the manual too--so they can provide |
| accurate and clear documentation for the modified program. A manual |
| that leaves you no choice but to write a new manual to document a |
| changed version of the program is not really available to our community. |
| |
| Some kinds of limits on the way modification is handled are |
| acceptable. For example, requirements to preserve the original |
| author's copyright notice, the distribution terms, or the list of |
| authors, are ok. It is also no problem to require modified versions to |
| include notice that they were modified. Even entire sections that may |
| not be deleted or changed are acceptable, as long as they deal with |
| nontechnical topics (like this one). These kinds of restrictions are |
| acceptable because they don't obstruct the community's normal use of |
| the manual. |
| |
| However, it must be possible to modify all the _technical_ content |
| of the manual, and then distribute the result in all the usual media, |
| through all the usual channels. Otherwise, the restrictions obstruct |
| the use of the manual, it is not free, and we need another manual to |
| replace it. |
| |
| Please spread the word about this issue. Our community continues to |
| lose manuals to proprietary publishing. If we spread the word that |
| free software needs free reference manuals and free tutorials, perhaps |
| the next person who wants to contribute by writing documentation will |
| realize, before it is too late, that only free manuals contribute to |
| the free software community. |
| |
| If you are writing documentation, please insist on publishing it |
| under the GNU Free Documentation License or another free documentation |
| license. Remember that this decision requires your approval--you don't |
| have to let the publisher decide. Some commercial publishers will use |
| a free license if you insist, but they will not propose the option; it |
| is up to you to raise the issue and say firmly that this is what you |
| want. If the publisher you are dealing with refuses, please try other |
| publishers. If you're not sure whether a proposed license is free, |
| write to <licensing@gnu.org>. |
| |
| You can encourage commercial publishers to sell more free, copylefted |
| manuals and tutorials by buying them, and particularly by buying copies |
| from the publishers that paid for their writing or for major |
| improvements. Meanwhile, try to avoid buying non-free documentation at |
| all. Check the distribution terms of a manual before you buy it, and |
| insist that whoever seeks your business must respect your freedom. |
| Check the history of the book, and try to reward the publishers that |
| have paid or pay the authors to work on it. |
| |
| The Free Software Foundation maintains a list of free documentation |
| published by other publishers, at |
| `http://www.fsf.org/doc/other-free-books.html'. |
| |
| |
| File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary |
| |
| Contributors to GDB |
| =================== |
| |
| Richard Stallman was the original author of GDB, and of many other GNU |
| programs. Many others have contributed to its development. This |
| section attempts to credit major contributors. One of the virtues of |
| free software is that everyone is free to contribute to it; with |
| regret, we cannot actually acknowledge everyone here. The file |
| `ChangeLog' in the GDB distribution approximates a blow-by-blow account. |
| |
| Changes much prior to version 2.0 are lost in the mists of time. |
| |
| _Plea:_ Additions to this section are particularly welcome. If you |
| or your friends (or enemies, to be evenhanded) have been unfairly |
| omitted from this list, we would like to add your names! |
| |
| So that they may not regard their many labors as thankless, we |
| particularly thank those who shepherded GDB through major releases: |
| Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim |
| Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs |
| (release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, |
| and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, |
| and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim |
| Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, |
| 3.1, and 3.0). |
| |
| Richard Stallman, assisted at various times by Peter TerMaat, Chris |
| Hanson, and Richard Mlynarik, handled releases through 2.8. |
| |
| Michael Tiemann is the author of most of the GNU C++ support in GDB, |
| with significant additional contributions from Per Bothner and Daniel |
| Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ |
| was by Peter TerMaat (who also did much general update work leading to |
| release 3.0). |
| |
| GDB uses the BFD subroutine library to examine multiple object-file |
| formats; BFD was a joint project of David V. Henkel-Wallace, Rich |
| Pixley, Steve Chamberlain, and John Gilmore. |
| |
| David Johnson wrote the original COFF support; Pace Willison did the |
| original support for encapsulated COFF. |
| |
| Brent Benson of Harris Computer Systems contributed DWARF 2 support. |
| |
| Adam de Boor and Bradley Davis contributed the ISI Optimum V support. |
| Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS |
| support. Jean-Daniel Fekete contributed Sun 386i support. Chris |
| Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki |
| Hasei contributed Sony/News OS 3 support. David Johnson contributed |
| Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. |
| Jeff Law contributed HP PA and SOM support. Keith Packard contributed |
| NS32K support. Doug Rabson contributed Acorn Risc Machine support. |
| Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith |
| contributed Convex support (and Fortran debugging). Jonathan Stone |
| contributed Pyramid support. Michael Tiemann contributed SPARC support. |
| Tim Tucker contributed support for the Gould NP1 and Gould Powernode. |
| Pace Willison contributed Intel 386 support. Jay Vosburgh contributed |
| Symmetry support. Marko Mlinar contributed OpenRISC 1000 support. |
| |
| Andreas Schwab contributed M68K GNU/Linux support. |
| |
| Rich Schaefer and Peter Schauer helped with support of SunOS shared |
| libraries. |
| |
| Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about |
| several machine instruction sets. |
| |
| Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped |
| develop remote debugging. Intel Corporation, Wind River Systems, AMD, |
| and ARM contributed remote debugging modules for the i960, VxWorks, |
| A29K UDI, and RDI targets, respectively. |
| |
| Brian Fox is the author of the readline libraries providing |
| command-line editing and command history. |
| |
| Andrew Beers of SUNY Buffalo wrote the language-switching code, the |
| Modula-2 support, and contributed the Languages chapter of this manual. |
| |
| Fred Fish wrote most of the support for Unix System Vr4. He also |
| enhanced the command-completion support to cover C++ overloaded symbols. |
| |
| Hitachi America (now Renesas America), Ltd. sponsored the support for |
| H8/300, H8/500, and Super-H processors. |
| |
| NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx |
| processors. |
| |
| Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and |
| M32R/D processors. |
| |
| Toshiba sponsored the support for the TX39 Mips processor. |
| |
| Matsushita sponsored the support for the MN10200 and MN10300 |
| processors. |
| |
| Fujitsu sponsored the support for SPARClite and FR30 processors. |
| |
| Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware |
| watchpoints. |
| |
| Michael Snyder added support for tracepoints. |
| |
| Stu Grossman wrote gdbserver. |
| |
| Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly |
| innumerable bug fixes and cleanups throughout GDB. |
| |
| The following people at the Hewlett-Packard Company contributed |
| support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 |
| (narrow mode), HP's implementation of kernel threads, HP's aC++ |
| compiler, and the Text User Interface (nee Terminal User Interface): |
| Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, |
| Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase |
| provided HP-specific information in this manual. |
| |
| DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert |
| Hoehne made significant contributions to the DJGPP port. |
| |
| Cygnus Solutions has sponsored GDB maintenance and much of its |
| development since 1991. Cygnus engineers who have worked on GDB |
| fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin |
| Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim |
| Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, |
| Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek |
| Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In |
| addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, |
| JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug |
| Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff |
| Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, |
| Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin |
| Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela |
| Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David |
| Zuhn have made contributions both large and small. |
| |
| Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for |
| Cygnus Solutions, implemented the original GDB/MI interface. |
| |
| Jim Blandy added support for preprocessor macros, while working for |
| Red Hat. |
| |
| Andrew Cagney designed GDB's architecture vector. Many people |
| including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek, |
| Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto, |
| Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna |
| Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration |
| of old architectures to this new framework. |
| |
| Andrew Cagney completely re-designed and re-implemented GDB's |
| unwinder framework, this consisting of a fresh new design featuring |
| frame IDs, independent frame sniffers, and the sentinel frame. Mark |
| Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind |
| unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad |
| unwinders. The architecture-specific changes, each involving a |
| complete rewrite of the architecture's frame code, were carried out by |
| Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane |
| Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel |
| Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei |
| Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich |
| Weigand. |
| |
| Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from |
| Tensilica, Inc. contributed support for Xtensa processors. Others who |
| have worked on the Xtensa port of GDB in the past include Steve Tjiang, |
| John Newlin, and Scott Foehner. |
| |
| |
| File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top |
| |
| 1 A Sample GDB Session |
| ********************** |
| |
| You can use this manual at your leisure to read all about GDB. |
| However, a handful of commands are enough to get started using the |
| debugger. This chapter illustrates those commands. |
| |
| One of the preliminary versions of GNU `m4' (a generic macro |
| processor) exhibits the following bug: sometimes, when we change its |
| quote strings from the default, the commands used to capture one macro |
| definition within another stop working. In the following short `m4' |
| session, we define a macro `foo' which expands to `0000'; we then use |
| the `m4' built-in `defn' to define `bar' as the same thing. However, |
| when we change the open quote string to `<QUOTE>' and the close quote |
| string to `<UNQUOTE>', the same procedure fails to define a new synonym |
| `baz': |
| |
| $ cd gnu/m4 |
| $ ./m4 |
| define(foo,0000) |
| |
| foo |
| 0000 |
| define(bar,defn(`foo')) |
| |
| bar |
| 0000 |
| changequote(<QUOTE>,<UNQUOTE>) |
| |
| define(baz,defn(<QUOTE>foo<UNQUOTE>)) |
| baz |
| Ctrl-d |
| m4: End of input: 0: fatal error: EOF in string |
| |
| Let us use GDB to try to see what is going on. |
| |
| $ gdb m4 |
| GDB is free software and you are welcome to distribute copies |
| of it under certain conditions; type "show copying" to see |
| the conditions. |
| There is absolutely no warranty for GDB; type "show warranty" |
| for details. |
| |
| GDB 6.8, Copyright 1999 Free Software Foundation, Inc... |
| (gdb) |
| |
| GDB reads only enough symbol data to know where to find the rest when |
| needed; as a result, the first prompt comes up very quickly. We now |
| tell GDB to use a narrower display width than usual, so that examples |
| fit in this manual. |
| |
| (gdb) set width 70 |
| |
| We need to see how the `m4' built-in `changequote' works. Having |
| looked at the source, we know the relevant subroutine is |
| `m4_changequote', so we set a breakpoint there with the GDB `break' |
| command. |
| |
| (gdb) break m4_changequote |
| Breakpoint 1 at 0x62f4: file builtin.c, line 879. |
| |
| Using the `run' command, we start `m4' running under GDB control; as |
| long as control does not reach the `m4_changequote' subroutine, the |
| program runs as usual: |
| |
| (gdb) run |
| Starting program: /work/Editorial/gdb/gnu/m4/m4 |
| define(foo,0000) |
| |
| foo |
| 0000 |
| |
| To trigger the breakpoint, we call `changequote'. GDB suspends |
| execution of `m4', displaying information about the context where it |
| stops. |
| |
| changequote(<QUOTE>,<UNQUOTE>) |
| |
| Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) |
| at builtin.c:879 |
| 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) |
| |
| Now we use the command `n' (`next') to advance execution to the next |
| line of the current function. |
| |
| (gdb) n |
| 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ |
| : nil, |
| |
| `set_quotes' looks like a promising subroutine. We can go into it by |
| using the command `s' (`step') instead of `next'. `step' goes to the |
| next line to be executed in _any_ subroutine, so it steps into |
| `set_quotes'. |
| |
| (gdb) s |
| set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") |
| at input.c:530 |
| 530 if (lquote != def_lquote) |
| |
| The display that shows the subroutine where `m4' is now suspended (and |
| its arguments) is called a stack frame display. It shows a summary of |
| the stack. We can use the `backtrace' command (which can also be |
| spelled `bt'), to see where we are in the stack as a whole: the |
| `backtrace' command displays a stack frame for each active subroutine. |
| |
| (gdb) bt |
| #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") |
| at input.c:530 |
| #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) |
| at builtin.c:882 |
| #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 |
| #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) |
| at macro.c:71 |
| #4 0x79dc in expand_input () at macro.c:40 |
| #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 |
| |
| We step through a few more lines to see what happens. The first two |
| times, we can use `s'; the next two times we use `n' to avoid falling |
| into the `xstrdup' subroutine. |
| |
| (gdb) s |
| 0x3b5c 532 if (rquote != def_rquote) |
| (gdb) s |
| 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ |
| def_lquote : xstrdup(lq); |
| (gdb) n |
| 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ |
| : xstrdup(rq); |
| (gdb) n |
| 538 len_lquote = strlen(rquote); |
| |
| The last line displayed looks a little odd; we can examine the variables |
| `lquote' and `rquote' to see if they are in fact the new left and right |
| quotes we specified. We use the command `p' (`print') to see their |
| values. |
| |
| (gdb) p lquote |
| $1 = 0x35d40 "<QUOTE>" |
| (gdb) p rquote |
| $2 = 0x35d50 "<UNQUOTE>" |
| |
| `lquote' and `rquote' are indeed the new left and right quotes. To |
| look at some context, we can display ten lines of source surrounding |
| the current line with the `l' (`list') command. |
| |
| (gdb) l |
| 533 xfree(rquote); |
| 534 |
| 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ |
| : xstrdup (lq); |
| 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ |
| : xstrdup (rq); |
| 537 |
| 538 len_lquote = strlen(rquote); |
| 539 len_rquote = strlen(lquote); |
| 540 } |
| 541 |
| 542 void |
| |
| Let us step past the two lines that set `len_lquote' and `len_rquote', |
| and then examine the values of those variables. |
| |
| (gdb) n |
| 539 len_rquote = strlen(lquote); |
| (gdb) n |
| 540 } |
| (gdb) p len_lquote |
| $3 = 9 |
| (gdb) p len_rquote |
| $4 = 7 |
| |
| That certainly looks wrong, assuming `len_lquote' and `len_rquote' are |
| meant to be the lengths of `lquote' and `rquote' respectively. We can |
| set them to better values using the `p' command, since it can print the |
| value of any expression--and that expression can include subroutine |
| calls and assignments. |
| |
| (gdb) p len_lquote=strlen(lquote) |
| $5 = 7 |
| (gdb) p len_rquote=strlen(rquote) |
| $6 = 9 |
| |
| Is that enough to fix the problem of using the new quotes with the `m4' |
| built-in `defn'? We can allow `m4' to continue executing with the `c' |
| (`continue') command, and then try the example that caused trouble |
| initially: |
| |
| (gdb) c |
| Continuing. |
| |
| define(baz,defn(<QUOTE>foo<UNQUOTE>)) |
| |
| baz |
| 0000 |
| |
| Success! The new quotes now work just as well as the default ones. The |
| problem seems to have been just the two typos defining the wrong |
| lengths. We allow `m4' exit by giving it an EOF as input: |
| |
| Ctrl-d |
| Program exited normally. |
| |
| The message `Program exited normally.' is from GDB; it indicates `m4' |
| has finished executing. We can end our GDB session with the GDB `quit' |
| command. |
| |
| (gdb) quit |
| |
| |
| File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top |
| |
| 2 Getting In and Out of GDB |
| *************************** |
| |
| This chapter discusses how to start GDB, and how to get out of it. The |
| essentials are: |
| * type `gdb' to start GDB. |
| |
| * type `quit' or `Ctrl-d' to exit. |
| |
| * Menu: |
| |
| * Invoking GDB:: How to start GDB |
| * Quitting GDB:: How to quit GDB |
| * Shell Commands:: How to use shell commands inside GDB |
| * Logging Output:: How to log GDB's output to a file |
| |
| |
| File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation |
| |
| 2.1 Invoking GDB |
| ================ |
| |
| Invoke GDB by running the program `gdb'. Once started, GDB reads |
| commands from the terminal until you tell it to exit. |
| |
| You can also run `gdb' with a variety of arguments and options, to |
| specify more of your debugging environment at the outset. |
| |
| The command-line options described here are designed to cover a |
| variety of situations; in some environments, some of these options may |
| effectively be unavailable. |
| |
| The most usual way to start GDB is with one argument, specifying an |
| executable program: |
| |
| gdb PROGRAM |
| |
| You can also start with both an executable program and a core file |
| specified: |
| |
| gdb PROGRAM CORE |
| |
| You can, instead, specify a process ID as a second argument, if you |
| want to debug a running process: |
| |
| gdb PROGRAM 1234 |
| |
| would attach GDB to process `1234' (unless you also have a file named |
| `1234'; GDB does check for a core file first). |
| |
| Taking advantage of the second command-line argument requires a |
| fairly complete operating system; when you use GDB as a remote debugger |
| attached to a bare board, there may not be any notion of "process", and |
| there is often no way to get a core dump. GDB will warn you if it is |
| unable to attach or to read core dumps. |
| |
| You can optionally have `gdb' pass any arguments after the |
| executable file to the inferior using `--args'. This option stops |
| option processing. |
| gdb --args gcc -O2 -c foo.c |
| This will cause `gdb' to debug `gcc', and to set `gcc''s |
| command-line arguments (*note Arguments::) to `-O2 -c foo.c'. |
| |
| You can run `gdb' without printing the front material, which |
| describes GDB's non-warranty, by specifying `-silent': |
| |
| gdb -silent |
| |
| You can further control how GDB starts up by using command-line |
| options. GDB itself can remind you of the options available. |
| |
| Type |
| |
| gdb -help |
| |
| to display all available options and briefly describe their use (`gdb |
| -h' is a shorter equivalent). |
| |
| All options and command line arguments you give are processed in |
| sequential order. The order makes a difference when the `-x' option is |
| used. |
| |
| * Menu: |
| |
| * File Options:: Choosing files |
| * Mode Options:: Choosing modes |
| * Startup:: What GDB does during startup |
| |
| |
| File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB |
| |
| 2.1.1 Choosing Files |
| -------------------- |
| |
| When GDB starts, it reads any arguments other than options as |
| specifying an executable file and core file (or process ID). This is |
| the same as if the arguments were specified by the `-se' and `-c' (or |
| `-p') options respectively. (GDB reads the first argument that does |
| not have an associated option flag as equivalent to the `-se' option |
| followed by that argument; and the second argument that does not have |
| an associated option flag, if any, as equivalent to the `-c'/`-p' |
| option followed by that argument.) If the second argument begins with |
| a decimal digit, GDB will first attempt to attach to it as a process, |
| and if that fails, attempt to open it as a corefile. If you have a |
| corefile whose name begins with a digit, you can prevent GDB from |
| treating it as a pid by prefixing it with `./', e.g. `./12345'. |
| |
| If GDB has not been configured to included core file support, such |
| as for most embedded targets, then it will complain about a second |
| argument and ignore it. |
| |
| Many options have both long and short forms; both are shown in the |
| following list. GDB also recognizes the long forms if you truncate |
| them, so long as enough of the option is present to be unambiguous. |
| (If you prefer, you can flag option arguments with `--' rather than |
| `-', though we illustrate the more usual convention.) |
| |
| `-symbols FILE' |
| `-s FILE' |
| Read symbol table from file FILE. |
| |
| `-exec FILE' |
| `-e FILE' |
| Use file FILE as the executable file to execute when appropriate, |
| and for examining pure data in conjunction with a core dump. |
| |
| `-se FILE' |
| Read symbol table from file FILE and use it as the executable file. |
| |
| `-core FILE' |
| `-c FILE' |
| Use file FILE as a core dump to examine. |
| |
| `-pid NUMBER' |
| `-p NUMBER' |
| Connect to process ID NUMBER, as with the `attach' command. |
| |
| `-command FILE' |
| `-x FILE' |
| Execute GDB commands from file FILE. *Note Command files: Command |
| Files. |
| |
| `-eval-command COMMAND' |
| `-ex COMMAND' |
| Execute a single GDB command. |
| |
| This option may be used multiple times to call multiple commands. |
| It may also be interleaved with `-command' as required. |
| |
| gdb -ex 'target sim' -ex 'load' \ |
| -x setbreakpoints -ex 'run' a.out |
| |
| `-directory DIRECTORY' |
| `-d DIRECTORY' |
| Add DIRECTORY to the path to search for source and script files. |
| |
| `-r' |
| `-readnow' |
| Read each symbol file's entire symbol table immediately, rather |
| than the default, which is to read it incrementally as it is |
| needed. This makes startup slower, but makes future operations |
| faster. |
| |
| |
| |
| File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB |
| |
| 2.1.2 Choosing Modes |
| -------------------- |
| |
| You can run GDB in various alternative modes--for example, in batch |
| mode or quiet mode. |
| |
| `-nx' |
| `-n' |
| Do not execute commands found in any initialization files. |
| Normally, GDB executes the commands in these files after all the |
| command options and arguments have been processed. *Note Command |
| Files: Command Files. |
| |
| `-quiet' |
| `-silent' |
| `-q' |
| "Quiet". Do not print the introductory and copyright messages. |
| These messages are also suppressed in batch mode. |
| |
| `-batch' |
| Run in batch mode. Exit with status `0' after processing all the |
| command files specified with `-x' (and all commands from |
| initialization files, if not inhibited with `-n'). Exit with |
| nonzero status if an error occurs in executing the GDB commands in |
| the command files. |
| |
| Batch mode may be useful for running GDB as a filter, for example |
| to download and run a program on another computer; in order to |
| make this more useful, the message |
| |
| Program exited normally. |
| |
| (which is ordinarily issued whenever a program running under GDB |
| control terminates) is not issued when running in batch mode. |
| |
| `-batch-silent' |
| Run in batch mode exactly like `-batch', but totally silently. All |
| GDB output to `stdout' is prevented (`stderr' is unaffected). |
| This is much quieter than `-silent' and would be useless for an |
| interactive session. |
| |
| This is particularly useful when using targets that give `Loading |
| section' messages, for example. |
| |
| Note that targets that give their output via GDB, as opposed to |
| writing directly to `stdout', will also be made silent. |
| |
| `-return-child-result' |
| The return code from GDB will be the return code from the child |
| process (the process being debugged), with the following |
| exceptions: |
| |
| * GDB exits abnormally. E.g., due to an incorrect argument or |
| an internal error. In this case the exit code is the same as |
| it would have been without `-return-child-result'. |
| |
| * The user quits with an explicit value. E.g., `quit 1'. |
| |
| * The child process never runs, or is not allowed to terminate, |
| in which case the exit code will be -1. |
| |
| This option is useful in conjunction with `-batch' or |
| `-batch-silent', when GDB is being used as a remote program loader |
| or simulator interface. |
| |
| `-nowindows' |
| `-nw' |
| "No windows". If GDB comes with a graphical user interface (GUI) |
| built in, then this option tells GDB to only use the command-line |
| interface. If no GUI is available, this option has no effect. |
| |
| `-windows' |
| `-w' |
| If GDB includes a GUI, then this option requires it to be used if |
| possible. |
| |
| `-cd DIRECTORY' |
| Run GDB using DIRECTORY as its working directory, instead of the |
| current directory. |
| |
| `-fullname' |
| `-f' |
| GNU Emacs sets this option when it runs GDB as a subprocess. It |
| tells GDB to output the full file name and line number in a |
| standard, recognizable fashion each time a stack frame is |
| displayed (which includes each time your program stops). This |
| recognizable format looks like two `\032' characters, followed by |
| the file name, line number and character position separated by |
| colons, and a newline. The Emacs-to-GDB interface program uses |
| the two `\032' characters as a signal to display the source code |
| for the frame. |
| |
| `-epoch' |
| The Epoch Emacs-GDB interface sets this option when it runs GDB as |
| a subprocess. It tells GDB to modify its print routines so as to |
| allow Epoch to display values of expressions in a separate window. |
| |
| `-annotate LEVEL' |
| This option sets the "annotation level" inside GDB. Its effect is |
| identical to using `set annotate LEVEL' (*note Annotations::). |
| The annotation LEVEL controls how much information GDB prints |
| together with its prompt, values of expressions, source lines, and |
| other types of output. Level 0 is the normal, level 1 is for use |
| when GDB is run as a subprocess of GNU Emacs, level 3 is the |
| maximum annotation suitable for programs that control GDB, and |
| level 2 has been deprecated. |
| |
| The annotation mechanism has largely been superseded by GDB/MI |
| (*note GDB/MI::). |
| |
| `--args' |
| Change interpretation of command line so that arguments following |
| the executable file are passed as command line arguments to the |
| inferior. This option stops option processing. |
| |
| `-baud BPS' |
| `-b BPS' |
| Set the line speed (baud rate or bits per second) of any serial |
| interface used by GDB for remote debugging. |
| |
| `-l TIMEOUT' |
| Set the timeout (in seconds) of any communication used by GDB for |
| remote debugging. |
| |
| `-tty DEVICE' |
| `-t DEVICE' |
| Run using DEVICE for your program's standard input and output. |
| |
| `-tui' |
| Activate the "Text User Interface" when starting. The Text User |
| Interface manages several text windows on the terminal, showing |
| source, assembly, registers and GDB command outputs (*note GDB |
| Text User Interface: TUI.). Alternatively, the Text User |
| Interface can be enabled by invoking the program `gdbtui'. Do not |
| use this option if you run GDB from Emacs (*note Using GDB under |
| GNU Emacs: Emacs.). |
| |
| `-interpreter INTERP' |
| Use the interpreter INTERP for interface with the controlling |
| program or device. This option is meant to be set by programs |
| which communicate with GDB using it as a back end. *Note Command |
| Interpreters: Interpreters. |
| |
| `--interpreter=mi' (or `--interpreter=mi2') causes GDB to use the |
| "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included |
| since GDB version 6.0. The previous GDB/MI interface, included in |
| GDB version 5.3 and selected with `--interpreter=mi1', is |
| deprecated. Earlier GDB/MI interfaces are no longer supported. |
| |
| `-write' |
| Open the executable and core files for both reading and writing. |
| This is equivalent to the `set write on' command inside GDB (*note |
| Patching::). |
| |
| `-statistics' |
| This option causes GDB to print statistics about time and memory |
| usage after it completes each command and returns to the prompt. |
| |
| `-version' |
| This option causes GDB to print its version number and no-warranty |
| blurb, and exit. |
| |
| |
| |
| File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB |
| |
| 2.1.3 What GDB Does During Startup |
| ---------------------------------- |
| |
| Here's the description of what GDB does during session startup: |
| |
| 1. Sets up the command interpreter as specified by the command line |
| (*note interpreter: Mode Options.). |
| |
| 2. Reads the "init file" (if any) in your home directory(1) and |
| executes all the commands in that file. |
| |
| 3. Processes command line options and operands. |
| |
| 4. Reads and executes the commands from init file (if any) in the |
| current working directory. This is only done if the current |
| directory is different from your home directory. Thus, you can |
| have more than one init file, one generic in your home directory, |
| and another, specific to the program you are debugging, in the |
| directory where you invoke GDB. |
| |
| 5. Reads command files specified by the `-x' option. *Note Command |
| Files::, for more details about GDB command files. |
| |
| 6. Reads the command history recorded in the "history file". *Note |
| Command History::, for more details about the command history and |
| the files where GDB records it. |
| |
| Init files use the same syntax as "command files" (*note Command |
| Files::) and are processed by GDB in the same way. The init file in |
| your home directory can set options (such as `set complaints') that |
| affect subsequent processing of command line options and operands. |
| Init files are not executed if you use the `-nx' option (*note Choosing |
| Modes: Mode Options.). |
| |
| The GDB init files are normally called `.gdbinit'. The DJGPP port |
| of GDB uses the name `gdb.ini', due to the limitations of file names |
| imposed by DOS filesystems. The Windows ports of GDB use the standard |
| name, but if they find a `gdb.ini' file, they warn you about that and |
| suggest to rename the file to the standard name. |
| |
| ---------- Footnotes ---------- |
| |
| (1) On DOS/Windows systems, the home directory is the one pointed to |
| by the `HOME' environment variable. |
| |
| |
| File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation |
| |
| 2.2 Quitting GDB |
| ================ |
| |
| `quit [EXPRESSION]' |
| `q' |
| To exit GDB, use the `quit' command (abbreviated `q'), or type an |
| end-of-file character (usually `Ctrl-d'). If you do not supply |
| EXPRESSION, GDB will terminate normally; otherwise it will |
| terminate using the result of EXPRESSION as the error code. |
| |
| An interrupt (often `Ctrl-c') does not exit from GDB, but rather |
| terminates the action of any GDB command that is in progress and |
| returns to GDB command level. It is safe to type the interrupt |
| character at any time because GDB does not allow it to take effect |
| until a time when it is safe. |
| |
| If you have been using GDB to control an attached process or device, |
| you can release it with the `detach' command (*note Debugging an |
| Already-running Process: Attach.). |
| |
| |
| File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation |
| |
| 2.3 Shell Commands |
| ================== |
| |
| If you need to execute occasional shell commands during your debugging |
| session, there is no need to leave or suspend GDB; you can just use the |
| `shell' command. |
| |
| `shell COMMAND STRING' |
| Invoke a standard shell to execute COMMAND STRING. If it exists, |
| the environment variable `SHELL' determines which shell to run. |
| Otherwise GDB uses the default shell (`/bin/sh' on Unix systems, |
| `COMMAND.COM' on MS-DOS, etc.). |
| |
| The utility `make' is often needed in development environments. You |
| do not have to use the `shell' command for this purpose in GDB: |
| |
| `make MAKE-ARGS' |
| Execute the `make' program with the specified arguments. This is |
| equivalent to `shell make MAKE-ARGS'. |
| |
| |
| File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation |
| |
| 2.4 Logging Output |
| ================== |
| |
| You may want to save the output of GDB commands to a file. There are |
| several commands to control GDB's logging. |
| |
| `set logging on' |
| Enable logging. |
| |
| `set logging off' |
| Disable logging. |
| |
| `set logging file FILE' |
| Change the name of the current logfile. The default logfile is |
| `gdb.txt'. |
| |
| `set logging overwrite [on|off]' |
| By default, GDB will append to the logfile. Set `overwrite' if |
| you want `set logging on' to overwrite the logfile instead. |
| |
| `set logging redirect [on|off]' |
| By default, GDB output will go to both the terminal and the |
| logfile. Set `redirect' if you want output to go only to the log |
| file. |
| |
| `show logging' |
| Show the current values of the logging settings. |
| |
| |
| File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top |
| |
| 3 GDB Commands |
| ************** |
| |
| You can abbreviate a GDB command to the first few letters of the command |
| name, if that abbreviation is unambiguous; and you can repeat certain |
| GDB commands by typing just <RET>. You can also use the <TAB> key to |
| get GDB to fill out the rest of a word in a command (or to show you the |
| alternatives available, if there is more than one possibility). |
| |
| * Menu: |
| |
| * Command Syntax:: How to give commands to GDB |
| * Completion:: Command completion |
| * Help:: How to ask GDB for help |
| |
| |
| File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands |
| |
| 3.1 Command Syntax |
| ================== |
| |
| A GDB command is a single line of input. There is no limit on how long |
| it can be. It starts with a command name, which is followed by |
| arguments whose meaning depends on the command name. For example, the |
| command `step' accepts an argument which is the number of times to |
| step, as in `step 5'. You can also use the `step' command with no |
| arguments. Some commands do not allow any arguments. |
| |
| GDB command names may always be truncated if that abbreviation is |
| unambiguous. Other possible command abbreviations are listed in the |
| documentation for individual commands. In some cases, even ambiguous |
| abbreviations are allowed; for example, `s' is specially defined as |
| equivalent to `step' even though there are other commands whose names |
| start with `s'. You can test abbreviations by using them as arguments |
| to the `help' command. |
| |
| A blank line as input to GDB (typing just <RET>) means to repeat the |
| previous command. Certain commands (for example, `run') will not |
| repeat this way; these are commands whose unintentional repetition |
| might cause trouble and which you are unlikely to want to repeat. |
| User-defined commands can disable this feature; see *note dont-repeat: |
| Define. |
| |
| The `list' and `x' commands, when you repeat them with <RET>, |
| construct new arguments rather than repeating exactly as typed. This |
| permits easy scanning of source or memory. |
| |
| GDB can also use <RET> in another way: to partition lengthy output, |
| in a way similar to the common utility `more' (*note Screen Size: |
| Screen Size.). Since it is easy to press one <RET> too many in this |
| situation, GDB disables command repetition after any command that |
| generates this sort of display. |
| |
| Any text from a `#' to the end of the line is a comment; it does |
| nothing. This is useful mainly in command files (*note Command Files: |
| Command Files.). |
| |
| The `Ctrl-o' binding is useful for repeating a complex sequence of |
| commands. This command accepts the current line, like <RET>, and then |
| fetches the next line relative to the current line from the history for |
| editing. |
| |
| |
| File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands |
| |
| 3.2 Command Completion |
| ====================== |
| |
| GDB can fill in the rest of a word in a command for you, if there is |
| only one possibility; it can also show you what the valid possibilities |
| are for the next word in a command, at any time. This works for GDB |
| commands, GDB subcommands, and the names of symbols in your program. |
| |
| Press the <TAB> key whenever you want GDB to fill out the rest of a |
| word. If there is only one possibility, GDB fills in the word, and |
| waits for you to finish the command (or press <RET> to enter it). For |
| example, if you type |
| |
| (gdb) info bre <TAB> |
| |
| GDB fills in the rest of the word `breakpoints', since that is the only |
| `info' subcommand beginning with `bre': |
| |
| (gdb) info breakpoints |
| |
| You can either press <RET> at this point, to run the `info breakpoints' |
| command, or backspace and enter something else, if `breakpoints' does |
| not look like the command you expected. (If you were sure you wanted |
| `info breakpoints' in the first place, you might as well just type |
| <RET> immediately after `info bre', to exploit command abbreviations |
| rather than command completion). |
| |
| If there is more than one possibility for the next word when you |
| press <TAB>, GDB sounds a bell. You can either supply more characters |
| and try again, or just press <TAB> a second time; GDB displays all the |
| possible completions for that word. For example, you might want to set |
| a breakpoint on a subroutine whose name begins with `make_', but when |
| you type `b make_<TAB>' GDB just sounds the bell. Typing <TAB> again |
| displays all the function names in your program that begin with those |
| characters, for example: |
| |
| (gdb) b make_ <TAB> |
| GDB sounds bell; press <TAB> again, to see: |
| make_a_section_from_file make_environ |
| make_abs_section make_function_type |
| make_blockvector make_pointer_type |
| make_cleanup make_reference_type |
| make_command make_symbol_completion_list |
| (gdb) b make_ |
| |
| After displaying the available possibilities, GDB copies your partial |
| input (`b make_' in the example) so you can finish the command. |
| |
| If you just want to see the list of alternatives in the first place, |
| you can press `M-?' rather than pressing <TAB> twice. `M-?' means |
| `<META> ?'. You can type this either by holding down a key designated |
| as the <META> shift on your keyboard (if there is one) while typing |
| `?', or as <ESC> followed by `?'. |
| |
| Sometimes the string you need, while logically a "word", may contain |
| parentheses or other characters that GDB normally excludes from its |
| notion of a word. To permit word completion to work in this situation, |
| you may enclose words in `'' (single quote marks) in GDB commands. |
| |
| The most likely situation where you might need this is in typing the |
| name of a C++ function. This is because C++ allows function |
| overloading (multiple definitions of the same function, distinguished |
| by argument type). For example, when you want to set a breakpoint you |
| may need to distinguish whether you mean the version of `name' that |
| takes an `int' parameter, `name(int)', or the version that takes a |
| `float' parameter, `name(float)'. To use the word-completion |
| facilities in this situation, type a single quote `'' at the beginning |
| of the function name. This alerts GDB that it may need to consider |
| more information than usual when you press <TAB> or `M-?' to request |
| word completion: |
| |
| (gdb) b 'bubble( M-? |
| bubble(double,double) bubble(int,int) |
| (gdb) b 'bubble( |
| |
| In some cases, GDB can tell that completing a name requires using |
| quotes. When this happens, GDB inserts the quote for you (while |
| completing as much as it can) if you do not type the quote in the first |
| place: |
| |
| (gdb) b bub <TAB> |
| GDB alters your input line to the following, and rings a bell: |
| (gdb) b 'bubble( |
| |
| In general, GDB can tell that a quote is needed (and inserts it) if you |
| have not yet started typing the argument list when you ask for |
| completion on an overloaded symbol. |
| |
| For more information about overloaded functions, see *note C++ |
| Expressions: C Plus Plus Expressions. You can use the command `set |
| overload-resolution off' to disable overload resolution; see *note GDB |
| Features for C++: Debugging C Plus Plus. |
| |
| |
| File: gdb.info, Node: Help, Prev: Completion, Up: Commands |
| |
| 3.3 Getting Help |
| ================ |
| |
| You can always ask GDB itself for information on its commands, using |
| the command `help'. |
| |
| `help' |
| `h' |
| You can use `help' (abbreviated `h') with no arguments to display |
| a short list of named classes of commands: |
| |
| (gdb) help |
| List of classes of commands: |
| |
| aliases -- Aliases of other commands |
| breakpoints -- Making program stop at certain points |
| data -- Examining data |
| files -- Specifying and examining files |
| internals -- Maintenance commands |
| obscure -- Obscure features |
| running -- Running the program |
| stack -- Examining the stack |
| status -- Status inquiries |
| support -- Support facilities |
| tracepoints -- Tracing of program execution without |
| stopping the program |
| user-defined -- User-defined commands |
| |
| Type "help" followed by a class name for a list of |
| commands in that class. |
| Type "help" followed by command name for full |
| documentation. |
| Command name abbreviations are allowed if unambiguous. |
| (gdb) |
| |
| `help CLASS' |
| Using one of the general help classes as an argument, you can get a |
| list of the individual commands in that class. For example, here |
| is the help display for the class `status': |
| |
| (gdb) help status |
| Status inquiries. |
| |
| List of commands: |
| |
| info -- Generic command for showing things |
| about the program being debugged |
| show -- Generic command for showing things |
| about the debugger |
| |
| Type "help" followed by command name for full |
| documentation. |
| Command name abbreviations are allowed if unambiguous. |
| (gdb) |
| |
| `help COMMAND' |
| With a command name as `help' argument, GDB displays a short |
| paragraph on how to use that command. |
| |
| `apropos ARGS' |
| The `apropos' command searches through all of the GDB commands, |
| and their documentation, for the regular expression specified in |
| ARGS. It prints out all matches found. For example: |
| |
| apropos reload |
| |
| results in: |
| |
| set symbol-reloading -- Set dynamic symbol table reloading |
| multiple times in one run |
| show symbol-reloading -- Show dynamic symbol table reloading |
| multiple times in one run |
| |
| `complete ARGS' |
| The `complete ARGS' command lists all the possible completions for |
| the beginning of a command. Use ARGS to specify the beginning of |
| the command you want completed. For example: |
| |
| complete i |
| |
| results in: |
| |
| if |
| ignore |
| info |
| inspect |
| |
| This is intended for use by GNU Emacs. |
| |
| In addition to `help', you can use the GDB commands `info' and |
| `show' to inquire about the state of your program, or the state of GDB |
| itself. Each command supports many topics of inquiry; this manual |
| introduces each of them in the appropriate context. The listings under |
| `info' and under `show' in the Index point to all the sub-commands. |
| *Note Index::. |
| |
| `info' |
| This command (abbreviated `i') is for describing the state of your |
| program. For example, you can show the arguments passed to a |
| function with `info args', list the registers currently in use |
| with `info registers', or list the breakpoints you have set with |
| `info breakpoints'. You can get a complete list of the `info' |
| sub-commands with `help info'. |
| |
| `set' |
| You can assign the result of an expression to an environment |
| variable with `set'. For example, you can set the GDB prompt to a |
| $-sign with `set prompt $'. |
| |
| `show' |
| In contrast to `info', `show' is for describing the state of GDB |
| itself. You can change most of the things you can `show', by |
| using the related command `set'; for example, you can control what |
| number system is used for displays with `set radix', or simply |
| inquire which is currently in use with `show radix'. |
| |
| To display all the settable parameters and their current values, |
| you can use `show' with no arguments; you may also use `info set'. |
| Both commands produce the same display. |
| |
| Here are three miscellaneous `show' subcommands, all of which are |
| exceptional in lacking corresponding `set' commands: |
| |
| `show version' |
| Show what version of GDB is running. You should include this |
| information in GDB bug-reports. If multiple versions of GDB are |
| in use at your site, you may need to determine which version of |
| GDB you are running; as GDB evolves, new commands are introduced, |
| and old ones may wither away. Also, many system vendors ship |
| variant versions of GDB, and there are variant versions of GDB in |
| GNU/Linux distributions as well. The version number is the same |
| as the one announced when you start GDB. |
| |
| `show copying' |
| `info copying' |
| Display information about permission for copying GDB. |
| |
| `show warranty' |
| `info warranty' |
| Display the GNU "NO WARRANTY" statement, or a warranty, if your |
| version of GDB comes with one. |
| |
| |
| |
| File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top |
| |
| 4 Running Programs Under GDB |
| **************************** |
| |
| When you run a program under GDB, you must first generate debugging |
| information when you compile it. |
| |
| You may start GDB with its arguments, if any, in an environment of |
| your choice. If you are doing native debugging, you may redirect your |
| program's input and output, debug an already running process, or kill a |
| child process. |
| |
| * Menu: |
| |
| * Compilation:: Compiling for debugging |
| * Starting:: Starting your program |
| * Arguments:: Your program's arguments |
| * Environment:: Your program's environment |
| |
| * Working Directory:: Your program's working directory |
| * Input/Output:: Your program's input and output |
| * Attach:: Debugging an already-running process |
| * Kill Process:: Killing the child process |
| |
| * Threads:: Debugging programs with multiple threads |
| * Processes:: Debugging programs with multiple processes |
| * Checkpoint/Restart:: Setting a _bookmark_ to return to later |
| |
| |
| File: gdb.info, Node: Compilation, Next: Starting, Up: Running |
| |
| 4.1 Compiling for Debugging |
| =========================== |
| |
| In order to debug a program effectively, you need to generate debugging |
| information when you compile it. This debugging information is stored |
| in the object file; it describes the data type of each variable or |
| function and the correspondence between source line numbers and |
| addresses in the executable code. |
| |
| To request debugging information, specify the `-g' option when you |
| run the compiler. |
| |
| Programs that are to be shipped to your customers are compiled with |
| optimizations, using the `-O' compiler option. However, many compilers |
| are unable to handle the `-g' and `-O' options together. Using those |
| compilers, you cannot generate optimized executables containing |
| debugging information. |
| |
| GCC, the GNU C/C++ compiler, supports `-g' with or without `-O', |
| making it possible to debug optimized code. We recommend that you |
| _always_ use `-g' whenever you compile a program. You may think your |
| program is correct, but there is no sense in pushing your luck. |
| |
| When you debug a program compiled with `-g -O', remember that the |
| optimizer is rearranging your code; the debugger shows you what is |
| really there. Do not be too surprised when the execution path does not |
| exactly match your source file! An extreme example: if you define a |
| variable, but never use it, GDB never sees that variable--because the |
| compiler optimizes it out of existence. |
| |
| Some things do not work as well with `-g -O' as with just `-g', |
| particularly on machines with instruction scheduling. If in doubt, |
| recompile with `-g' alone, and if this fixes the problem, please report |
| it to us as a bug (including a test case!). *Note Variables::, for |
| more information about debugging optimized code. |
| |
| Older versions of the GNU C compiler permitted a variant option |
| `-gg' for debugging information. GDB no longer supports this format; |
| if your GNU C compiler has this option, do not use it. |
| |
| GDB knows about preprocessor macros and can show you their expansion |
| (*note Macros::). Most compilers do not include information about |
| preprocessor macros in the debugging information if you specify the |
| `-g' flag alone, because this information is rather large. Version 3.1 |
| and later of GCC, the GNU C compiler, provides macro information if you |
| specify the options `-gdwarf-2' and `-g3'; the former option requests |
| debugging information in the Dwarf 2 format, and the latter requests |
| "extra information". In the future, we hope to find more compact ways |
| to represent macro information, so that it can be included with `-g' |
| alone. |
| |
| |
| File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running |
| |
| 4.2 Starting your Program |
| ========================= |
| |
| `run' |
| `r' |
| Use the `run' command to start your program under GDB. You must |
| first specify the program name (except on VxWorks) with an |
| argument to GDB (*note Getting In and Out of GDB: Invocation.), or |
| by using the `file' or `exec-file' command (*note Commands to |
| Specify Files: Files.). |
| |
| |
| If you are running your program in an execution environment that |
| supports processes, `run' creates an inferior process and makes that |
| process run your program. (In environments without processes, `run' |
| jumps to the start of your program.) |
| |
| The execution of a program is affected by certain information it |
| receives from its superior. GDB provides ways to specify this |
| information, which you must do _before_ starting your program. (You |
| can change it after starting your program, but such changes only affect |
| your program the next time you start it.) This information may be |
| divided into four categories: |
| |
| The _arguments._ |
| Specify the arguments to give your program as the arguments of the |
| `run' command. If a shell is available on your target, the shell |
| is used to pass the arguments, so that you may use normal |
| conventions (such as wildcard expansion or variable substitution) |
| in describing the arguments. In Unix systems, you can control |
| which shell is used with the `SHELL' environment variable. *Note |
| Your Program's Arguments: Arguments. |
| |
| The _environment._ |
| Your program normally inherits its environment from GDB, but you |
| can use the GDB commands `set environment' and `unset environment' |
| to change parts of the environment that affect your program. |
| *Note Your Program's Environment: Environment. |
| |
| The _working directory._ |
| Your program inherits its working directory from GDB. You can set |
| the GDB working directory with the `cd' command in GDB. *Note |
| Your Program's Working Directory: Working Directory. |
| |
| The _standard input and output._ |
| Your program normally uses the same device for standard input and |
| standard output as GDB is using. You can redirect input and output |
| in the `run' command line, or you can use the `tty' command to set |
| a different device for your program. *Note Your Program's Input |
| and Output: Input/Output. |
| |
| _Warning:_ While input and output redirection work, you cannot use |
| pipes to pass the output of the program you are debugging to |
| another program; if you attempt this, GDB is likely to wind up |
| debugging the wrong program. |
| |
| When you issue the `run' command, your program begins to execute |
| immediately. *Note Stopping and Continuing: Stopping, for discussion |
| of how to arrange for your program to stop. Once your program has |
| stopped, you may call functions in your program, using the `print' or |
| `call' commands. *Note Examining Data: Data. |
| |
| If the modification time of your symbol file has changed since the |
| last time GDB read its symbols, GDB discards its symbol table, and |
| reads it again. When it does this, GDB tries to retain your current |
| breakpoints. |
| |
| `start' |
| The name of the main procedure can vary from language to language. |
| With C or C++, the main procedure name is always `main', but other |
| languages such as Ada do not require a specific name for their |
| main procedure. The debugger provides a convenient way to start |
| the execution of the program and to stop at the beginning of the |
| main procedure, depending on the language used. |
| |
| The `start' command does the equivalent of setting a temporary |
| breakpoint at the beginning of the main procedure and then invoking |
| the `run' command. |
| |
| Some programs contain an "elaboration" phase where some startup |
| code is executed before the main procedure is called. This |
| depends on the languages used to write your program. In C++, for |
| instance, constructors for static and global objects are executed |
| before `main' is called. It is therefore possible that the |
| debugger stops before reaching the main procedure. However, the |
| temporary breakpoint will remain to halt execution. |
| |
| Specify the arguments to give to your program as arguments to the |
| `start' command. These arguments will be given verbatim to the |
| underlying `run' command. Note that the same arguments will be |
| reused if no argument is provided during subsequent calls to |
| `start' or `run'. |
| |
| It is sometimes necessary to debug the program during elaboration. |
| In these cases, using the `start' command would stop the execution |
| of your program too late, as the program would have already |
| completed the elaboration phase. Under these circumstances, |
| insert breakpoints in your elaboration code before running your |
| program. |
| |
| |
| File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running |
| |
| 4.3 Your Program's Arguments |
| ============================ |
| |
| The arguments to your program can be specified by the arguments of the |
| `run' command. They are passed to a shell, which expands wildcard |
| characters and performs redirection of I/O, and thence to your program. |
| Your `SHELL' environment variable (if it exists) specifies what shell |
| GDB uses. If you do not define `SHELL', GDB uses the default shell |
| (`/bin/sh' on Unix). |
| |
| On non-Unix systems, the program is usually invoked directly by GDB, |
| which emulates I/O redirection via the appropriate system calls, and |
| the wildcard characters are expanded by the startup code of the |
| program, not by the shell. |
| |
| `run' with no arguments uses the same arguments used by the previous |
| `run', or those set by the `set args' command. |
| |
| `set args' |
| Specify the arguments to be used the next time your program is |
| run. If `set args' has no arguments, `run' executes your program |
| with no arguments. Once you have run your program with arguments, |
| using `set args' before the next `run' is the only way to run it |
| again without arguments. |
| |
| `show args' |
| Show the arguments to give your program when it is started. |
| |
| |
| File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running |
| |
| 4.4 Your Program's Environment |
| ============================== |
| |
| The "environment" consists of a set of environment variables and their |
| values. Environment variables conventionally record such things as |
| your user name, your home directory, your terminal type, and your search |
| path for programs to run. Usually you set up environment variables with |
| the shell and they are inherited by all the other programs you run. |
| When debugging, it can be useful to try running your program with a |
| modified environment without having to start GDB over again. |
| |
| `path DIRECTORY' |
| Add DIRECTORY to the front of the `PATH' environment variable (the |
| search path for executables) that will be passed to your program. |
| The value of `PATH' used by GDB does not change. You may specify |
| several directory names, separated by whitespace or by a |
| system-dependent separator character (`:' on Unix, `;' on MS-DOS |
| and MS-Windows). If DIRECTORY is already in the path, it is moved |
| to the front, so it is searched sooner. |
| |
| You can use the string `$cwd' to refer to whatever is the current |
| working directory at the time GDB searches the path. If you use |
| `.' instead, it refers to the directory where you executed the |
| `path' command. GDB replaces `.' in the DIRECTORY argument (with |
| the current path) before adding DIRECTORY to the search path. |
| |
| `show paths' |
| Display the list of search paths for executables (the `PATH' |
| environment variable). |
| |
| `show environment [VARNAME]' |
| Print the value of environment variable VARNAME to be given to |
| your program when it starts. If you do not supply VARNAME, print |
| the names and values of all environment variables to be given to |
| your program. You can abbreviate `environment' as `env'. |
| |
| `set environment VARNAME [=VALUE]' |
| Set environment variable VARNAME to VALUE. The value changes for |
| your program only, not for GDB itself. VALUE may be any string; |
| the values of environment variables are just strings, and any |
| interpretation is supplied by your program itself. The VALUE |
| parameter is optional; if it is eliminated, the variable is set to |
| a null value. |
| |
| For example, this command: |
| |
| set env USER = foo |
| |
| tells the debugged program, when subsequently run, that its user |
| is named `foo'. (The spaces around `=' are used for clarity here; |
| they are not actually required.) |
| |
| `unset environment VARNAME' |
| Remove variable VARNAME from the environment to be passed to your |
| program. This is different from `set env VARNAME ='; `unset |
| environment' removes the variable from the environment, rather |
| than assigning it an empty value. |
| |
| _Warning:_ On Unix systems, GDB runs your program using the shell |
| indicated by your `SHELL' environment variable if it exists (or |
| `/bin/sh' if not). If your `SHELL' variable names a shell that runs an |
| initialization file--such as `.cshrc' for C-shell, or `.bashrc' for |
| BASH--any variables you set in that file affect your program. You may |
| wish to move setting of environment variables to files that are only |
| run when you sign on, such as `.login' or `.profile'. |
| |
| |
| File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running |
| |
| 4.5 Your Program's Working Directory |
| ==================================== |
| |
| Each time you start your program with `run', it inherits its working |
| directory from the current working directory of GDB. The GDB working |
| directory is initially whatever it inherited from its parent process |
| (typically the shell), but you can specify a new working directory in |
| GDB with the `cd' command. |
| |
| The GDB working directory also serves as a default for the commands |
| that specify files for GDB to operate on. *Note Commands to Specify |
| Files: Files. |
| |
| `cd DIRECTORY' |
| Set the GDB working directory to DIRECTORY. |
| |
| `pwd' |
| Print the GDB working directory. |
| |
| It is generally impossible to find the current working directory of |
| the process being debugged (since a program can change its directory |
| during its run). If you work on a system where GDB is configured with |
| the `/proc' support, you can use the `info proc' command (*note SVR4 |
| Process Information::) to find out the current working directory of the |
| debuggee. |
| |
| |
| File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running |
| |
| 4.6 Your Program's Input and Output |
| =================================== |
| |
| By default, the program you run under GDB does input and output to the |
| same terminal that GDB uses. GDB switches the terminal to its own |
| terminal modes to interact with you, but it records the terminal modes |
| your program was using and switches back to them when you continue |
| running your program. |
| |
| `info terminal' |
| Displays information recorded by GDB about the terminal modes your |
| program is using. |
| |
| You can redirect your program's input and/or output using shell |
| redirection with the `run' command. For example, |
| |
| run > outfile |
| |
| starts your program, diverting its output to the file `outfile'. |
| |
| Another way to specify where your program should do input and output |
| is with the `tty' command. This command accepts a file name as |
| argument, and causes this file to be the default for future `run' |
| commands. It also resets the controlling terminal for the child |
| process, for future `run' commands. For example, |
| |
| tty /dev/ttyb |
| |
| directs that processes started with subsequent `run' commands default |
| to do input and output on the terminal `/dev/ttyb' and have that as |
| their controlling terminal. |
| |
| An explicit redirection in `run' overrides the `tty' command's |
| effect on the input/output device, but not its effect on the controlling |
| terminal. |
| |
| When you use the `tty' command or redirect input in the `run' |
| command, only the input _for your program_ is affected. The input for |
| GDB still comes from your terminal. `tty' is an alias for `set |
| inferior-tty'. |
| |
| You can use the `show inferior-tty' command to tell GDB to display |
| the name of the terminal that will be used for future runs of your |
| program. |
| |
| `set inferior-tty /dev/ttyb' |
| Set the tty for the program being debugged to /dev/ttyb. |
| |
| `show inferior-tty' |
| Show the current tty for the program being debugged. |
| |
| |
| File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running |
| |
| 4.7 Debugging an Already-running Process |
| ======================================== |
| |
| `attach PROCESS-ID' |
| This command attaches to a running process--one that was started |
| outside GDB. (`info files' shows your active targets.) The |
| command takes as argument a process ID. The usual way to find out |
| the PROCESS-ID of a Unix process is with the `ps' utility, or with |
| the `jobs -l' shell command. |
| |
| `attach' does not repeat if you press <RET> a second time after |
| executing the command. |
| |
| To use `attach', your program must be running in an environment |
| which supports processes; for example, `attach' does not work for |
| programs on bare-board targets that lack an operating system. You must |
| also have permission to send the process a signal. |
| |
| When you use `attach', the debugger finds the program running in the |
| process first by looking in the current working directory, then (if the |
| program is not found) by using the source file search path (*note |
| Specifying Source Directories: Source Path.). You can also use the |
| `file' command to load the program. *Note Commands to Specify Files: |
| Files. |
| |
| The first thing GDB does after arranging to debug the specified |
| process is to stop it. You can examine and modify an attached process |
| with all the GDB commands that are ordinarily available when you start |
| processes with `run'. You can insert breakpoints; you can step and |
| continue; you can modify storage. If you would rather the process |
| continue running, you may use the `continue' command after attaching |
| GDB to the process. |
| |
| `detach' |
| When you have finished debugging the attached process, you can use |
| the `detach' command to release it from GDB control. Detaching |
| the process continues its execution. After the `detach' command, |
| that process and GDB become completely independent once more, and |
| you are ready to `attach' another process or start one with `run'. |
| `detach' does not repeat if you press <RET> again after executing |
| the command. |
| |
| If you exit GDB while you have an attached process, you detach that |
| process. If you use the `run' command, you kill that process. By |
| default, GDB asks for confirmation if you try to do either of these |
| things; you can control whether or not you need to confirm by using the |
| `set confirm' command (*note Optional Warnings and Messages: |
| Messages/Warnings.). |
| |
| |
| File: gdb.info, Node: Kill Process, Next: Threads, Prev: Attach, Up: Running |
| |
| 4.8 Killing the Child Process |
| ============================= |
| |
| `kill' |
| Kill the child process in which your program is running under GDB. |
| |
| This command is useful if you wish to debug a core dump instead of a |
| running process. GDB ignores any core dump file while your program is |
| running. |
| |
| On some operating systems, a program cannot be executed outside GDB |
| while you have breakpoints set on it inside GDB. You can use the |
| `kill' command in this situation to permit running your program outside |
| the debugger. |
| |
| The `kill' command is also useful if you wish to recompile and |
| relink your program, since on many systems it is impossible to modify an |
| executable file while it is running in a process. In this case, when |
| you next type `run', GDB notices that the file has changed, and reads |
| the symbol table again (while trying to preserve your current |
| breakpoint settings). |
| |
| |
| File: gdb.info, Node: Threads, Next: Processes, Prev: Kill Process, Up: Running |
| |
| 4.9 Debugging Programs with Multiple Threads |
| ============================================ |
| |
| In some operating systems, such as HP-UX and Solaris, a single program |
| may have more than one "thread" of execution. The precise semantics of |
| threads differ from one operating system to another, but in general the |
| threads of a single program are akin to multiple processes--except that |
| they share one address space (that is, they can all examine and modify |
| the same variables). On the other hand, each thread has its own |
| registers and execution stack, and perhaps private memory. |
| |
| GDB provides these facilities for debugging multi-thread programs: |
| |
| * automatic notification of new threads |
| |
| * `thread THREADNO', a command to switch among threads |
| |
| * `info threads', a command to inquire about existing threads |
| |
| * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command |
| to a list of threads |
| |
| * thread-specific breakpoints |
| |
| * `set print thread-events', which controls printing of messages on |
| thread start and exit. |
| |
| _Warning:_ These facilities are not yet available on every GDB |
| configuration where the operating system supports threads. If |
| your GDB does not support threads, these commands have no effect. |
| For example, a system without thread support shows no output from |
| `info threads', and always rejects the `thread' command, like this: |
| |
| (gdb) info threads |
| (gdb) thread 1 |
| Thread ID 1 not known. Use the "info threads" command to |
| see the IDs of currently known threads. |
| |
| The GDB thread debugging facility allows you to observe all threads |
| while your program runs--but whenever GDB takes control, one thread in |
| particular is always the focus of debugging. This thread is called the |
| "current thread". Debugging commands show program information from the |
| perspective of the current thread. |
| |
| Whenever GDB detects a new thread in your program, it displays the |
| target system's identification for the thread with a message in the |
| form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies |
| depending on the particular system. For example, on GNU/Linux, you |
| might see |
| |
| [New Thread 46912507313328 (LWP 25582)] |
| |
| when GDB notices a new thread. In contrast, on an SGI system, the |
| SYSTAG is simply something like `process 368', with no further |
| qualifier. |
| |
| For debugging purposes, GDB associates its own thread number--always |
| a single integer--with each thread in your program. |
| |
| `info threads' |
| Display a summary of all threads currently in your program. GDB |
| displays for each thread (in this order): |
| |
| 1. the thread number assigned by GDB |
| |
| 2. the target system's thread identifier (SYSTAG) |
| |
| 3. the current stack frame summary for that thread |
| |
| An asterisk `*' to the left of the GDB thread number indicates the |
| current thread. |
| |
| For example, |
| |
| (gdb) info threads |
| 3 process 35 thread 27 0x34e5 in sigpause () |
| 2 process 35 thread 23 0x34e5 in sigpause () |
| * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) |
| at threadtest.c:68 |
| |
| On HP-UX systems: |
| |
| For debugging purposes, GDB associates its own thread number--a |
| small integer assigned in thread-creation order--with each thread in |
| your program. |
| |
| Whenever GDB detects a new thread in your program, it displays both |
| GDB's thread number and the target system's identification for the |
| thread with a message in the form `[New SYSTAG]'. SYSTAG is a thread |
| identifier whose form varies depending on the particular system. For |
| example, on HP-UX, you see |
| |
| [New thread 2 (system thread 26594)] |
| |
| when GDB notices a new thread. |
| |
| `info threads' |
| Display a summary of all threads currently in your program. GDB |
| displays for each thread (in this order): |
| |
| 1. the thread number assigned by GDB |
| |
| 2. the target system's thread identifier (SYSTAG) |
| |
| 3. the current stack frame summary for that thread |
| |
| An asterisk `*' to the left of the GDB thread number indicates the |
| current thread. |
| |
| For example, |
| |
| (gdb) info threads |
| * 3 system thread 26607 worker (wptr=0x7b09c318 "@") \ |
| |
| at quicksort.c:137 |
| 2 system thread 26606 0x7b0030d8 in __ksleep () \ |
| |
| from /usr/lib/libc.2 |
| 1 system thread 27905 0x7b003498 in _brk () \ |
| |
| from /usr/lib/libc.2 |
| |
| On Solaris, you can display more information about user threads with |
| a Solaris-specific command: |
| |
| `maint info sol-threads' |
| Display info on Solaris user threads. |
| |
| `thread THREADNO' |
| Make thread number THREADNO the current thread. The command |
| argument THREADNO is the internal GDB thread number, as shown in |
| the first field of the `info threads' display. GDB responds by |
| displaying the system identifier of the thread you selected, and |
| its current stack frame summary: |
| |
| (gdb) thread 2 |
| [Switching to process 35 thread 23] |
| 0x34e5 in sigpause () |
| |
| As with the `[New ...]' message, the form of the text after |
| `Switching to' depends on your system's conventions for identifying |
| threads. |
| |
| `thread apply [THREADNO] [ALL] COMMAND' |
| The `thread apply' command allows you to apply the named COMMAND |
| to one or more threads. Specify the numbers of the threads that |
| you want affected with the command argument THREADNO. It can be a |
| single thread number, one of the numbers shown in the first field |
| of the `info threads' display; or it could be a range of thread |
| numbers, as in `2-4'. To apply a command to all threads, type |
| `thread apply all COMMAND'. |
| |
| `set print thread-events' |
| `set print thread-events on' |
| `set print thread-events off' |
| The `set print thread-events' command allows you to enable or |
| disable printing of messages when GDB notices that new threads have |
| started or that threads have exited. By default, these messages |
| will be printed if detection of these events is supported by the |
| target. Note that these messages cannot be disabled on all |
| targets. |
| |
| `show print thread-events' |
| Show whether messages will be printed when GDB detects that threads |
| have started and exited. |
| |
| Whenever GDB stops your program, due to a breakpoint or a signal, it |
| automatically selects the thread where that breakpoint or signal |
| happened. GDB alerts you to the context switch with a message of the |
| form `[Switching to SYSTAG]' to identify the thread. |
| |
| *Note Stopping and Starting Multi-thread Programs: Thread Stops, for |
| more information about how GDB behaves when you stop and start programs |
| with multiple threads. |
| |
| *Note Setting Watchpoints: Set Watchpoints, for information about |
| watchpoints in programs with multiple threads. |
| |
| |
| File: gdb.info, Node: Processes, Next: Checkpoint/Restart, Prev: Threads, Up: Running |
| |
| 4.10 Debugging Programs with Multiple Processes |
| =============================================== |
| |
| On most systems, GDB has no special support for debugging programs |
| which create additional processes using the `fork' function. When a |
| program forks, GDB will continue to debug the parent process and the |
| child process will run unimpeded. If you have set a breakpoint in any |
| code which the child then executes, the child will get a `SIGTRAP' |
| signal which (unless it catches the signal) will cause it to terminate. |
| |
| However, if you want to debug the child process there is a workaround |
| which isn't too painful. Put a call to `sleep' in the code which the |
| child process executes after the fork. It may be useful to sleep only |
| if a certain environment variable is set, or a certain file exists, so |
| that the delay need not occur when you don't want to run GDB on the |
| child. While the child is sleeping, use the `ps' program to get its |
| process ID. Then tell GDB (a new invocation of GDB if you are also |
| debugging the parent process) to attach to the child process (*note |
| Attach::). From that point on you can debug the child process just |
| like any other process which you attached to. |
| |
| On some systems, GDB provides support for debugging programs that |
| create additional processes using the `fork' or `vfork' functions. |
| Currently, the only platforms with this feature are HP-UX (11.x and |
| later only?) and GNU/Linux (kernel version 2.5.60 and later). |
| |
| By default, when a program forks, GDB will continue to debug the |
| parent process and the child process will run unimpeded. |
| |
| If you want to follow the child process instead of the parent |
| process, use the command `set follow-fork-mode'. |
| |
| `set follow-fork-mode MODE' |
| Set the debugger response to a program call of `fork' or `vfork'. |
| A call to `fork' or `vfork' creates a new process. The MODE |
| argument can be: |
| |
| `parent' |
| The original process is debugged after a fork. The child |
| process runs unimpeded. This is the default. |
| |
| `child' |
| The new process is debugged after a fork. The parent process |
| runs unimpeded. |
| |
| |
| `show follow-fork-mode' |
| Display the current debugger response to a `fork' or `vfork' call. |
| |
| On Linux, if you want to debug both the parent and child processes, |
| use the command `set detach-on-fork'. |
| |
| `set detach-on-fork MODE' |
| Tells gdb whether to detach one of the processes after a fork, or |
| retain debugger control over them both. |
| |
| `on' |
| The child process (or parent process, depending on the value |
| of `follow-fork-mode') will be detached and allowed to run |
| independently. This is the default. |
| |
| `off' |
| Both processes will be held under the control of GDB. One |
| process (child or parent, depending on the value of |
| `follow-fork-mode') is debugged as usual, while the other is |
| held suspended. |
| |
| |
| `show detach-on-fork' |
| Show whether detach-on-fork mode is on/off. |
| |
| If you choose to set `detach-on-fork' mode off, then GDB will retain |
| control of all forked processes (including nested forks). You can list |
| the forked processes under the control of GDB by using the `info forks' |
| command, and switch from one fork to another by using the `fork' |
| command. |
| |
| `info forks' |
| Print a list of all forked processes under the control of GDB. |
| The listing will include a fork id, a process id, and the current |
| position (program counter) of the process. |
| |
| `fork FORK-ID' |
| Make fork number FORK-ID the current process. The argument |
| FORK-ID is the internal fork number assigned by GDB, as shown in |
| the first field of the `info forks' display. |
| |
| `process PROCESS-ID' |
| Make process number PROCESS-ID the current process. The argument |
| PROCESS-ID must be one that is listed in the output of `info |
| forks'. |
| |
| |
| To quit debugging one of the forked processes, you can either detach |
| from it by using the `detach fork' command (allowing it to run |
| independently), or delete (and kill) it using the `delete fork' command. |
| |
| `detach fork FORK-ID' |
| Detach from the process identified by GDB fork number FORK-ID, and |
| remove it from the fork list. The process will be allowed to run |
| independently. |
| |
| `delete fork FORK-ID' |
| Kill the process identified by GDB fork number FORK-ID, and remove |
| it from the fork list. |
| |
| |
| If you ask to debug a child process and a `vfork' is followed by an |
| `exec', GDB executes the new target up to the first breakpoint in the |
| new target. If you have a breakpoint set on `main' in your original |
| program, the breakpoint will also be set on the child process's `main'. |
| |
| When a child process is spawned by `vfork', you cannot debug the |
| child or parent until an `exec' call completes. |
| |
| If you issue a `run' command to GDB after an `exec' call executes, |
| the new target restarts. To restart the parent process, use the `file' |
| command with the parent executable name as its argument. |
| |
| You can use the `catch' command to make GDB stop whenever a `fork', |
| `vfork', or `exec' call is made. *Note Setting Catchpoints: Set |
| Catchpoints. |
| |
| |
| File: gdb.info, Node: Checkpoint/Restart, Prev: Processes, Up: Running |
| |
| 4.11 Setting a _Bookmark_ to Return to Later |
| ============================================ |
| |
| On certain operating systems(1), GDB is able to save a "snapshot" of a |
| program's state, called a "checkpoint", and come back to it later. |
| |
| Returning to a checkpoint effectively undoes everything that has |
| happened in the program since the `checkpoint' was saved. This |
| includes changes in memory, registers, and even (within some limits) |
| system state. Effectively, it is like going back in time to the moment |
| when the checkpoint was saved. |
| |
| Thus, if you're stepping thru a program and you think you're getting |
| close to the point where things go wrong, you can save a checkpoint. |
| Then, if you accidentally go too far and miss the critical statement, |
| instead of having to restart your program from the beginning, you can |
| just go back to the checkpoint and start again from there. |
| |
| This can be especially useful if it takes a lot of time or steps to |
| reach the point where you think the bug occurs. |
| |
| To use the `checkpoint'/`restart' method of debugging: |
| |
| `checkpoint' |
| Save a snapshot of the debugged program's current execution state. |
| The `checkpoint' command takes no arguments, but each checkpoint |
| is assigned a small integer id, similar to a breakpoint id. |
| |
| `info checkpoints' |
| List the checkpoints that have been saved in the current debugging |
| session. For each checkpoint, the following information will be |
| listed: |
| |
| `Checkpoint ID' |
| |
| `Process ID' |
| |
| `Code Address' |
| |
| `Source line, or label' |
| |
| `restart CHECKPOINT-ID' |
| Restore the program state that was saved as checkpoint number |
| CHECKPOINT-ID. All program variables, registers, stack frames |
| etc. will be returned to the values that they had when the |
| checkpoint was saved. In essence, gdb will "wind back the clock" |
| to the point in time when the checkpoint was saved. |
| |
| Note that breakpoints, GDB variables, command history etc. are |
| not affected by restoring a checkpoint. In general, a checkpoint |
| only restores things that reside in the program being debugged, |
| not in the debugger. |
| |
| `delete checkpoint CHECKPOINT-ID' |
| Delete the previously-saved checkpoint identified by CHECKPOINT-ID. |
| |
| |
| Returning to a previously saved checkpoint will restore the user |
| state of the program being debugged, plus a significant subset of the |
| system (OS) state, including file pointers. It won't "un-write" data |
| from a file, but it will rewind the file pointer to the previous |
| location, so that the previously written data can be overwritten. For |
| files opened in read mode, the pointer will also be restored so that the |
| previously read data can be read again. |
| |
| Of course, characters that have been sent to a printer (or other |
| external device) cannot be "snatched back", and characters received |
| from eg. a serial device can be removed from internal program buffers, |
| but they cannot be "pushed back" into the serial pipeline, ready to be |
| received again. Similarly, the actual contents of files that have been |
| changed cannot be restored (at this time). |
| |
| However, within those constraints, you actually can "rewind" your |
| program to a previously saved point in time, and begin debugging it |
| again -- and you can change the course of events so as to debug a |
| different execution path this time. |
| |
| Finally, there is one bit of internal program state that will be |
| different when you return to a checkpoint -- the program's process id. |
| Each checkpoint will have a unique process id (or PID), and each will |
| be different from the program's original PID. If your program has |
| saved a local copy of its process id, this could potentially pose a |
| problem. |
| |
| 4.11.1 A Non-obvious Benefit of Using Checkpoints |
| ------------------------------------------------- |
| |
| On some systems such as GNU/Linux, address space randomization is |
| performed on new processes for security reasons. This makes it |
| difficult or impossible to set a breakpoint, or watchpoint, on an |
| absolute address if you have to restart the program, since the absolute |
| location of a symbol will change from one execution to the next. |
| |
| A checkpoint, however, is an _identical_ copy of a process. |
| Therefore if you create a checkpoint at (eg.) the start of main, and |
| simply return to that checkpoint instead of restarting the process, you |
| can avoid the effects of address randomization and your symbols will |
| all stay in the same place. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Currently, only GNU/Linux. |
| |
| |
| File: gdb.info, Node: Stopping, Next: Stack, Prev: Running, Up: Top |
| |
| 5 Stopping and Continuing |
| ************************* |
| |
| The principal purposes of using a debugger are so that you can stop your |
| program before it terminates; or so that, if your program runs into |
| trouble, you can investigate and find out why. |
| |
| Inside GDB, your program may stop for any of several reasons, such |
| as a signal, a breakpoint, or reaching a new line after a GDB command |
| such as `step'. You may then examine and change variables, set new |
| breakpoints or remove old ones, and then continue execution. Usually, |
| the messages shown by GDB provide ample explanation of the status of |
| your program--but you can also explicitly request this information at |
| any time. |
| |
| `info program' |
| Display information about the status of your program: whether it is |
| running or not, what process it is, and why it stopped. |
| |
| * Menu: |
| |
| * Breakpoints:: Breakpoints, watchpoints, and catchpoints |
| * Continuing and Stepping:: Resuming execution |
| * Signals:: Signals |
| * Thread Stops:: Stopping and starting multi-thread programs |
| |
| |
| File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping |
| |
| 5.1 Breakpoints, Watchpoints, and Catchpoints |
| ============================================= |
| |
| A "breakpoint" makes your program stop whenever a certain point in the |
| program is reached. For each breakpoint, you can add conditions to |
| control in finer detail whether your program stops. You can set |
| breakpoints with the `break' command and its variants (*note Setting |
| Breakpoints: Set Breaks.), to specify the place where your program |
| should stop by line number, function name or exact address in the |
| program. |
| |
| On some systems, you can set breakpoints in shared libraries before |
| the executable is run. There is a minor limitation on HP-UX systems: |
| you must wait until the executable is run in order to set breakpoints |
| in shared library routines that are not called directly by the program |
| (for example, routines that are arguments in a `pthread_create' call). |
| |
| A "watchpoint" is a special breakpoint that stops your program when |
| the value of an expression changes. The expression may be a value of a |
| variable, or it could involve values of one or more variables combined |
| by operators, such as `a + b'. This is sometimes called "data |
| breakpoints". You must use a different command to set watchpoints |
| (*note Setting Watchpoints: Set Watchpoints.), but aside from that, you |
| can manage a watchpoint like any other breakpoint: you enable, disable, |
| and delete both breakpoints and watchpoints using the same commands. |
| |
| You can arrange to have values from your program displayed |
| automatically whenever GDB stops at a breakpoint. *Note Automatic |
| Display: Auto Display. |
| |
| A "catchpoint" is another special breakpoint that stops your program |
| when a certain kind of event occurs, such as the throwing of a C++ |
| exception or the loading of a library. As with watchpoints, you use a |
| different command to set a catchpoint (*note Setting Catchpoints: Set |
| Catchpoints.), but aside from that, you can manage a catchpoint like any |
| other breakpoint. (To stop when your program receives a signal, use the |
| `handle' command; see *note Signals: Signals.) |
| |
| GDB assigns a number to each breakpoint, watchpoint, or catchpoint |
| when you create it; these numbers are successive integers starting with |
| one. In many of the commands for controlling various features of |
| breakpoints you use the breakpoint number to say which breakpoint you |
| want to change. Each breakpoint may be "enabled" or "disabled"; if |
| disabled, it has no effect on your program until you enable it again. |
| |
| Some GDB commands accept a range of breakpoints on which to operate. |
| A breakpoint range is either a single breakpoint number, like `5', or |
| two such numbers, in increasing order, separated by a hyphen, like |
| `5-7'. When a breakpoint range is given to a command, all breakpoints |
| in that range are operated on. |
| |
| * Menu: |
| |
| * Set Breaks:: Setting breakpoints |
| * Set Watchpoints:: Setting watchpoints |
| * Set Catchpoints:: Setting catchpoints |
| * Delete Breaks:: Deleting breakpoints |
| * Disabling:: Disabling breakpoints |
| * Conditions:: Break conditions |
| * Break Commands:: Breakpoint command lists |
| * Breakpoint Menus:: Breakpoint menus |
| * Error in Breakpoints:: ``Cannot insert breakpoints'' |
| * Breakpoint-related Warnings:: ``Breakpoint address adjusted...'' |
| |
| |
| File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints |
| |
| 5.1.1 Setting Breakpoints |
| ------------------------- |
| |
| Breakpoints are set with the `break' command (abbreviated `b'). The |
| debugger convenience variable `$bpnum' records the number of the |
| breakpoint you've set most recently; see *note Convenience Variables: |
| Convenience Vars, for a discussion of what you can do with convenience |
| variables. |
| |
| `break LOCATION' |
| Set a breakpoint at the given LOCATION, which can specify a |
| function name, a line number, or an address of an instruction. |
| (*Note Specify Location::, for a list of all the possible ways to |
| specify a LOCATION.) The breakpoint will stop your program just |
| before it executes any of the code in the specified LOCATION. |
| |
| When using source languages that permit overloading of symbols, |
| such as C++, a function name may refer to more than one possible |
| place to break. *Note Breakpoint Menus: Breakpoint Menus, for a |
| discussion of that situation. |
| |
| `break' |
| When called without any arguments, `break' sets a breakpoint at |
| the next instruction to be executed in the selected stack frame |
| (*note Examining the Stack: Stack.). In any selected frame but the |
| innermost, this makes your program stop as soon as control returns |
| to that frame. This is similar to the effect of a `finish' |
| command in the frame inside the selected frame--except that |
| `finish' does not leave an active breakpoint. If you use `break' |
| without an argument in the innermost frame, GDB stops the next |
| time it reaches the current location; this may be useful inside |
| loops. |
| |
| GDB normally ignores breakpoints when it resumes execution, until |
| at least one instruction has been executed. If it did not do |
| this, you would be unable to proceed past a breakpoint without |
| first disabling the breakpoint. This rule applies whether or not |
| the breakpoint already existed when your program stopped. |
| |
| `break ... if COND' |
| Set a breakpoint with condition COND; evaluate the expression COND |
| each time the breakpoint is reached, and stop only if the value is |
| nonzero--that is, if COND evaluates as true. `...' stands for one |
| of the possible arguments described above (or no argument) |
| specifying where to break. *Note Break Conditions: Conditions, |
| for more information on breakpoint conditions. |
| |
| `tbreak ARGS' |
| Set a breakpoint enabled only for one stop. ARGS are the same as |
| for the `break' command, and the breakpoint is set in the same |
| way, but the breakpoint is automatically deleted after the first |
| time your program stops there. *Note Disabling Breakpoints: |
| Disabling. |
| |
| `hbreak ARGS' |
| Set a hardware-assisted breakpoint. ARGS are the same as for the |
| `break' command and the breakpoint is set in the same way, but the |
| breakpoint requires hardware support and some target hardware may |
| not have this support. The main purpose of this is EPROM/ROM code |
| debugging, so you can set a breakpoint at an instruction without |
| changing the instruction. This can be used with the new |
| trap-generation provided by SPARClite DSU and most x86-based |
| targets. These targets will generate traps when a program |
| accesses some data or instruction address that is assigned to the |
| debug registers. However the hardware breakpoint registers can |
| take a limited number of breakpoints. For example, on the DSU, |
| only two data breakpoints can be set at a time, and GDB will |
| reject this command if more than two are used. Delete or disable |
| unused hardware breakpoints before setting new ones (*note |
| Disabling Breakpoints: Disabling.). *Note Break Conditions: |
| Conditions. For remote targets, you can restrict the number of |
| hardware breakpoints GDB will use, see *note set remote |
| hardware-breakpoint-limit::. |
| |
| `thbreak ARGS' |
| Set a hardware-assisted breakpoint enabled only for one stop. ARGS |
| are the same as for the `hbreak' command and the breakpoint is set |
| in the same way. However, like the `tbreak' command, the |
| breakpoint is automatically deleted after the first time your |
| program stops there. Also, like the `hbreak' command, the |
| breakpoint requires hardware support and some target hardware may |
| not have this support. *Note Disabling Breakpoints: Disabling. |
| See also *note Break Conditions: Conditions. |
| |
| `rbreak REGEX' |
| Set breakpoints on all functions matching the regular expression |
| REGEX. This command sets an unconditional breakpoint on all |
| matches, printing a list of all breakpoints it set. Once these |
| breakpoints are set, they are treated just like the breakpoints |
| set with the `break' command. You can delete them, disable them, |
| or make them conditional the same way as any other breakpoint. |
| |
| The syntax of the regular expression is the standard one used with |
| tools like `grep'. Note that this is different from the syntax |
| used by shells, so for instance `foo*' matches all functions that |
| include an `fo' followed by zero or more `o's. There is an |
| implicit `.*' leading and trailing the regular expression you |
| supply, so to match only functions that begin with `foo', use |
| `^foo'. |
| |
| When debugging C++ programs, `rbreak' is useful for setting |
| breakpoints on overloaded functions that are not members of any |
| special classes. |
| |
| The `rbreak' command can be used to set breakpoints in *all* the |
| functions in a program, like this: |
| |
| (gdb) rbreak . |
| |
| `info breakpoints [N]' |
| `info break [N]' |
| `info watchpoints [N]' |
| Print a table of all breakpoints, watchpoints, and catchpoints set |
| and not deleted. Optional argument N means print information only |
| about the specified breakpoint (or watchpoint or catchpoint). For |
| each breakpoint, following columns are printed: |
| |
| _Breakpoint Numbers_ |
| |
| _Type_ |
| Breakpoint, watchpoint, or catchpoint. |
| |
| _Disposition_ |
| Whether the breakpoint is marked to be disabled or deleted |
| when hit. |
| |
| _Enabled or Disabled_ |
| Enabled breakpoints are marked with `y'. `n' marks |
| breakpoints that are not enabled. |
| |
| _Address_ |
| Where the breakpoint is in your program, as a memory address. |
| For a pending breakpoint whose address is not yet known, this |
| field will contain `<PENDING>'. Such breakpoint won't fire |
| until a shared library that has the symbol or line referred |
| by breakpoint is loaded. See below for details. A |
| breakpoint with several locations will have `<MULTIPLE>' in |
| this field--see below for details. |
| |
| _What_ |
| Where the breakpoint is in the source for your program, as a |
| file and line number. For a pending breakpoint, the original |
| string passed to the breakpoint command will be listed as it |
| cannot be resolved until the appropriate shared library is |
| loaded in the future. |
| |
| If a breakpoint is conditional, `info break' shows the condition on |
| the line following the affected breakpoint; breakpoint commands, |
| if any, are listed after that. A pending breakpoint is allowed to |
| have a condition specified for it. The condition is not parsed |
| for validity until a shared library is loaded that allows the |
| pending breakpoint to resolve to a valid location. |
| |
| `info break' with a breakpoint number N as argument lists only |
| that breakpoint. The convenience variable `$_' and the default |
| examining-address for the `x' command are set to the address of |
| the last breakpoint listed (*note Examining Memory: Memory.). |
| |
| `info break' displays a count of the number of times the breakpoint |
| has been hit. This is especially useful in conjunction with the |
| `ignore' command. You can ignore a large number of breakpoint |
| hits, look at the breakpoint info to see how many times the |
| breakpoint was hit, and then run again, ignoring one less than |
| that number. This will get you quickly to the last hit of that |
| breakpoint. |
| |
| GDB allows you to set any number of breakpoints at the same place in |
| your program. There is nothing silly or meaningless about this. When |
| the breakpoints are conditional, this is even useful (*note Break |
| Conditions: Conditions.). |
| |
| It is possible that a breakpoint corresponds to several locations in |
| your program. Examples of this situation are: |
| |
| * For a C++ constructor, the GCC compiler generates several |
| instances of the function body, used in different cases. |
| |
| * For a C++ template function, a given line in the function can |
| correspond to any number of instantiations. |
| |
| * For an inlined function, a given source line can correspond to |
| several places where that function is inlined. |
| |
| |
| In all those cases, GDB will insert a breakpoint at all the relevant |
| locations. |
| |
| A breakpoint with multiple locations is displayed in the breakpoint |
| table using several rows--one header row, followed by one row for each |
| breakpoint location. The header row has `<MULTIPLE>' in the address |
| column. The rows for individual locations contain the actual addresses |
| for locations, and show the functions to which those locations belong. |
| The number column for a location is of the form |
| BREAKPOINT-NUMBER.LOCATION-NUMBER. |
| |
| For example: |
| |
| Num Type Disp Enb Address What |
| 1 breakpoint keep y <MULTIPLE> |
| stop only if i==1 |
| breakpoint already hit 1 time |
| 1.1 y 0x080486a2 in void foo<int>() at t.cc:8 |
| 1.2 y 0x080486ca in void foo<double>() at t.cc:8 |
| |
| Each location can be individually enabled or disabled by passing |
| BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the `enable' and |
| `disable' commands. Note that you cannot delete the individual |
| locations from the list, you can only delete the entire list of |
| locations that belong to their parent breakpoint (with the `delete NUM' |
| command, where NUM is the number of the parent breakpoint, 1 in the |
| above example). Disabling or enabling the parent breakpoint (*note |
| Disabling::) affects all of the locations that belong to that |
| breakpoint. |
| |
| It's quite common to have a breakpoint inside a shared library. |
| Shared libraries can be loaded and unloaded explicitly, and possibly |
| repeatedly, as the program is executed. To support this use case, GDB |
| updates breakpoint locations whenever any shared library is loaded or |
| unloaded. Typically, you would set a breakpoint in a shared library at |
| the beginning of your debugging session, when the library is not |
| loaded, and when the symbols from the library are not available. When |
| you try to set breakpoint, GDB will ask you if you want to set a so |
| called "pending breakpoint"--breakpoint whose address is not yet |
| resolved. |
| |
| After the program is run, whenever a new shared library is loaded, |
| GDB reevaluates all the breakpoints. When a newly loaded shared |
| library contains the symbol or line referred to by some pending |
| breakpoint, that breakpoint is resolved and becomes an ordinary |
| breakpoint. When a library is unloaded, all breakpoints that refer to |
| its symbols or source lines become pending again. |
| |
| This logic works for breakpoints with multiple locations, too. For |
| example, if you have a breakpoint in a C++ template function, and a |
| newly loaded shared library has an instantiation of that template, a |
| new location is added to the list of locations for the breakpoint. |
| |
| Except for having unresolved address, pending breakpoints do not |
| differ from regular breakpoints. You can set conditions or commands, |
| enable and disable them and perform other breakpoint operations. |
| |
| GDB provides some additional commands for controlling what happens |
| when the `break' command cannot resolve breakpoint address |
| specification to an address: |
| |
| `set breakpoint pending auto' |
| This is the default behavior. When GDB cannot find the breakpoint |
| location, it queries you whether a pending breakpoint should be |
| created. |
| |
| `set breakpoint pending on' |
| This indicates that an unrecognized breakpoint location should |
| automatically result in a pending breakpoint being created. |
| |
| `set breakpoint pending off' |
| This indicates that pending breakpoints are not to be created. Any |
| unrecognized breakpoint location results in an error. This |
| setting does not affect any pending breakpoints previously created. |
| |
| `show breakpoint pending' |
| Show the current behavior setting for creating pending breakpoints. |
| |
| The settings above only affect the `break' command and its variants. |
| Once breakpoint is set, it will be automatically updated as shared |
| libraries are loaded and unloaded. |
| |
| For some targets, GDB can automatically decide if hardware or |
| software breakpoints should be used, depending on whether the |
| breakpoint address is read-only or read-write. This applies to |
| breakpoints set with the `break' command as well as to internal |
| breakpoints set by commands like `next' and `finish'. For breakpoints |
| set with `hbreak', GDB will always use hardware breakpoints. |
| |
| You can control this automatic behaviour with the following |
| commands:: |
| |
| `set breakpoint auto-hw on' |
| This is the default behavior. When GDB sets a breakpoint, it will |
| try to use the target memory map to decide if software or hardware |
| breakpoint must be used. |
| |
| `set breakpoint auto-hw off' |
| This indicates GDB should not automatically select breakpoint |
| type. If the target provides a memory map, GDB will warn when |
| trying to set software breakpoint at a read-only address. |
| |
| GDB itself sometimes sets breakpoints in your program for special |
| purposes, such as proper handling of `longjmp' (in C programs). These |
| internal breakpoints are assigned negative numbers, starting with `-1'; |
| `info breakpoints' does not display them. You can see these |
| breakpoints with the GDB maintenance command `maint info breakpoints' |
| (*note maint info breakpoints::). |
| |
| |
| File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints |
| |
| 5.1.2 Setting Watchpoints |
| ------------------------- |
| |
| You can use a watchpoint to stop execution whenever the value of an |
| expression changes, without having to predict a particular place where |
| this may happen. (This is sometimes called a "data breakpoint".) The |
| expression may be as simple as the value of a single variable, or as |
| complex as many variables combined by operators. Examples include: |
| |
| * A reference to the value of a single variable. |
| |
| * An address cast to an appropriate data type. For example, `*(int |
| *)0x12345678' will watch a 4-byte region at the specified address |
| (assuming an `int' occupies 4 bytes). |
| |
| * An arbitrarily complex expression, such as `a*b + c/d'. The |
| expression can use any operators valid in the program's native |
| language (*note Languages::). |
| |
| Depending on your system, watchpoints may be implemented in software |
| or hardware. GDB does software watchpointing by single-stepping your |
| program and testing the variable's value each time, which is hundreds of |
| times slower than normal execution. (But this may still be worth it, to |
| catch errors where you have no clue what part of your program is the |
| culprit.) |
| |
| On some systems, such as HP-UX, PowerPC, GNU/Linux and most other |
| x86-based targets, GDB includes support for hardware watchpoints, which |
| do not slow down the running of your program. |
| |
| `watch EXPR [thread THREADNUM]' |
| Set a watchpoint for an expression. GDB will break when the |
| expression EXPR is written into by the program and its value |
| changes. The simplest (and the most popular) use of this command |
| is to watch the value of a single variable: |
| |
| (gdb) watch foo |
| |
| If the command includes a `[thread THREADNUM]' clause, GDB breaks |
| only when the thread identified by THREADNUM changes the value of |
| EXPR. If any other threads change the value of EXPR, GDB will not |
| break. Note that watchpoints restricted to a single thread in |
| this way only work with Hardware Watchpoints. |
| |
| `rwatch EXPR [thread THREADNUM]' |
| Set a watchpoint that will break when the value of EXPR is read by |
| the program. |
| |
| `awatch EXPR [thread THREADNUM]' |
| Set a watchpoint that will break when EXPR is either read from or |
| written into by the program. |
| |
| `info watchpoints' |
| This command prints a list of watchpoints, breakpoints, and |
| catchpoints; it is the same as `info break' (*note Set Breaks::). |
| |
| GDB sets a "hardware watchpoint" if possible. Hardware watchpoints |
| execute very quickly, and the debugger reports a change in value at the |
| exact instruction where the change occurs. If GDB cannot set a |
| hardware watchpoint, it sets a software watchpoint, which executes more |
| slowly and reports the change in value at the next _statement_, not the |
| instruction, after the change occurs. |
| |
| You can force GDB to use only software watchpoints with the `set |
| can-use-hw-watchpoints 0' command. With this variable set to zero, GDB |
| will never try to use hardware watchpoints, even if the underlying |
| system supports them. (Note that hardware-assisted watchpoints that |
| were set _before_ setting `can-use-hw-watchpoints' to zero will still |
| use the hardware mechanism of watching expression values.) |
| |
| `set can-use-hw-watchpoints' |
| Set whether or not to use hardware watchpoints. |
| |
| `show can-use-hw-watchpoints' |
| Show the current mode of using hardware watchpoints. |
| |
| For remote targets, you can restrict the number of hardware |
| watchpoints GDB will use, see *note set remote |
| hardware-breakpoint-limit::. |
| |
| When you issue the `watch' command, GDB reports |
| |
| Hardware watchpoint NUM: EXPR |
| |
| if it was able to set a hardware watchpoint. |
| |
| Currently, the `awatch' and `rwatch' commands can only set hardware |
| watchpoints, because accesses to data that don't change the value of |
| the watched expression cannot be detected without examining every |
| instruction as it is being executed, and GDB does not do that |
| currently. If GDB finds that it is unable to set a hardware breakpoint |
| with the `awatch' or `rwatch' command, it will print a message like |
| this: |
| |
| Expression cannot be implemented with read/access watchpoint. |
| |
| Sometimes, GDB cannot set a hardware watchpoint because the data |
| type of the watched expression is wider than what a hardware watchpoint |
| on the target machine can handle. For example, some systems can only |
| watch regions that are up to 4 bytes wide; on such systems you cannot |
| set hardware watchpoints for an expression that yields a |
| double-precision floating-point number (which is typically 8 bytes |
| wide). As a work-around, it might be possible to break the large region |
| into a series of smaller ones and watch them with separate watchpoints. |
| |
| If you set too many hardware watchpoints, GDB might be unable to |
| insert all of them when you resume the execution of your program. |
| Since the precise number of active watchpoints is unknown until such |
| time as the program is about to be resumed, GDB might not be able to |
| warn you about this when you set the watchpoints, and the warning will |
| be printed only when the program is resumed: |
| |
| Hardware watchpoint NUM: Could not insert watchpoint |
| |
| If this happens, delete or disable some of the watchpoints. |
| |
| Watching complex expressions that reference many variables can also |
| exhaust the resources available for hardware-assisted watchpoints. |
| That's because GDB needs to watch every variable in the expression with |
| separately allocated resources. |
| |
| The SPARClite DSU will generate traps when a program accesses some |
| data or instruction address that is assigned to the debug registers. |
| For the data addresses, DSU facilitates the `watch' command. However |
| the hardware breakpoint registers can only take two data watchpoints, |
| and both watchpoints must be the same kind. For example, you can set |
| two watchpoints with `watch' commands, two with `rwatch' commands, *or* |
| two with `awatch' commands, but you cannot set one watchpoint with one |
| command and the other with a different command. GDB will reject the |
| command if you try to mix watchpoints. Delete or disable unused |
| watchpoint commands before setting new ones. |
| |
| If you call a function interactively using `print' or `call', any |
| watchpoints you have set will be inactive until GDB reaches another |
| kind of breakpoint or the call completes. |
| |
| GDB automatically deletes watchpoints that watch local (automatic) |
| variables, or expressions that involve such variables, when they go out |
| of scope, that is, when the execution leaves the block in which these |
| variables were defined. In particular, when the program being debugged |
| terminates, _all_ local variables go out of scope, and so only |
| watchpoints that watch global variables remain set. If you rerun the |
| program, you will need to set all such watchpoints again. One way of |
| doing that would be to set a code breakpoint at the entry to the `main' |
| function and when it breaks, set all the watchpoints. |
| |
| In multi-threaded programs, watchpoints will detect changes to the |
| watched expression from every thread. |
| |
| _Warning:_ In multi-threaded programs, software watchpoints have |
| only limited usefulness. If GDB creates a software watchpoint, it |
| can only watch the value of an expression _in a single thread_. |
| If you are confident that the expression can only change due to |
| the current thread's activity (and if you are also confident that |
| no other thread can become current), then you can use software |
| watchpoints as usual. However, GDB may not notice when a |
| non-current thread's activity changes the expression. (Hardware |
| watchpoints, in contrast, watch an expression in all threads.) |
| |
| *Note set remote hardware-watchpoint-limit::. |
| |
| |
| File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints |
| |
| 5.1.3 Setting Catchpoints |
| ------------------------- |
| |
| You can use "catchpoints" to cause the debugger to stop for certain |
| kinds of program events, such as C++ exceptions or the loading of a |
| shared library. Use the `catch' command to set a catchpoint. |
| |
| `catch EVENT' |
| Stop when EVENT occurs. EVENT can be any of the following: |
| `throw' |
| The throwing of a C++ exception. |
| |
| `catch' |
| The catching of a C++ exception. |
| |
| `exception' |
| An Ada exception being raised. If an exception name is |
| specified at the end of the command (eg `catch exception |
| Program_Error'), the debugger will stop only when this |
| specific exception is raised. Otherwise, the debugger stops |
| execution when any Ada exception is raised. |
| |
| `exception unhandled' |
| An exception that was raised but is not handled by the |
| program. |
| |
| `assert' |
| A failed Ada assertion. |
| |
| `exec' |
| A call to `exec'. This is currently only available for HP-UX |
| and GNU/Linux. |
| |
| `fork' |
| A call to `fork'. This is currently only available for HP-UX |
| and GNU/Linux. |
| |
| `vfork' |
| A call to `vfork'. This is currently only available for HP-UX |
| and GNU/Linux. |
| |
| `load' |
| `load LIBNAME' |
| The dynamic loading of any shared library, or the loading of |
| the library LIBNAME. This is currently only available for |
| HP-UX. |
| |
| `unload' |
| `unload LIBNAME' |
| The unloading of any dynamically loaded shared library, or |
| the unloading of the library LIBNAME. This is currently only |
| available for HP-UX. |
| |
| `tcatch EVENT' |
| Set a catchpoint that is enabled only for one stop. The |
| catchpoint is automatically deleted after the first time the event |
| is caught. |
| |
| |
| Use the `info break' command to list the current catchpoints. |
| |
| There are currently some limitations to C++ exception handling |
| (`catch throw' and `catch catch') in GDB: |
| |
| * If you call a function interactively, GDB normally returns control |
| to you when the function has finished executing. If the call |
| raises an exception, however, the call may bypass the mechanism |
| that returns control to you and cause your program either to abort |
| or to simply continue running until it hits a breakpoint, catches |
| a signal that GDB is listening for, or exits. This is the case |
| even if you set a catchpoint for the exception; catchpoints on |
| exceptions are disabled within interactive calls. |
| |
| * You cannot raise an exception interactively. |
| |
| * You cannot install an exception handler interactively. |
| |
| Sometimes `catch' is not the best way to debug exception handling: |
| if you need to know exactly where an exception is raised, it is better |
| to stop _before_ the exception handler is called, since that way you |
| can see the stack before any unwinding takes place. If you set a |
| breakpoint in an exception handler instead, it may not be easy to find |
| out where the exception was raised. |
| |
| To stop just before an exception handler is called, you need some |
| knowledge of the implementation. In the case of GNU C++, exceptions are |
| raised by calling a library function named `__raise_exception' which |
| has the following ANSI C interface: |
| |
| /* ADDR is where the exception identifier is stored. |
| ID is the exception identifier. */ |
| void __raise_exception (void **addr, void *id); |
| |
| To make the debugger catch all exceptions before any stack unwinding |
| takes place, set a breakpoint on `__raise_exception' (*note |
| Breakpoints; Watchpoints; and Exceptions: Breakpoints.). |
| |
| With a conditional breakpoint (*note Break Conditions: Conditions.) |
| that depends on the value of ID, you can stop your program when a |
| specific exception is raised. You can use multiple conditional |
| breakpoints to stop your program when any of a number of exceptions are |
| raised. |
| |
| |
| File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints |
| |
| 5.1.4 Deleting Breakpoints |
| -------------------------- |
| |
| It is often necessary to eliminate a breakpoint, watchpoint, or |
| catchpoint once it has done its job and you no longer want your program |
| to stop there. This is called "deleting" the breakpoint. A breakpoint |
| that has been deleted no longer exists; it is forgotten. |
| |
| With the `clear' command you can delete breakpoints according to |
| where they are in your program. With the `delete' command you can |
| delete individual breakpoints, watchpoints, or catchpoints by specifying |
| their breakpoint numbers. |
| |
| It is not necessary to delete a breakpoint to proceed past it. GDB |
| automatically ignores breakpoints on the first instruction to be |
| executed when you continue execution without changing the execution |
| address. |
| |
| `clear' |
| Delete any breakpoints at the next instruction to be executed in |
| the selected stack frame (*note Selecting a Frame: Selection.). |
| When the innermost frame is selected, this is a good way to delete |
| a breakpoint where your program just stopped. |
| |
| `clear LOCATION' |
| Delete any breakpoints set at the specified LOCATION. *Note |
| Specify Location::, for the various forms of LOCATION; the most |
| useful ones are listed below: |
| |
| `clear FUNCTION' |
| `clear FILENAME:FUNCTION' |
| Delete any breakpoints set at entry to the named FUNCTION. |
| |
| `clear LINENUM' |
| `clear FILENAME:LINENUM' |
| Delete any breakpoints set at or within the code of the |
| specified LINENUM of the specified FILENAME. |
| |
| `delete [breakpoints] [RANGE...]' |
| Delete the breakpoints, watchpoints, or catchpoints of the |
| breakpoint ranges specified as arguments. If no argument is |
| specified, delete all breakpoints (GDB asks confirmation, unless |
| you have `set confirm off'). You can abbreviate this command as |
| `d'. |
| |
| |
| File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints |
| |
| 5.1.5 Disabling Breakpoints |
| --------------------------- |
| |
| Rather than deleting a breakpoint, watchpoint, or catchpoint, you might |
| prefer to "disable" it. This makes the breakpoint inoperative as if it |
| had been deleted, but remembers the information on the breakpoint so |
| that you can "enable" it again later. |
| |
| You disable and enable breakpoints, watchpoints, and catchpoints with |
| the `enable' and `disable' commands, optionally specifying one or more |
| breakpoint numbers as arguments. Use `info break' or `info watch' to |
| print a list of breakpoints, watchpoints, and catchpoints if you do not |
| know which numbers to use. |
| |
| Disabling and enabling a breakpoint that has multiple locations |
| affects all of its locations. |
| |
| A breakpoint, watchpoint, or catchpoint can have any of four |
| different states of enablement: |
| |
| * Enabled. The breakpoint stops your program. A breakpoint set |
| with the `break' command starts out in this state. |
| |
| * Disabled. The breakpoint has no effect on your program. |
| |
| * Enabled once. The breakpoint stops your program, but then becomes |
| disabled. |
| |
| * Enabled for deletion. The breakpoint stops your program, but |
| immediately after it does so it is deleted permanently. A |
| breakpoint set with the `tbreak' command starts out in this state. |
| |
| You can use the following commands to enable or disable breakpoints, |
| watchpoints, and catchpoints: |
| |
| `disable [breakpoints] [RANGE...]' |
| Disable the specified breakpoints--or all breakpoints, if none are |
| listed. A disabled breakpoint has no effect but is not forgotten. |
| All options such as ignore-counts, conditions and commands are |
| remembered in case the breakpoint is enabled again later. You may |
| abbreviate `disable' as `dis'. |
| |
| `enable [breakpoints] [RANGE...]' |
| Enable the specified breakpoints (or all defined breakpoints). |
| They become effective once again in stopping your program. |
| |
| `enable [breakpoints] once RANGE...' |
| Enable the specified breakpoints temporarily. GDB disables any of |
| these breakpoints immediately after stopping your program. |
| |
| `enable [breakpoints] delete RANGE...' |
| Enable the specified breakpoints to work once, then die. GDB |
| deletes any of these breakpoints as soon as your program stops |
| there. Breakpoints set by the `tbreak' command start out in this |
| state. |
| |
| Except for a breakpoint set with `tbreak' (*note Setting |
| Breakpoints: Set Breaks.), breakpoints that you set are initially |
| enabled; subsequently, they become disabled or enabled only when you |
| use one of the commands above. (The command `until' can set and delete |
| a breakpoint of its own, but it does not change the state of your other |
| breakpoints; see *note Continuing and Stepping: Continuing and |
| Stepping.) |
| |
| |
| File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints |
| |
| 5.1.6 Break Conditions |
| ---------------------- |
| |
| The simplest sort of breakpoint breaks every time your program reaches a |
| specified place. You can also specify a "condition" for a breakpoint. |
| A condition is just a Boolean expression in your programming language |
| (*note Expressions: Expressions.). A breakpoint with a condition |
| evaluates the expression each time your program reaches it, and your |
| program stops only if the condition is _true_. |
| |
| This is the converse of using assertions for program validation; in |
| that situation, you want to stop when the assertion is violated--that |
| is, when the condition is false. In C, if you want to test an |
| assertion expressed by the condition ASSERT, you should set the |
| condition `! ASSERT' on the appropriate breakpoint. |
| |
| Conditions are also accepted for watchpoints; you may not need them, |
| since a watchpoint is inspecting the value of an expression anyhow--but |
| it might be simpler, say, to just set a watchpoint on a variable name, |
| and specify a condition that tests whether the new value is an |
| interesting one. |
| |
| Break conditions can have side effects, and may even call functions |
| in your program. This can be useful, for example, to activate functions |
| that log program progress, or to use your own print functions to format |
| special data structures. The effects are completely predictable unless |
| there is another enabled breakpoint at the same address. (In that |
| case, GDB might see the other breakpoint first and stop your program |
| without checking the condition of this one.) Note that breakpoint |
| commands are usually more convenient and flexible than break conditions |
| for the purpose of performing side effects when a breakpoint is reached |
| (*note Breakpoint Command Lists: Break Commands.). |
| |
| Break conditions can be specified when a breakpoint is set, by using |
| `if' in the arguments to the `break' command. *Note Setting |
| Breakpoints: Set Breaks. They can also be changed at any time with the |
| `condition' command. |
| |
| You can also use the `if' keyword with the `watch' command. The |
| `catch' command does not recognize the `if' keyword; `condition' is the |
| only way to impose a further condition on a catchpoint. |
| |
| `condition BNUM EXPRESSION' |
| Specify EXPRESSION as the break condition for breakpoint, |
| watchpoint, or catchpoint number BNUM. After you set a condition, |
| breakpoint BNUM stops your program only if the value of EXPRESSION |
| is true (nonzero, in C). When you use `condition', GDB checks |
| EXPRESSION immediately for syntactic correctness, and to determine |
| whether symbols in it have referents in the context of your |
| breakpoint. If EXPRESSION uses symbols not referenced in the |
| context of the breakpoint, GDB prints an error message: |
| |
| No symbol "foo" in current context. |
| |
| GDB does not actually evaluate EXPRESSION at the time the |
| `condition' command (or a command that sets a breakpoint with a |
| condition, like `break if ...') is given, however. *Note |
| Expressions: Expressions. |
| |
| `condition BNUM' |
| Remove the condition from breakpoint number BNUM. It becomes an |
| ordinary unconditional breakpoint. |
| |
| A special case of a breakpoint condition is to stop only when the |
| breakpoint has been reached a certain number of times. This is so |
| useful that there is a special way to do it, using the "ignore count" |
| of the breakpoint. Every breakpoint has an ignore count, which is an |
| integer. Most of the time, the ignore count is zero, and therefore has |
| no effect. But if your program reaches a breakpoint whose ignore count |
| is positive, then instead of stopping, it just decrements the ignore |
| count by one and continues. As a result, if the ignore count value is |
| N, the breakpoint does not stop the next N times your program reaches |
| it. |
| |
| `ignore BNUM COUNT' |
| Set the ignore count of breakpoint number BNUM to COUNT. The next |
| COUNT times the breakpoint is reached, your program's execution |
| does not stop; other than to decrement the ignore count, GDB takes |
| no action. |
| |
| To make the breakpoint stop the next time it is reached, specify a |
| count of zero. |
| |
| When you use `continue' to resume execution of your program from a |
| breakpoint, you can specify an ignore count directly as an |
| argument to `continue', rather than using `ignore'. *Note |
| Continuing and Stepping: Continuing and Stepping. |
| |
| If a breakpoint has a positive ignore count and a condition, the |
| condition is not checked. Once the ignore count reaches zero, GDB |
| resumes checking the condition. |
| |
| You could achieve the effect of the ignore count with a condition |
| such as `$foo-- <= 0' using a debugger convenience variable that |
| is decremented each time. *Note Convenience Variables: |
| Convenience Vars. |
| |
| Ignore counts apply to breakpoints, watchpoints, and catchpoints. |
| |
| |
| File: gdb.info, Node: Break Commands, Next: Breakpoint Menus, Prev: Conditions, Up: Breakpoints |
| |
| 5.1.7 Breakpoint Command Lists |
| ------------------------------ |
| |
| You can give any breakpoint (or watchpoint or catchpoint) a series of |
| commands to execute when your program stops due to that breakpoint. For |
| example, you might want to print the values of certain expressions, or |
| enable other breakpoints. |
| |
| `commands [BNUM]' |
| `... COMMAND-LIST ...' |
| `end' |
| Specify a list of commands for breakpoint number BNUM. The |
| commands themselves appear on the following lines. Type a line |
| containing just `end' to terminate the commands. |
| |
| To remove all commands from a breakpoint, type `commands' and |
| follow it immediately with `end'; that is, give no commands. |
| |
| With no BNUM argument, `commands' refers to the last breakpoint, |
| watchpoint, or catchpoint set (not to the breakpoint most recently |
| encountered). |
| |
| Pressing <RET> as a means of repeating the last GDB command is |
| disabled within a COMMAND-LIST. |
| |
| You can use breakpoint commands to start your program up again. |
| Simply use the `continue' command, or `step', or any other command that |
| resumes execution. |
| |
| Any other commands in the command list, after a command that resumes |
| execution, are ignored. This is because any time you resume execution |
| (even with a simple `next' or `step'), you may encounter another |
| breakpoint--which could have its own command list, leading to |
| ambiguities about which list to execute. |
| |
| If the first command you specify in a command list is `silent', the |
| usual message about stopping at a breakpoint is not printed. This may |
| be desirable for breakpoints that are to print a specific message and |
| then continue. If none of the remaining commands print anything, you |
| see no sign that the breakpoint was reached. `silent' is meaningful |
| only at the beginning of a breakpoint command list. |
| |
| The commands `echo', `output', and `printf' allow you to print |
| precisely controlled output, and are often useful in silent |
| breakpoints. *Note Commands for Controlled Output: Output. |
| |
| For example, here is how you could use breakpoint commands to print |
| the value of `x' at entry to `foo' whenever `x' is positive. |
| |
| break foo if x>0 |
| commands |
| silent |
| printf "x is %d\n",x |
| cont |
| end |
| |
| One application for breakpoint commands is to compensate for one bug |
| so you can test for another. Put a breakpoint just after the erroneous |
| line of code, give it a condition to detect the case in which something |
| erroneous has been done, and give it commands to assign correct values |
| to any variables that need them. End with the `continue' command so |
| that your program does not stop, and start with the `silent' command so |
| that no output is produced. Here is an example: |
| |
| break 403 |
| commands |
| silent |
| set x = y + 4 |
| cont |
| end |
| |
| |
| File: gdb.info, Node: Breakpoint Menus, Next: Error in Breakpoints, Prev: Break Commands, Up: Breakpoints |
| |
| 5.1.8 Breakpoint Menus |
| ---------------------- |
| |
| Some programming languages (notably C++ and Objective-C) permit a |
| single function name to be defined several times, for application in |
| different contexts. This is called "overloading". When a function |
| name is overloaded, `break FUNCTION' is not enough to tell GDB where |
| you want a breakpoint. You can use explicit signature of the function, |
| as in `break FUNCTION(TYPES)', to specify which particular version of |
| the function you want. Otherwise, GDB offers you a menu of numbered |
| choices for different possible breakpoints, and waits for your |
| selection with the prompt `>'. The first two options are always `[0] |
| cancel' and `[1] all'. Typing `1' sets a breakpoint at each definition |
| of FUNCTION, and typing `0' aborts the `break' command without setting |
| any new breakpoints. |
| |
| For example, the following session excerpt shows an attempt to set a |
| breakpoint at the overloaded symbol `String::after'. We choose three |
| particular definitions of that function name: |
| |
| (gdb) b String::after |
| [0] cancel |
| [1] all |
| [2] file:String.cc; line number:867 |
| [3] file:String.cc; line number:860 |
| [4] file:String.cc; line number:875 |
| [5] file:String.cc; line number:853 |
| [6] file:String.cc; line number:846 |
| [7] file:String.cc; line number:735 |
| > 2 4 6 |
| Breakpoint 1 at 0xb26c: file String.cc, line 867. |
| Breakpoint 2 at 0xb344: file String.cc, line 875. |
| Breakpoint 3 at 0xafcc: file String.cc, line 846. |
| Multiple breakpoints were set. |
| Use the "delete" command to delete unwanted |
| breakpoints. |
| (gdb) |
| |
| |
| File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Breakpoint Menus, Up: Breakpoints |
| |
| 5.1.9 "Cannot insert breakpoints" |
| --------------------------------- |
| |
| Under some operating systems, breakpoints cannot be used in a program if |
| any other process is running that program. In this situation, |
| attempting to run or continue a program with a breakpoint causes GDB to |
| print an error message: |
| |
| Cannot insert breakpoints. |
| The same program may be running in another process. |
| |
| When this happens, you have three ways to proceed: |
| |
| 1. Remove or disable the breakpoints, then continue. |
| |
| 2. Suspend GDB, and copy the file containing your program to a new |
| name. Resume GDB and use the `exec-file' command to specify that |
| GDB should run your program under that name. Then start your |
| program again. |
| |
| 3. Relink your program so that the text segment is nonsharable, using |
| the linker option `-N'. The operating system limitation may not |
| apply to nonsharable executables. |
| |
| A similar message can be printed if you request too many active |
| hardware-assisted breakpoints and watchpoints: |
| |
| Stopped; cannot insert breakpoints. |
| You may have requested too many hardware breakpoints and watchpoints. |
| |
| This message is printed when you attempt to resume the program, since |
| only then GDB knows exactly how many hardware breakpoints and |
| watchpoints it needs to insert. |
| |
| When this message is printed, you need to disable or remove some of |
| the hardware-assisted breakpoints and watchpoints, and then continue. |
| |
| |
| File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints |
| |
| 5.1.10 "Breakpoint address adjusted..." |
| --------------------------------------- |
| |
| Some processor architectures place constraints on the addresses at |
| which breakpoints may be placed. For architectures thus constrained, |
| GDB will attempt to adjust the breakpoint's address to comply with the |
| constraints dictated by the architecture. |
| |
| One example of such an architecture is the Fujitsu FR-V. The FR-V is |
| a VLIW architecture in which a number of RISC-like instructions may be |
| bundled together for parallel execution. The FR-V architecture |
| constrains the location of a breakpoint instruction within such a |
| bundle to the instruction with the lowest address. GDB honors this |
| constraint by adjusting a breakpoint's address to the first in the |
| bundle. |
| |
| It is not uncommon for optimized code to have bundles which contain |
| instructions from different source statements, thus it may happen that |
| a breakpoint's address will be adjusted from one source statement to |
| another. Since this adjustment may significantly alter GDB's |
| breakpoint related behavior from what the user expects, a warning is |
| printed when the breakpoint is first set and also when the breakpoint |
| is hit. |
| |
| A warning like the one below is printed when setting a breakpoint |
| that's been subject to address adjustment: |
| |
| warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. |
| |
| Such warnings are printed both for user settable and GDB's internal |
| breakpoints. If you see one of these warnings, you should verify that |
| a breakpoint set at the adjusted address will have the desired affect. |
| If not, the breakpoint in question may be removed and other breakpoints |
| may be set which will have the desired behavior. E.g., it may be |
| sufficient to place the breakpoint at a later instruction. A |
| conditional breakpoint may also be useful in some cases to prevent the |
| breakpoint from triggering too often. |
| |
| GDB will also issue a warning when stopping at one of these adjusted |
| breakpoints: |
| |
| warning: Breakpoint 1 address previously adjusted from 0x00010414 |
| to 0x00010410. |
| |
| When this warning is encountered, it may be too late to take remedial |
| action except in cases where the breakpoint is hit earlier or more |
| frequently than expected. |
| |
| |
| File: gdb.info, Node: Continuing and Stepping, Next: Signals, Prev: Breakpoints, Up: Stopping |
| |
| 5.2 Continuing and Stepping |
| =========================== |
| |
| "Continuing" means resuming program execution until your program |
| completes normally. In contrast, "stepping" means executing just one |
| more "step" of your program, where "step" may mean either one line of |
| source code, or one machine instruction (depending on what particular |
| command you use). Either when continuing or when stepping, your |
| program may stop even sooner, due to a breakpoint or a signal. (If it |
| stops due to a signal, you may want to use `handle', or use `signal 0' |
| to resume execution. *Note Signals: Signals.) |
| |
| `continue [IGNORE-COUNT]' |
| `c [IGNORE-COUNT]' |
| `fg [IGNORE-COUNT]' |
| Resume program execution, at the address where your program last |
| stopped; any breakpoints set at that address are bypassed. The |
| optional argument IGNORE-COUNT allows you to specify a further |
| number of times to ignore a breakpoint at this location; its |
| effect is like that of `ignore' (*note Break Conditions: |
| Conditions.). |
| |
| The argument IGNORE-COUNT is meaningful only when your program |
| stopped due to a breakpoint. At other times, the argument to |
| `continue' is ignored. |
| |
| The synonyms `c' and `fg' (for "foreground", as the debugged |
| program is deemed to be the foreground program) are provided |
| purely for convenience, and have exactly the same behavior as |
| `continue'. |
| |
| To resume execution at a different place, you can use `return' |
| (*note Returning from a Function: Returning.) to go back to the calling |
| function; or `jump' (*note Continuing at a Different Address: Jumping.) |
| to go to an arbitrary location in your program. |
| |
| A typical technique for using stepping is to set a breakpoint (*note |
| Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the |
| beginning of the function or the section of your program where a problem |
| is believed to lie, run your program until it stops at that breakpoint, |
| and then step through the suspect area, examining the variables that are |
| interesting, until you see the problem happen. |
| |
| `step' |
| Continue running your program until control reaches a different |
| source line, then stop it and return control to GDB. This command |
| is abbreviated `s'. |
| |
| _Warning:_ If you use the `step' command while control is |
| within a function that was compiled without debugging |
| information, execution proceeds until control reaches a |
| function that does have debugging information. Likewise, it |
| will not step into a function which is compiled without |
| debugging information. To step through functions without |
| debugging information, use the `stepi' command, described |
| below. |
| |
| The `step' command only stops at the first instruction of a source |
| line. This prevents the multiple stops that could otherwise occur |
| in `switch' statements, `for' loops, etc. `step' continues to |
| stop if a function that has debugging information is called within |
| the line. In other words, `step' _steps inside_ any functions |
| called within the line. |
| |
| Also, the `step' command only enters a function if there is line |
| number information for the function. Otherwise it acts like the |
| `next' command. This avoids problems when using `cc -gl' on MIPS |
| machines. Previously, `step' entered subroutines if there was any |
| debugging information about the routine. |
| |
| `step COUNT' |
| Continue running as in `step', but do so COUNT times. If a |
| breakpoint is reached, or a signal not related to stepping occurs |
| before COUNT steps, stepping stops right away. |
| |
| `next [COUNT]' |
| Continue to the next source line in the current (innermost) stack |
| frame. This is similar to `step', but function calls that appear |
| within the line of code are executed without stopping. Execution |
| stops when control reaches a different line of code at the |
| original stack level that was executing when you gave the `next' |
| command. This command is abbreviated `n'. |
| |
| An argument COUNT is a repeat count, as for `step'. |
| |
| The `next' command only stops at the first instruction of a source |
| line. This prevents multiple stops that could otherwise occur in |
| `switch' statements, `for' loops, etc. |
| |
| `set step-mode' |
| `set step-mode on' |
| The `set step-mode on' command causes the `step' command to stop |
| at the first instruction of a function which contains no debug line |
| information rather than stepping over it. |
| |
| This is useful in cases where you may be interested in inspecting |
| the machine instructions of a function which has no symbolic info |
| and do not want GDB to automatically skip over this function. |
| |
| `set step-mode off' |
| Causes the `step' command to step over any functions which |
| contains no debug information. This is the default. |
| |
| `show step-mode' |
| Show whether GDB will stop in or step over functions without |
| source line debug information. |
| |
| `finish' |
| Continue running until just after function in the selected stack |
| frame returns. Print the returned value (if any). |
| |
| Contrast this with the `return' command (*note Returning from a |
| Function: Returning.). |
| |
| `until' |
| `u' |
| Continue running until a source line past the current line, in the |
| current stack frame, is reached. This command is used to avoid |
| single stepping through a loop more than once. It is like the |
| `next' command, except that when `until' encounters a jump, it |
| automatically continues execution until the program counter is |
| greater than the address of the jump. |
| |
| This means that when you reach the end of a loop after single |
| stepping though it, `until' makes your program continue execution |
| until it exits the loop. In contrast, a `next' command at the end |
| of a loop simply steps back to the beginning of the loop, which |
| forces you to step through the next iteration. |
| |
| `until' always stops your program if it attempts to exit the |
| current stack frame. |
| |
| `until' may produce somewhat counterintuitive results if the order |
| of machine code does not match the order of the source lines. For |
| example, in the following excerpt from a debugging session, the `f' |
| (`frame') command shows that execution is stopped at line `206'; |
| yet when we use `until', we get to line `195': |
| |
| (gdb) f |
| #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 |
| 206 expand_input(); |
| (gdb) until |
| 195 for ( ; argc > 0; NEXTARG) { |
| |
| This happened because, for execution efficiency, the compiler had |
| generated code for the loop closure test at the end, rather than |
| the start, of the loop--even though the test in a C `for'-loop is |
| written before the body of the loop. The `until' command appeared |
| to step back to the beginning of the loop when it advanced to this |
| expression; however, it has not really gone to an earlier |
| statement--not in terms of the actual machine code. |
| |
| `until' with no argument works by means of single instruction |
| stepping, and hence is slower than `until' with an argument. |
| |
| `until LOCATION' |
| `u LOCATION' |
| Continue running your program until either the specified location |
| is reached, or the current stack frame returns. LOCATION is any of |
| the forms described in *note Specify Location::. This form of the |
| command uses temporary breakpoints, and hence is quicker than |
| `until' without an argument. The specified location is actually |
| reached only if it is in the current frame. This implies that |
| `until' can be used to skip over recursive function invocations. |
| For instance in the code below, if the current location is line |
| `96', issuing `until 99' will execute the program up to line `99' |
| in the same invocation of factorial, i.e., after the inner |
| invocations have returned. |
| |
| 94 int factorial (int value) |
| 95 { |
| 96 if (value > 1) { |
| 97 value *= factorial (value - 1); |
| 98 } |
| 99 return (value); |
| 100 } |
| |
| `advance LOCATION' |
| Continue running the program up to the given LOCATION. An |
| argument is required, which should be of one of the forms |
| described in *note Specify Location::. Execution will also stop |
| upon exit from the current stack frame. This command is similar |
| to `until', but `advance' will not skip over recursive function |
| calls, and the target location doesn't have to be in the same |
| frame as the current one. |
| |
| `stepi' |
| `stepi ARG' |
| `si' |
| Execute one machine instruction, then stop and return to the |
| debugger. |
| |
| It is often useful to do `display/i $pc' when stepping by machine |
| instructions. This makes GDB automatically display the next |
| instruction to be executed, each time your program stops. *Note |
| Automatic Display: Auto Display. |
| |
| An argument is a repeat count, as in `step'. |
| |
| `nexti' |
| `nexti ARG' |
| `ni' |
| Execute one machine instruction, but if it is a function call, |
| proceed until the function returns. |
| |
| An argument is a repeat count, as in `next'. |
| |
| |
| File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Continuing and Stepping, Up: Stopping |
| |
| 5.3 Signals |
| =========== |
| |
| A signal is an asynchronous event that can happen in a program. The |
| operating system defines the possible kinds of signals, and gives each |
| kind a name and a number. For example, in Unix `SIGINT' is the signal |
| a program gets when you type an interrupt character (often `Ctrl-c'); |
| `SIGSEGV' is the signal a program gets from referencing a place in |
| memory far away from all the areas in use; `SIGALRM' occurs when the |
| alarm clock timer goes off (which happens only if your program has |
| requested an alarm). |
| |
| Some signals, including `SIGALRM', are a normal part of the |
| functioning of your program. Others, such as `SIGSEGV', indicate |
| errors; these signals are "fatal" (they kill your program immediately) |
| if the program has not specified in advance some other way to handle |
| the signal. `SIGINT' does not indicate an error in your program, but |
| it is normally fatal so it can carry out the purpose of the interrupt: |
| to kill the program. |
| |
| GDB has the ability to detect any occurrence of a signal in your |
| program. You can tell GDB in advance what to do for each kind of |
| signal. |
| |
| Normally, GDB is set up to let the non-erroneous signals like |
| `SIGALRM' be silently passed to your program (so as not to interfere |
| with their role in the program's functioning) but to stop your program |
| immediately whenever an error signal happens. You can change these |
| settings with the `handle' command. |
| |
| `info signals' |
| `info handle' |
| Print a table of all the kinds of signals and how GDB has been |
| told to handle each one. You can use this to see the signal |
| numbers of all the defined types of signals. |
| |
| `info signals SIG' |
| Similar, but print information only about the specified signal |
| number. |
| |
| `info handle' is an alias for `info signals'. |
| |
| `handle SIGNAL [KEYWORDS...]' |
| Change the way GDB handles signal SIGNAL. SIGNAL can be the |
| number of a signal or its name (with or without the `SIG' at the |
| beginning); a list of signal numbers of the form `LOW-HIGH'; or |
| the word `all', meaning all the known signals. Optional arguments |
| KEYWORDS, described below, say what change to make. |
| |
| The keywords allowed by the `handle' command can be abbreviated. |
| Their full names are: |
| |
| `nostop' |
| GDB should not stop your program when this signal happens. It may |
| still print a message telling you that the signal has come in. |
| |
| `stop' |
| GDB should stop your program when this signal happens. This |
| implies the `print' keyword as well. |
| |
| `print' |
| GDB should print a message when this signal happens. |
| |
| `noprint' |
| GDB should not mention the occurrence of the signal at all. This |
| implies the `nostop' keyword as well. |
| |
| `pass' |
| `noignore' |
| GDB should allow your program to see this signal; your program can |
| handle the signal, or else it may terminate if the signal is fatal |
| and not handled. `pass' and `noignore' are synonyms. |
| |
| `nopass' |
| `ignore' |
| GDB should not allow your program to see this signal. `nopass' |
| and `ignore' are synonyms. |
| |
| When a signal stops your program, the signal is not visible to the |
| program until you continue. Your program sees the signal then, if |
| `pass' is in effect for the signal in question _at that time_. In |
| other words, after GDB reports a signal, you can use the `handle' |
| command with `pass' or `nopass' to control whether your program sees |
| that signal when you continue. |
| |
| The default is set to `nostop', `noprint', `pass' for non-erroneous |
| signals such as `SIGALRM', `SIGWINCH' and `SIGCHLD', and to `stop', |
| `print', `pass' for the erroneous signals. |
| |
| You can also use the `signal' command to prevent your program from |
| seeing a signal, or cause it to see a signal it normally would not see, |
| or to give it any signal at any time. For example, if your program |
| stopped due to some sort of memory reference error, you might store |
| correct values into the erroneous variables and continue, hoping to see |
| more execution; but your program would probably terminate immediately as |
| a result of the fatal signal once it saw the signal. To prevent this, |
| you can continue with `signal 0'. *Note Giving your Program a Signal: |
| Signaling. |
| |
| |
| File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping |
| |
| 5.4 Stopping and Starting Multi-thread Programs |
| =============================================== |
| |
| When your program has multiple threads (*note Debugging Programs with |
| Multiple Threads: Threads.), you can choose whether to set breakpoints |
| on all threads, or on a particular thread. |
| |
| `break LINESPEC thread THREADNO' |
| `break LINESPEC thread THREADNO if ...' |
| LINESPEC specifies source lines; there are several ways of writing |
| them (*note Specify Location::), but the effect is always to |
| specify some source line. |
| |
| Use the qualifier `thread THREADNO' with a breakpoint command to |
| specify that you only want GDB to stop the program when a |
| particular thread reaches this breakpoint. THREADNO is one of the |
| numeric thread identifiers assigned by GDB, shown in the first |
| column of the `info threads' display. |
| |
| If you do not specify `thread THREADNO' when you set a breakpoint, |
| the breakpoint applies to _all_ threads of your program. |
| |
| You can use the `thread' qualifier on conditional breakpoints as |
| well; in this case, place `thread THREADNO' before the breakpoint |
| condition, like this: |
| |
| (gdb) break frik.c:13 thread 28 if bartab > lim |
| |
| |
| Whenever your program stops under GDB for any reason, _all_ threads |
| of execution stop, not just the current thread. This allows you to |
| examine the overall state of the program, including switching between |
| threads, without worrying that things may change underfoot. |
| |
| There is an unfortunate side effect. If one thread stops for a |
| breakpoint, or for some other reason, and another thread is blocked in a |
| system call, then the system call may return prematurely. This is a |
| consequence of the interaction between multiple threads and the signals |
| that GDB uses to implement breakpoints and other events that stop |
| execution. |
| |
| To handle this problem, your program should check the return value of |
| each system call and react appropriately. This is good programming |
| style anyways. |
| |
| For example, do not write code like this: |
| |
| sleep (10); |
| |
| The call to `sleep' will return early if a different thread stops at |
| a breakpoint or for some other reason. |
| |
| Instead, write this: |
| |
| int unslept = 10; |
| while (unslept > 0) |
| unslept = sleep (unslept); |
| |
| A system call is allowed to return early, so the system is still |
| conforming to its specification. But GDB does cause your |
| multi-threaded program to behave differently than it would without GDB. |
| |
| Also, GDB uses internal breakpoints in the thread library to monitor |
| certain events such as thread creation and thread destruction. When |
| such an event happens, a system call in another thread may return |
| prematurely, even though your program does not appear to stop. |
| |
| Conversely, whenever you restart the program, _all_ threads start |
| executing. _This is true even when single-stepping_ with commands like |
| `step' or `next'. |
| |
| In particular, GDB cannot single-step all threads in lockstep. |
| Since thread scheduling is up to your debugging target's operating |
| system (not controlled by GDB), other threads may execute more than one |
| statement while the current thread completes a single step. Moreover, |
| in general other threads stop in the middle of a statement, rather than |
| at a clean statement boundary, when the program stops. |
| |
| You might even find your program stopped in another thread after |
| continuing or even single-stepping. This happens whenever some other |
| thread runs into a breakpoint, a signal, or an exception before the |
| first thread completes whatever you requested. |
| |
| On some OSes, you can lock the OS scheduler and thus allow only a |
| single thread to run. |
| |
| `set scheduler-locking MODE' |
| Set the scheduler locking mode. If it is `off', then there is no |
| locking and any thread may run at any time. If `on', then only the |
| current thread may run when the inferior is resumed. The `step' |
| mode optimizes for single-stepping. It stops other threads from |
| "seizing the prompt" by preempting the current thread while you are |
| stepping. Other threads will only rarely (or never) get a chance |
| to run when you step. They are more likely to run when you `next' |
| over a function call, and they are completely free to run when you |
| use commands like `continue', `until', or `finish'. However, |
| unless another thread hits a breakpoint during its timeslice, they |
| will never steal the GDB prompt away from the thread that you are |
| debugging. |
| |
| `show scheduler-locking' |
| Display the current scheduler locking mode. |
| |
| |
| File: gdb.info, Node: Stack, Next: Source, Prev: Stopping, Up: Top |
| |
| 6 Examining the Stack |
| ********************* |
| |
| When your program has stopped, the first thing you need to know is |
| where it stopped and how it got there. |
| |
| Each time your program performs a function call, information about |
| the call is generated. That information includes the location of the |
| call in your program, the arguments of the call, and the local |
| variables of the function being called. The information is saved in a |
| block of data called a "stack frame". The stack frames are allocated |
| in a region of memory called the "call stack". |
| |
| When your program stops, the GDB commands for examining the stack |
| allow you to see all of this information. |
| |
| One of the stack frames is "selected" by GDB and many GDB commands |
| refer implicitly to the selected frame. In particular, whenever you |
| ask GDB for the value of a variable in your program, the value is found |
| in the selected frame. There are special GDB commands to select |
| whichever frame you are interested in. *Note Selecting a Frame: |
| Selection. |
| |
| When your program stops, GDB automatically selects the currently |
| executing frame and describes it briefly, similar to the `frame' |
| command (*note Information about a Frame: Frame Info.). |
| |
| * Menu: |
| |
| * Frames:: Stack frames |
| * Backtrace:: Backtraces |
| * Selection:: Selecting a frame |
| * Frame Info:: Information on a frame |
| |
| |
| File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack |
| |
| 6.1 Stack Frames |
| ================ |
| |
| The call stack is divided up into contiguous pieces called "stack |
| frames", or "frames" for short; each frame is the data associated with |
| one call to one function. The frame contains the arguments given to |
| the function, the function's local variables, and the address at which |
| the function is executing. |
| |
| When your program is started, the stack has only one frame, that of |
| the function `main'. This is called the "initial" frame or the |
| "outermost" frame. Each time a function is called, a new frame is |
| made. Each time a function returns, the frame for that function |
| invocation is eliminated. If a function is recursive, there can be |
| many frames for the same function. The frame for the function in which |
| execution is actually occurring is called the "innermost" frame. This |
| is the most recently created of all the stack frames that still exist. |
| |
| Inside your program, stack frames are identified by their addresses. |
| A stack frame consists of many bytes, each of which has its own |
| address; each kind of computer has a convention for choosing one byte |
| whose address serves as the address of the frame. Usually this address |
| is kept in a register called the "frame pointer register" (*note $fp: |
| Registers.) while execution is going on in that frame. |
| |
| GDB assigns numbers to all existing stack frames, starting with zero |
| for the innermost frame, one for the frame that called it, and so on |
| upward. These numbers do not really exist in your program; they are |
| assigned by GDB to give you a way of designating stack frames in GDB |
| commands. |
| |
| Some compilers provide a way to compile functions so that they |
| operate without stack frames. (For example, the GCC option |
| `-fomit-frame-pointer' |
| generates functions without a frame.) This is occasionally done |
| with heavily used library functions to save the frame setup time. GDB |
| has limited facilities for dealing with these function invocations. If |
| the innermost function invocation has no stack frame, GDB nevertheless |
| regards it as though it had a separate frame, which is numbered zero as |
| usual, allowing correct tracing of the function call chain. However, |
| GDB has no provision for frameless functions elsewhere in the stack. |
| |
| `frame ARGS' |
| The `frame' command allows you to move from one stack frame to |
| another, and to print the stack frame you select. ARGS may be |
| either the address of the frame or the stack frame number. |
| Without an argument, `frame' prints the current stack frame. |
| |
| `select-frame' |
| The `select-frame' command allows you to move from one stack frame |
| to another without printing the frame. This is the silent version |
| of `frame'. |
| |
| |
| File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack |
| |
| 6.2 Backtraces |
| ============== |
| |
| A backtrace is a summary of how your program got where it is. It shows |
| one line per frame, for many frames, starting with the currently |
| executing frame (frame zero), followed by its caller (frame one), and |
| on up the stack. |
| |
| `backtrace' |
| `bt' |
| Print a backtrace of the entire stack: one line per frame for all |
| frames in the stack. |
| |
| You can stop the backtrace at any time by typing the system |
| interrupt character, normally `Ctrl-c'. |
| |
| `backtrace N' |
| `bt N' |
| Similar, but print only the innermost N frames. |
| |
| `backtrace -N' |
| `bt -N' |
| Similar, but print only the outermost N frames. |
| |
| `backtrace full' |
| `bt full' |
| `bt full N' |
| `bt full -N' |
| Print the values of the local variables also. N specifies the |
| number of frames to print, as described above. |
| |
| The names `where' and `info stack' (abbreviated `info s') are |
| additional aliases for `backtrace'. |
| |
| In a multi-threaded program, GDB by default shows the backtrace only |
| for the current thread. To display the backtrace for several or all of |
| the threads, use the command `thread apply' (*note thread apply: |
| Threads.). For example, if you type `thread apply all backtrace', GDB |
| will display the backtrace for all the threads; this is handy when you |
| debug a core dump of a multi-threaded program. |
| |
| Each line in the backtrace shows the frame number and the function |
| name. The program counter value is also shown--unless you use `set |
| print address off'. The backtrace also shows the source file name and |
| line number, as well as the arguments to the function. The program |
| counter value is omitted if it is at the beginning of the code for that |
| line number. |
| |
| Here is an example of a backtrace. It was made with the command `bt |
| 3', so it shows the innermost three frames. |
| |
| #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) |
| at builtin.c:993 |
| #1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242 |
| #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) |
| at macro.c:71 |
| (More stack frames follow...) |
| |
| The display for frame zero does not begin with a program counter value, |
| indicating that your program has stopped at the beginning of the code |
| for line `993' of `builtin.c'. |
| |
| If your program was compiled with optimizations, some compilers will |
| optimize away arguments passed to functions if those arguments are |
| never used after the call. Such optimizations generate code that |
| passes arguments through registers, but doesn't store those arguments |
| in the stack frame. GDB has no way of displaying such arguments in |
| stack frames other than the innermost one. Here's what such a |
| backtrace might look like: |
| |
| #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) |
| at builtin.c:993 |
| #1 0x6e38 in expand_macro (sym=<value optimized out>) at macro.c:242 |
| #2 0x6840 in expand_token (obs=0x0, t=<value optimized out>, td=0xf7fffb08) |
| at macro.c:71 |
| (More stack frames follow...) |
| |
| The values of arguments that were not saved in their stack frames are |
| shown as `<value optimized out>'. |
| |
| If you need to display the values of such optimized-out arguments, |
| either deduce that from other variables whose values depend on the one |
| you are interested in, or recompile without optimizations. |
| |
| Most programs have a standard user entry point--a place where system |
| libraries and startup code transition into user code. For C this is |
| `main'(1). When GDB finds the entry function in a backtrace it will |
| terminate the backtrace, to avoid tracing into highly system-specific |
| (and generally uninteresting) code. |
| |
| If you need to examine the startup code, or limit the number of |
| levels in a backtrace, you can change this behavior: |
| |
| `set backtrace past-main' |
| `set backtrace past-main on' |
| Backtraces will continue past the user entry point. |
| |
| `set backtrace past-main off' |
| Backtraces will stop when they encounter the user entry point. |
| This is the default. |
| |
| `show backtrace past-main' |
| Display the current user entry point backtrace policy. |
| |
| `set backtrace past-entry' |
| `set backtrace past-entry on' |
| Backtraces will continue past the internal entry point of an |
| application. This entry point is encoded by the linker when the |
| application is built, and is likely before the user entry point |
| `main' (or equivalent) is called. |
| |
| `set backtrace past-entry off' |
| Backtraces will stop when they encounter the internal entry point |
| of an application. This is the default. |
| |
| `show backtrace past-entry' |
| Display the current internal entry point backtrace policy. |
| |
| `set backtrace limit N' |
| `set backtrace limit 0' |
| Limit the backtrace to N levels. A value of zero means unlimited. |
| |
| `show backtrace limit' |
| Display the current limit on backtrace levels. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Note that embedded programs (the so-called "free-standing" |
| environment) are not required to have a `main' function as the entry |
| point. They could even have multiple entry points. |
| |
| |
| File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack |
| |
| 6.3 Selecting a Frame |
| ===================== |
| |
| Most commands for examining the stack and other data in your program |
| work on whichever stack frame is selected at the moment. Here are the |
| commands for selecting a stack frame; all of them finish by printing a |
| brief description of the stack frame just selected. |
| |
| `frame N' |
| `f N' |
| Select frame number N. Recall that frame zero is the innermost |
| (currently executing) frame, frame one is the frame that called the |
| innermost one, and so on. The highest-numbered frame is the one |
| for `main'. |
| |
| `frame ADDR' |
| `f ADDR' |
| Select the frame at address ADDR. This is useful mainly if the |
| chaining of stack frames has been damaged by a bug, making it |
| impossible for GDB to assign numbers properly to all frames. In |
| addition, this can be useful when your program has multiple stacks |
| and switches between them. |
| |
| On the SPARC architecture, `frame' needs two addresses to select |
| an arbitrary frame: a frame pointer and a stack pointer. |
| |
| On the MIPS and Alpha architecture, it needs two addresses: a stack |
| pointer and a program counter. |
| |
| On the 29k architecture, it needs three addresses: a register stack |
| pointer, a program counter, and a memory stack pointer. |
| |
| `up N' |
| Move N frames up the stack. For positive numbers N, this advances |
| toward the outermost frame, to higher frame numbers, to frames |
| that have existed longer. N defaults to one. |
| |
| `down N' |
| Move N frames down the stack. For positive numbers N, this |
| advances toward the innermost frame, to lower frame numbers, to |
| frames that were created more recently. N defaults to one. You |
| may abbreviate `down' as `do'. |
| |
| All of these commands end by printing two lines of output describing |
| the frame. The first line shows the frame number, the function name, |
| the arguments, and the source file and line number of execution in that |
| frame. The second line shows the text of that source line. |
| |
| For example: |
| |
| (gdb) up |
| #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) |
| at env.c:10 |
| 10 read_input_file (argv[i]); |
| |
| After such a printout, the `list' command with no arguments prints |
| ten lines centered on the point of execution in the frame. You can |
| also edit the program at the point of execution with your favorite |
| editing program by typing `edit'. *Note Printing Source Lines: List, |
| for details. |
| |
| `up-silently N' |
| `down-silently N' |
| These two commands are variants of `up' and `down', respectively; |
| they differ in that they do their work silently, without causing |
| display of the new frame. They are intended primarily for use in |
| GDB command scripts, where the output might be unnecessary and |
| distracting. |
| |
| |
| File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack |
| |
| 6.4 Information About a Frame |
| ============================= |
| |
| There are several other commands to print information about the selected |
| stack frame. |
| |
| `frame' |
| `f' |
| When used without any argument, this command does not change which |
| frame is selected, but prints a brief description of the currently |
| selected stack frame. It can be abbreviated `f'. With an |
| argument, this command is used to select a stack frame. *Note |
| Selecting a Frame: Selection. |
| |
| `info frame' |
| `info f' |
| This command prints a verbose description of the selected stack |
| frame, including: |
| |
| * the address of the frame |
| |
| * the address of the next frame down (called by this frame) |
| |
| * the address of the next frame up (caller of this frame) |
| |
| * the language in which the source code corresponding to this |
| frame is written |
| |
| * the address of the frame's arguments |
| |
| * the address of the frame's local variables |
| |
| * the program counter saved in it (the address of execution in |
| the caller frame) |
| |
| * which registers were saved in the frame |
| |
| The verbose description is useful when something has gone wrong |
| that has made the stack format fail to fit the usual conventions. |
| |
| `info frame ADDR' |
| `info f ADDR' |
| Print a verbose description of the frame at address ADDR, without |
| selecting that frame. The selected frame remains unchanged by this |
| command. This requires the same kind of address (more than one |
| for some architectures) that you specify in the `frame' command. |
| *Note Selecting a Frame: Selection. |
| |
| `info args' |
| Print the arguments of the selected frame, each on a separate line. |
| |
| `info locals' |
| Print the local variables of the selected frame, each on a separate |
| line. These are all variables (declared either static or |
| automatic) accessible at the point of execution of the selected |
| frame. |
| |
| `info catch' |
| Print a list of all the exception handlers that are active in the |
| current stack frame at the current point of execution. To see |
| other exception handlers, visit the associated frame (using the |
| `up', `down', or `frame' commands); then type `info catch'. *Note |
| Setting Catchpoints: Set Catchpoints. |
| |
| |
| |
| File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top |
| |
| 7 Examining Source Files |
| ************************ |
| |
| GDB can print parts of your program's source, since the debugging |
| information recorded in the program tells GDB what source files were |
| used to build it. When your program stops, GDB spontaneously prints |
| the line where it stopped. Likewise, when you select a stack frame |
| (*note Selecting a Frame: Selection.), GDB prints the line where |
| execution in that frame has stopped. You can print other portions of |
| source files by explicit command. |
| |
| If you use GDB through its GNU Emacs interface, you may prefer to |
| use Emacs facilities to view source; see *note Using GDB under GNU |
| Emacs: Emacs. |
| |
| * Menu: |
| |
| * List:: Printing source lines |
| * Specify Location:: How to specify code locations |
| * Edit:: Editing source files |
| * Search:: Searching source files |
| * Source Path:: Specifying source directories |
| * Machine Code:: Source and machine code |
| |
| |
| File: gdb.info, Node: List, Next: Specify Location, Up: Source |
| |
| 7.1 Printing Source Lines |
| ========================= |
| |
| To print lines from a source file, use the `list' command (abbreviated |
| `l'). By default, ten lines are printed. There are several ways to |
| specify what part of the file you want to print; see *note Specify |
| Location::, for the full list. |
| |
| Here are the forms of the `list' command most commonly used: |
| |
| `list LINENUM' |
| Print lines centered around line number LINENUM in the current |
| source file. |
| |
| `list FUNCTION' |
| Print lines centered around the beginning of function FUNCTION. |
| |
| `list' |
| Print more lines. If the last lines printed were printed with a |
| `list' command, this prints lines following the last lines |
| printed; however, if the last line printed was a solitary line |
| printed as part of displaying a stack frame (*note Examining the |
| Stack: Stack.), this prints lines centered around that line. |
| |
| `list -' |
| Print lines just before the lines last printed. |
| |
| By default, GDB prints ten source lines with any of these forms of |
| the `list' command. You can change this using `set listsize': |
| |
| `set listsize COUNT' |
| Make the `list' command display COUNT source lines (unless the |
| `list' argument explicitly specifies some other number). |
| |
| `show listsize' |
| Display the number of lines that `list' prints. |
| |
| Repeating a `list' command with <RET> discards the argument, so it |
| is equivalent to typing just `list'. This is more useful than listing |
| the same lines again. An exception is made for an argument of `-'; |
| that argument is preserved in repetition so that each repetition moves |
| up in the source file. |
| |
| In general, the `list' command expects you to supply zero, one or two |
| "linespecs". Linespecs specify source lines; there are several ways of |
| writing them (*note Specify Location::), but the effect is always to |
| specify some source line. |
| |
| Here is a complete description of the possible arguments for `list': |
| |
| `list LINESPEC' |
| Print lines centered around the line specified by LINESPEC. |
| |
| `list FIRST,LAST' |
| Print lines from FIRST to LAST. Both arguments are linespecs. |
| When a `list' command has two linespecs, and the source file of |
| the second linespec is omitted, this refers to the same source |
| file as the first linespec. |
| |
| `list ,LAST' |
| Print lines ending with LAST. |
| |
| `list FIRST,' |
| Print lines starting with FIRST. |
| |
| `list +' |
| Print lines just after the lines last printed. |
| |
| `list -' |
| Print lines just before the lines last printed. |
| |
| `list' |
| As described in the preceding table. |
| |
| |
| File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source |
| |
| 7.2 Specifying a Location |
| ========================= |
| |
| Several GDB commands accept arguments that specify a location of your |
| program's code. Since GDB is a source-level debugger, a location |
| usually specifies some line in the source code; for that reason, |
| locations are also known as "linespecs". |
| |
| Here are all the different ways of specifying a code location that |
| GDB understands: |
| |
| `LINENUM' |
| Specifies the line number LINENUM of the current source file. |
| |
| `-OFFSET' |
| `+OFFSET' |
| Specifies the line OFFSET lines before or after the "current |
| line". For the `list' command, the current line is the last one |
| printed; for the breakpoint commands, this is the line at which |
| execution stopped in the currently selected "stack frame" (*note |
| Frames: Frames, for a description of stack frames.) When used as |
| the second of the two linespecs in a `list' command, this |
| specifies the line OFFSET lines up or down from the first linespec. |
| |
| `FILENAME:LINENUM' |
| Specifies the line LINENUM in the source file FILENAME. |
| |
| `FUNCTION' |
| Specifies the line that begins the body of the function FUNCTION. |
| For example, in C, this is the line with the open brace. |
| |
| `FILENAME:FUNCTION' |
| Specifies the line that begins the body of the function FUNCTION |
| in the file FILENAME. You only need the file name with a function |
| name to avoid ambiguity when there are identically named functions |
| in different source files. |
| |
| `*ADDRESS' |
| Specifies the program address ADDRESS. For line-oriented |
| commands, such as `list' and `edit', this specifies a source line |
| that contains ADDRESS. For `break' and other breakpoint oriented |
| commands, this can be used to set breakpoints in parts of your |
| program which do not have debugging information or source files. |
| |
| Here ADDRESS may be any expression valid in the current working |
| language (*note working language: Languages.) that specifies a code |
| address. In addition, as a convenience, GDB extends the semantics |
| of expressions used in locations to cover the situations that |
| frequently happen during debugging. Here are the various forms of |
| ADDRESS: |
| |
| `EXPRESSION' |
| Any expression valid in the current working language. |
| |
| `FUNCADDR' |
| An address of a function or procedure derived from its name. |
| In C, C++, Java, Objective-C, Fortran, minimal, and assembly, |
| this is simply the function's name FUNCTION (and actually a |
| special case of a valid expression). In Pascal and Modula-2, |
| this is `&FUNCTION'. In Ada, this is `FUNCTION'Address' |
| (although the Pascal form also works). |
| |
| This form specifies the address of the function's first |
| instruction, before the stack frame and arguments have been |
| set up. |
| |
| `'FILENAME'::FUNCADDR' |
| Like FUNCADDR above, but also specifies the name of the source |
| file explicitly. This is useful if the name of the function |
| does not specify the function unambiguously, e.g., if there |
| are several functions with identical names in different |
| source files. |
| |
| |
| |
| File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source |
| |
| 7.3 Editing Source Files |
| ======================== |
| |
| To edit the lines in a source file, use the `edit' command. The |
| editing program of your choice is invoked with the current line set to |
| the active line in the program. Alternatively, there are several ways |
| to specify what part of the file you want to print if you want to see |
| other parts of the program: |
| |
| `edit LOCATION' |
| Edit the source file specified by `location'. Editing starts at |
| that LOCATION, e.g., at the specified source line of the specified |
| file. *Note Specify Location::, for all the possible forms of the |
| LOCATION argument; here are the forms of the `edit' command most |
| commonly used: |
| |
| `edit NUMBER' |
| Edit the current source file with NUMBER as the active line |
| number. |
| |
| `edit FUNCTION' |
| Edit the file containing FUNCTION at the beginning of its |
| definition. |
| |
| |
| 7.3.1 Choosing your Editor |
| -------------------------- |
| |
| You can customize GDB to use any editor you want (1). By default, it |
| is `/bin/ex', but you can change this by setting the environment |
| variable `EDITOR' before using GDB. For example, to configure GDB to |
| use the `vi' editor, you could use these commands with the `sh' shell: |
| EDITOR=/usr/bin/vi |
| export EDITOR |
| gdb ... |
| or in the `csh' shell, |
| setenv EDITOR /usr/bin/vi |
| gdb ... |
| |
| ---------- Footnotes ---------- |
| |
| (1) The only restriction is that your editor (say `ex'), recognizes |
| the following command-line syntax: |
| ex +NUMBER file |
| The optional numeric value +NUMBER specifies the number of the line |
| in the file where to start editing. |
| |
| |
| File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source |
| |
| 7.4 Searching Source Files |
| ========================== |
| |
| There are two commands for searching through the current source file |
| for a regular expression. |
| |
| `forward-search REGEXP' |
| `search REGEXP' |
| The command `forward-search REGEXP' checks each line, starting |
| with the one following the last line listed, for a match for |
| REGEXP. It lists the line that is found. You can use the synonym |
| `search REGEXP' or abbreviate the command name as `fo'. |
| |
| `reverse-search REGEXP' |
| The command `reverse-search REGEXP' checks each line, starting |
| with the one before the last line listed and going backward, for a |
| match for REGEXP. It lists the line that is found. You can |
| abbreviate this command as `rev'. |
| |
| |
| File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source |
| |
| 7.5 Specifying Source Directories |
| ================================= |
| |
| Executable programs sometimes do not record the directories of the |
| source files from which they were compiled, just the names. Even when |
| they do, the directories could be moved between the compilation and |
| your debugging session. GDB has a list of directories to search for |
| source files; this is called the "source path". Each time GDB wants a |
| source file, it tries all the directories in the list, in the order |
| they are present in the list, until it finds a file with the desired |
| name. |
| |
| For example, suppose an executable references the file |
| `/usr/src/foo-1.0/lib/foo.c', and our source path is `/mnt/cross'. The |
| file is first looked up literally; if this fails, |
| `/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails, |
| `/mnt/cross/foo.c' is opened; if this fails, an error message is |
| printed. GDB does not look up the parts of the source file name, such |
| as `/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of |
| the source path are not searched: if the source path is `/mnt/cross', |
| and the binary refers to `foo.c', GDB would not find it under |
| `/mnt/cross/usr/src/foo-1.0/lib'. |
| |
| Plain file names, relative file names with leading directories, file |
| names containing dots, etc. are all treated as described above; for |
| instance, if the source path is `/mnt/cross', and the source file is |
| recorded as `../lib/foo.c', GDB would first try `../lib/foo.c', then |
| `/mnt/cross/../lib/foo.c', and after that--`/mnt/cross/foo.c'. |
| |
| Note that the executable search path is _not_ used to locate the |
| source files. |
| |
| Whenever you reset or rearrange the source path, GDB clears out any |
| information it has cached about where source files are found and where |
| each line is in the file. |
| |
| When you start GDB, its source path includes only `cdir' and `cwd', |
| in that order. To add other directories, use the `directory' command. |
| |
| The search path is used to find both program source files and GDB |
| script files (read using the `-command' option and `source' command). |
| |
| In addition to the source path, GDB provides a set of commands that |
| manage a list of source path substitution rules. A "substitution rule" |
| specifies how to rewrite source directories stored in the program's |
| debug information in case the sources were moved to a different |
| directory between compilation and debugging. A rule is made of two |
| strings, the first specifying what needs to be rewritten in the path, |
| and the second specifying how it should be rewritten. In *note set |
| substitute-path::, we name these two parts FROM and TO respectively. |
| GDB does a simple string replacement of FROM with TO at the start of |
| the directory part of the source file name, and uses that result |
| instead of the original file name to look up the sources. |
| |
| Using the previous example, suppose the `foo-1.0' tree has been |
| moved from `/usr/src' to `/mnt/cross', then you can tell GDB to replace |
| `/usr/src' in all source path names with `/mnt/cross'. The first |
| lookup will then be `/mnt/cross/foo-1.0/lib/foo.c' in place of the |
| original location of `/usr/src/foo-1.0/lib/foo.c'. To define a source |
| path substitution rule, use the `set substitute-path' command (*note |
| set substitute-path::). |
| |
| To avoid unexpected substitution results, a rule is applied only if |
| the FROM part of the directory name ends at a directory separator. For |
| instance, a rule substituting `/usr/source' into `/mnt/cross' will be |
| applied to `/usr/source/foo-1.0' but not to `/usr/sourceware/foo-2.0'. |
| And because the substitution is applied only at the beginning of the |
| directory name, this rule will not be applied to |
| `/root/usr/source/baz.c' either. |
| |
| In many cases, you can achieve the same result using the `directory' |
| command. However, `set substitute-path' can be more efficient in the |
| case where the sources are organized in a complex tree with multiple |
| subdirectories. With the `directory' command, you need to add each |
| subdirectory of your project. If you moved the entire tree while |
| preserving its internal organization, then `set substitute-path' allows |
| you to direct the debugger to all the sources with one single command. |
| |
| `set substitute-path' is also more than just a shortcut command. |
| The source path is only used if the file at the original location no |
| longer exists. On the other hand, `set substitute-path' modifies the |
| debugger behavior to look at the rewritten location instead. So, if |
| for any reason a source file that is not relevant to your executable is |
| located at the original location, a substitution rule is the only |
| method available to point GDB at the new location. |
| |
| `directory DIRNAME ...' |
| |
| `dir DIRNAME ...' |
| Add directory DIRNAME to the front of the source path. Several |
| directory names may be given to this command, separated by `:' |
| (`;' on MS-DOS and MS-Windows, where `:' usually appears as part |
| of absolute file names) or whitespace. You may specify a |
| directory that is already in the source path; this moves it |
| forward, so GDB searches it sooner. |
| |
| You can use the string `$cdir' to refer to the compilation |
| directory (if one is recorded), and `$cwd' to refer to the current |
| working directory. `$cwd' is not the same as `.'--the former |
| tracks the current working directory as it changes during your GDB |
| session, while the latter is immediately expanded to the current |
| directory at the time you add an entry to the source path. |
| |
| `directory' |
| Reset the source path to its default value (`$cdir:$cwd' on Unix |
| systems). This requires confirmation. |
| |
| `show directories' |
| Print the source path: show which directories it contains. |
| |
| `set substitute-path FROM TO' |
| Define a source path substitution rule, and add it at the end of |
| the current list of existing substitution rules. If a rule with |
| the same FROM was already defined, then the old rule is also |
| deleted. |
| |
| For example, if the file `/foo/bar/baz.c' was moved to |
| `/mnt/cross/baz.c', then the command |
| |
| (gdb) set substitute-path /usr/src /mnt/cross |
| |
| will tell GDB to replace `/usr/src' with `/mnt/cross', which will |
| allow GDB to find the file `baz.c' even though it was moved. |
| |
| In the case when more than one substitution rule have been defined, |
| the rules are evaluated one by one in the order where they have |
| been defined. The first one matching, if any, is selected to |
| perform the substitution. |
| |
| For instance, if we had entered the following commands: |
| |
| (gdb) set substitute-path /usr/src/include /mnt/include |
| (gdb) set substitute-path /usr/src /mnt/src |
| |
| GDB would then rewrite `/usr/src/include/defs.h' into |
| `/mnt/include/defs.h' by using the first rule. However, it would |
| use the second rule to rewrite `/usr/src/lib/foo.c' into |
| `/mnt/src/lib/foo.c'. |
| |
| `unset substitute-path [path]' |
| If a path is specified, search the current list of substitution |
| rules for a rule that would rewrite that path. Delete that rule |
| if found. A warning is emitted by the debugger if no rule could |
| be found. |
| |
| If no path is specified, then all substitution rules are deleted. |
| |
| `show substitute-path [path]' |
| If a path is specified, then print the source path substitution |
| rule which would rewrite that path, if any. |
| |
| If no path is specified, then print all existing source path |
| substitution rules. |
| |
| |
| If your source path is cluttered with directories that are no longer |
| of interest, GDB may sometimes cause confusion by finding the wrong |
| versions of source. You can correct the situation as follows: |
| |
| 1. Use `directory' with no argument to reset the source path to its |
| default value. |
| |
| 2. Use `directory' with suitable arguments to reinstall the |
| directories you want in the source path. You can add all the |
| directories in one command. |
| |
| |
| File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source |
| |
| 7.6 Source and Machine Code |
| =========================== |
| |
| You can use the command `info line' to map source lines to program |
| addresses (and vice versa), and the command `disassemble' to display a |
| range of addresses as machine instructions. When run under GNU Emacs |
| mode, the `info line' command causes the arrow to point to the line |
| specified. Also, `info line' prints addresses in symbolic form as well |
| as hex. |
| |
| `info line LINESPEC' |
| Print the starting and ending addresses of the compiled code for |
| source line LINESPEC. You can specify source lines in any of the |
| ways documented in *note Specify Location::. |
| |
| For example, we can use `info line' to discover the location of the |
| object code for the first line of function `m4_changequote': |
| |
| (gdb) info line m4_changequote |
| Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. |
| |
| We can also inquire (using `*ADDR' as the form for LINESPEC) what |
| source line covers a particular address: |
| (gdb) info line *0x63ff |
| Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. |
| |
| After `info line', the default address for the `x' command is |
| changed to the starting address of the line, so that `x/i' is |
| sufficient to begin examining the machine code (*note Examining Memory: |
| Memory.). Also, this address is saved as the value of the convenience |
| variable `$_' (*note Convenience Variables: Convenience Vars.). |
| |
| `disassemble' |
| This specialized command dumps a range of memory as machine |
| instructions. The default memory range is the function |
| surrounding the program counter of the selected frame. A single |
| argument to this command is a program counter value; GDB dumps the |
| function surrounding this value. Two arguments specify a range of |
| addresses (first inclusive, second exclusive) to dump. |
| |
| The following example shows the disassembly of a range of addresses |
| of HP PA-RISC 2.0 code: |
| |
| (gdb) disas 0x32c4 0x32e4 |
| Dump of assembler code from 0x32c4 to 0x32e4: |
| 0x32c4 <main+204>: addil 0,dp |
| 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 |
| 0x32cc <main+212>: ldil 0x3000,r31 |
| 0x32d0 <main+216>: ble 0x3f8(sr4,r31) |
| 0x32d4 <main+220>: ldo 0(r31),rp |
| 0x32d8 <main+224>: addil -0x800,dp |
| 0x32dc <main+228>: ldo 0x588(r1),r26 |
| 0x32e0 <main+232>: ldil 0x3000,r31 |
| End of assembler dump. |
| |
| Some architectures have more than one commonly-used set of |
| instruction mnemonics or other syntax. |
| |
| For programs that were dynamically linked and use shared libraries, |
| instructions that call functions or branch to locations in the shared |
| libraries might show a seemingly bogus location--it's actually a |
| location of the relocation table. On some architectures, GDB might be |
| able to resolve these to actual function names. |
| |
| `set disassembly-flavor INSTRUCTION-SET' |
| Select the instruction set to use when disassembling the program |
| via the `disassemble' or `x/i' commands. |
| |
| Currently this command is only defined for the Intel x86 family. |
| You can set INSTRUCTION-SET to either `intel' or `att'. The |
| default is `att', the AT&T flavor used by default by Unix |
| assemblers for x86-based targets. |
| |
| `show disassembly-flavor' |
| Show the current setting of the disassembly flavor. |
| |
| |
| File: gdb.info, Node: Data, Next: Macros, Prev: Source, Up: Top |
| |
| 8 Examining Data |
| **************** |
| |
| The usual way to examine data in your program is with the `print' |
| command (abbreviated `p'), or its synonym `inspect'. It evaluates and |
| prints the value of an expression of the language your program is |
| written in (*note Using GDB with Different Languages: Languages.). |
| |
| `print EXPR' |
| `print /F EXPR' |
| EXPR is an expression (in the source language). By default the |
| value of EXPR is printed in a format appropriate to its data type; |
| you can choose a different format by specifying `/F', where F is a |
| letter specifying the format; see *note Output Formats: Output |
| Formats. |
| |
| `print' |
| `print /F' |
| If you omit EXPR, GDB displays the last value again (from the |
| "value history"; *note Value History: Value History.). This |
| allows you to conveniently inspect the same value in an |
| alternative format. |
| |
| A more low-level way of examining data is with the `x' command. It |
| examines data in memory at a specified address and prints it in a |
| specified format. *Note Examining Memory: Memory. |
| |
| If you are interested in information about types, or about how the |
| fields of a struct or a class are declared, use the `ptype EXP' command |
| rather than `print'. *Note Examining the Symbol Table: Symbols. |
| |
| * Menu: |
| |
| * Expressions:: Expressions |
| * Variables:: Program variables |
| * Arrays:: Artificial arrays |
| * Output Formats:: Output formats |
| * Memory:: Examining memory |
| * Auto Display:: Automatic display |
| * Print Settings:: Print settings |
| * Value History:: Value history |
| * Convenience Vars:: Convenience variables |
| * Registers:: Registers |
| * Floating Point Hardware:: Floating point hardware |
| * Vector Unit:: Vector Unit |
| * OS Information:: Auxiliary data provided by operating system |
| * Memory Region Attributes:: Memory region attributes |
| * Dump/Restore Files:: Copy between memory and a file |
| * Core File Generation:: Cause a program dump its core |
| * Character Sets:: Debugging programs that use a different |
| character set than GDB does |
| * Caching Remote Data:: Data caching for remote targets |
| |
| |
| File: gdb.info, Node: Expressions, Next: Variables, Up: Data |
| |
| 8.1 Expressions |
| =============== |
| |
| `print' and many other GDB commands accept an expression and compute |
| its value. Any kind of constant, variable or operator defined by the |
| programming language you are using is valid in an expression in GDB. |
| This includes conditional expressions, function calls, casts, and |
| string constants. It also includes preprocessor macros, if you |
| compiled your program to include this information; see *note |
| Compilation::. |
| |
| GDB supports array constants in expressions input by the user. The |
| syntax is {ELEMENT, ELEMENT...}. For example, you can use the command |
| `print {1, 2, 3}' to build up an array in memory that is `malloc'ed in |
| the target program. |
| |
| Because C is so widespread, most of the expressions shown in |
| examples in this manual are in C. *Note Using GDB with Different |
| Languages: Languages, for information on how to use expressions in other |
| languages. |
| |
| In this section, we discuss operators that you can use in GDB |
| expressions regardless of your programming language. |
| |
| Casts are supported in all languages, not just in C, because it is so |
| useful to cast a number into a pointer in order to examine a structure |
| at that address in memory. |
| |
| GDB supports these operators, in addition to those common to |
| programming languages: |
| |
| `@' |
| `@' is a binary operator for treating parts of memory as arrays. |
| *Note Artificial Arrays: Arrays, for more information. |
| |
| `::' |
| `::' allows you to specify a variable in terms of the file or |
| function where it is defined. *Note Program Variables: Variables. |
| |
| `{TYPE} ADDR' |
| Refers to an object of type TYPE stored at address ADDR in memory. |
| ADDR may be any expression whose value is an integer or pointer |
| (but parentheses are required around binary operators, just as in |
| a cast). This construct is allowed regardless of what kind of |
| data is normally supposed to reside at ADDR. |
| |
| |
| File: gdb.info, Node: Variables, Next: Arrays, Prev: Expressions, Up: Data |
| |
| 8.2 Program Variables |
| ===================== |
| |
| The most common kind of expression to use is the name of a variable in |
| your program. |
| |
| Variables in expressions are understood in the selected stack frame |
| (*note Selecting a Frame: Selection.); they must be either: |
| |
| * global (or file-static) |
| |
| or |
| |
| * visible according to the scope rules of the programming language |
| from the point of execution in that frame |
| |
| This means that in the function |
| |
| foo (a) |
| int a; |
| { |
| bar (a); |
| { |
| int b = test (); |
| bar (b); |
| } |
| } |
| |
| you can examine and use the variable `a' whenever your program is |
| executing within the function `foo', but you can only use or examine |
| the variable `b' while your program is executing inside the block where |
| `b' is declared. |
| |
| There is an exception: you can refer to a variable or function whose |
| scope is a single source file even if the current execution point is not |
| in this file. But it is possible to have more than one such variable or |
| function with the same name (in different source files). If that |
| happens, referring to that name has unpredictable effects. If you wish, |
| you can specify a static variable in a particular function or file, |
| using the colon-colon (`::') notation: |
| |
| FILE::VARIABLE |
| FUNCTION::VARIABLE |
| |
| Here FILE or FUNCTION is the name of the context for the static |
| VARIABLE. In the case of file names, you can use quotes to make sure |
| GDB parses the file name as a single word--for example, to print a |
| global value of `x' defined in `f2.c': |
| |
| (gdb) p 'f2.c'::x |
| |
| This use of `::' is very rarely in conflict with the very similar |
| use of the same notation in C++. GDB also supports use of the C++ |
| scope resolution operator in GDB expressions. |
| |
| _Warning:_ Occasionally, a local variable may appear to have the |
| wrong value at certain points in a function--just after entry to a |
| new scope, and just before exit. |
| You may see this problem when you are stepping by machine |
| instructions. This is because, on most machines, it takes more than |
| one instruction to set up a stack frame (including local variable |
| definitions); if you are stepping by machine instructions, variables |
| may appear to have the wrong values until the stack frame is completely |
| built. On exit, it usually also takes more than one machine |
| instruction to destroy a stack frame; after you begin stepping through |
| that group of instructions, local variable definitions may be gone. |
| |
| This may also happen when the compiler does significant |
| optimizations. To be sure of always seeing accurate values, turn off |
| all optimization when compiling. |
| |
| Another possible effect of compiler optimizations is to optimize |
| unused variables out of existence, or assign variables to registers (as |
| opposed to memory addresses). Depending on the support for such cases |
| offered by the debug info format used by the compiler, GDB might not be |
| able to display values for such local variables. If that happens, GDB |
| will print a message like this: |
| |
| No symbol "foo" in current context. |
| |
| To solve such problems, either recompile without optimizations, or |
| use a different debug info format, if the compiler supports several such |
| formats. For example, GCC, the GNU C/C++ compiler, usually supports |
| the `-gstabs+' option. `-gstabs+' produces debug info in a format that |
| is superior to formats such as COFF. You may be able to use DWARF 2 |
| (`-gdwarf-2'), which is also an effective form for debug info. *Note |
| Options for Debugging Your Program or GCC: (gcc.info)Debugging Options. |
| *Note C and C++: C, for more information about debug info formats that |
| are best suited to C++ programs. |
| |
| If you ask to print an object whose contents are unknown to GDB, |
| e.g., because its data type is not completely specified by the debug |
| information, GDB will say `<incomplete type>'. *Note incomplete type: |
| Symbols, for more about this. |
| |
| Strings are identified as arrays of `char' values without specified |
| signedness. Arrays of either `signed char' or `unsigned char' get |
| printed as arrays of 1 byte sized integers. `-fsigned-char' or |
| `-funsigned-char' GCC options have no effect as GDB defines literal |
| string type `"char"' as `char' without a sign. For program code |
| |
| char var0[] = "A"; |
| signed char var1[] = "A"; |
| |
| You get during debugging |
| (gdb) print var0 |
| $1 = "A" |
| (gdb) print var1 |
| $2 = {65 'A', 0 '\0'} |
| |
| |
| File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data |
| |
| 8.3 Artificial Arrays |
| ===================== |
| |
| It is often useful to print out several successive objects of the same |
| type in memory; a section of an array, or an array of dynamically |
| determined size for which only a pointer exists in the program. |
| |
| You can do this by referring to a contiguous span of memory as an |
| "artificial array", using the binary operator `@'. The left operand of |
| `@' should be the first element of the desired array and be an |
| individual object. The right operand should be the desired length of |
| the array. The result is an array value whose elements are all of the |
| type of the left argument. The first element is actually the left |
| argument; the second element comes from bytes of memory immediately |
| following those that hold the first element, and so on. Here is an |
| example. If a program says |
| |
| int *array = (int *) malloc (len * sizeof (int)); |
| |
| you can print the contents of `array' with |
| |
| p *array@len |
| |
| The left operand of `@' must reside in memory. Array values made |
| with `@' in this way behave just like other arrays in terms of |
| subscripting, and are coerced to pointers when used in expressions. |
| Artificial arrays most often appear in expressions via the value history |
| (*note Value History: Value History.), after printing one out. |
| |
| Another way to create an artificial array is to use a cast. This |
| re-interprets a value as if it were an array. The value need not be in |
| memory: |
| (gdb) p/x (short[2])0x12345678 |
| $1 = {0x1234, 0x5678} |
| |
| As a convenience, if you leave the array length out (as in |
| `(TYPE[])VALUE') GDB calculates the size to fill the value (as |
| `sizeof(VALUE)/sizeof(TYPE)': |
| (gdb) p/x (short[])0x12345678 |
| $2 = {0x1234, 0x5678} |
| |
| Sometimes the artificial array mechanism is not quite enough; in |
| moderately complex data structures, the elements of interest may not |
| actually be adjacent--for example, if you are interested in the values |
| of pointers in an array. One useful work-around in this situation is |
| to use a convenience variable (*note Convenience Variables: Convenience |
| Vars.) as a counter in an expression that prints the first interesting |
| value, and then repeat that expression via <RET>. For instance, |
| suppose you have an array `dtab' of pointers to structures, and you are |
| interested in the values of a field `fv' in each structure. Here is an |
| example of what you might type: |
| |
| set $i = 0 |
| p dtab[$i++]->fv |
| <RET> |
| <RET> |
| ... |
| |
| |
| File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data |
| |
| 8.4 Output Formats |
| ================== |
| |
| By default, GDB prints a value according to its data type. Sometimes |
| this is not what you want. For example, you might want to print a |
| number in hex, or a pointer in decimal. Or you might want to view data |
| in memory at a certain address as a character string or as an |
| instruction. To do these things, specify an "output format" when you |
| print a value. |
| |
| The simplest use of output formats is to say how to print a value |
| already computed. This is done by starting the arguments of the |
| `print' command with a slash and a format letter. The format letters |
| supported are: |
| |
| `x' |
| Regard the bits of the value as an integer, and print the integer |
| in hexadecimal. |
| |
| `d' |
| Print as integer in signed decimal. |
| |
| `u' |
| Print as integer in unsigned decimal. |
| |
| `o' |
| Print as integer in octal. |
| |
| `t' |
| Print as integer in binary. The letter `t' stands for "two". (1) |
| |
| `a' |
| Print as an address, both absolute in hexadecimal and as an offset |
| from the nearest preceding symbol. You can use this format used |
| to discover where (in what function) an unknown address is located: |
| |
| (gdb) p/a 0x54320 |
| $3 = 0x54320 <_initialize_vx+396> |
| |
| The command `info symbol 0x54320' yields similar results. *Note |
| info symbol: Symbols. |
| |
| `c' |
| Regard as an integer and print it as a character constant. This |
| prints both the numerical value and its character representation. |
| The character representation is replaced with the octal escape |
| `\nnn' for characters outside the 7-bit ASCII range. |
| |
| Without this format, GDB displays `char', `unsigned char', and |
| `signed char' data as character constants. Single-byte members of |
| vectors are displayed as integer data. |
| |
| `f' |
| Regard the bits of the value as a floating point number and print |
| using typical floating point syntax. |
| |
| `s' |
| Regard as a string, if possible. With this format, pointers to |
| single-byte data are displayed as null-terminated strings and |
| arrays of single-byte data are displayed as fixed-length strings. |
| Other values are displayed in their natural types. |
| |
| Without this format, GDB displays pointers to and arrays of |
| `char', `unsigned char', and `signed char' as strings. |
| Single-byte members of a vector are displayed as an integer array. |
| |
| For example, to print the program counter in hex (*note |
| Registers::), type |
| |
| p/x $pc |
| |
| Note that no space is required before the slash; this is because command |
| names in GDB cannot contain a slash. |
| |
| To reprint the last value in the value history with a different |
| format, you can use the `print' command with just a format and no |
| expression. For example, `p/x' reprints the last value in hex. |
| |
| ---------- Footnotes ---------- |
| |
| (1) `b' cannot be used because these format letters are also used |
| with the `x' command, where `b' stands for "byte"; see *note Examining |
| Memory: Memory. |
| |
| |
| File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data |
| |
| 8.5 Examining Memory |
| ==================== |
| |
| You can use the command `x' (for "examine") to examine memory in any of |
| several formats, independently of your program's data types. |
| |
| `x/NFU ADDR' |
| `x ADDR' |
| `x' |
| Use the `x' command to examine memory. |
| |
| N, F, and U are all optional parameters that specify how much memory |
| to display and how to format it; ADDR is an expression giving the |
| address where you want to start displaying memory. If you use defaults |
| for NFU, you need not type the slash `/'. Several commands set |
| convenient defaults for ADDR. |
| |
| N, the repeat count |
| The repeat count is a decimal integer; the default is 1. It |
| specifies how much memory (counting by units U) to display. |
| |
| F, the display format |
| The display format is one of the formats used by `print' (`x', |
| `d', `u', `o', `t', `a', `c', `f', `s'), and in addition `i' (for |
| machine instructions). The default is `x' (hexadecimal) |
| initially. The default changes each time you use either `x' or |
| `print'. |
| |
| U, the unit size |
| The unit size is any of |
| |
| `b' |
| Bytes. |
| |
| `h' |
| Halfwords (two bytes). |
| |
| `w' |
| Words (four bytes). This is the initial default. |
| |
| `g' |
| Giant words (eight bytes). |
| |
| Each time you specify a unit size with `x', that size becomes the |
| default unit the next time you use `x'. (For the `s' and `i' |
| formats, the unit size is ignored and is normally not written.) |
| |
| ADDR, starting display address |
| ADDR is the address where you want GDB to begin displaying memory. |
| The expression need not have a pointer value (though it may); it |
| is always interpreted as an integer address of a byte of memory. |
| *Note Expressions: Expressions, for more information on |
| expressions. The default for ADDR is usually just after the last |
| address examined--but several other commands also set the default |
| address: `info breakpoints' (to the address of the last breakpoint |
| listed), `info line' (to the starting address of a line), and |
| `print' (if you use it to display a value from memory). |
| |
| For example, `x/3uh 0x54320' is a request to display three halfwords |
| (`h') of memory, formatted as unsigned decimal integers (`u'), starting |
| at address `0x54320'. `x/4xw $sp' prints the four words (`w') of |
| memory above the stack pointer (here, `$sp'; *note Registers: |
| Registers.) in hexadecimal (`x'). |
| |
| Since the letters indicating unit sizes are all distinct from the |
| letters specifying output formats, you do not have to remember whether |
| unit size or format comes first; either order works. The output |
| specifications `4xw' and `4wx' mean exactly the same thing. (However, |
| the count N must come first; `wx4' does not work.) |
| |
| Even though the unit size U is ignored for the formats `s' and `i', |
| you might still want to use a count N; for example, `3i' specifies that |
| you want to see three machine instructions, including any operands. |
| For convenience, especially when used with the `display' command, the |
| `i' format also prints branch delay slot instructions, if any, beyond |
| the count specified, which immediately follow the last instruction that |
| is within the count. The command `disassemble' gives an alternative |
| way of inspecting machine instructions; see *note Source and Machine |
| Code: Machine Code. |
| |
| All the defaults for the arguments to `x' are designed to make it |
| easy to continue scanning memory with minimal specifications each time |
| you use `x'. For example, after you have inspected three machine |
| instructions with `x/3i ADDR', you can inspect the next seven with just |
| `x/7'. If you use <RET> to repeat the `x' command, the repeat count N |
| is used again; the other arguments default as for successive uses of |
| `x'. |
| |
| The addresses and contents printed by the `x' command are not saved |
| in the value history because there is often too much of them and they |
| would get in the way. Instead, GDB makes these values available for |
| subsequent use in expressions as values of the convenience variables |
| `$_' and `$__'. After an `x' command, the last address examined is |
| available for use in expressions in the convenience variable `$_'. The |
| contents of that address, as examined, are available in the convenience |
| variable `$__'. |
| |
| If the `x' command has a repeat count, the address and contents saved |
| are from the last memory unit printed; this is not the same as the last |
| address printed if several units were printed on the last line of |
| output. |
| |
| When you are debugging a program running on a remote target machine |
| (*note Remote Debugging::), you may wish to verify the program's image |
| in the remote machine's memory against the executable file you |
| downloaded to the target. The `compare-sections' command is provided |
| for such situations. |
| |
| `compare-sections [SECTION-NAME]' |
| Compare the data of a loadable section SECTION-NAME in the |
| executable file of the program being debugged with the same |
| section in the remote machine's memory, and report any mismatches. |
| With no arguments, compares all loadable sections. This command's |
| availability depends on the target's support for the `"qCRC"' |
| remote request. |
| |
| |
| File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data |
| |
| 8.6 Automatic Display |
| ===================== |
| |
| If you find that you want to print the value of an expression frequently |
| (to see how it changes), you might want to add it to the "automatic |
| display list" so that GDB prints its value each time your program stops. |
| Each expression added to the list is given a number to identify it; to |
| remove an expression from the list, you specify that number. The |
| automatic display looks like this: |
| |
| 2: foo = 38 |
| 3: bar[5] = (struct hack *) 0x3804 |
| |
| This display shows item numbers, expressions and their current values. |
| As with displays you request manually using `x' or `print', you can |
| specify the output format you prefer; in fact, `display' decides |
| whether to use `print' or `x' depending your format specification--it |
| uses `x' if you specify either the `i' or `s' format, or a unit size; |
| otherwise it uses `print'. |
| |
| `display EXPR' |
| Add the expression EXPR to the list of expressions to display each |
| time your program stops. *Note Expressions: Expressions. |
| |
| `display' does not repeat if you press <RET> again after using it. |
| |
| `display/FMT EXPR' |
| For FMT specifying only a display format and not a size or count, |
| add the expression EXPR to the auto-display list but arrange to |
| display it each time in the specified format FMT. *Note Output |
| Formats: Output Formats. |
| |
| `display/FMT ADDR' |
| For FMT `i' or `s', or including a unit-size or a number of units, |
| add the expression ADDR as a memory address to be examined each |
| time your program stops. Examining means in effect doing `x/FMT |
| ADDR'. *Note Examining Memory: Memory. |
| |
| For example, `display/i $pc' can be helpful, to see the machine |
| instruction about to be executed each time execution stops (`$pc' is a |
| common name for the program counter; *note Registers: Registers.). |
| |
| `undisplay DNUMS...' |
| `delete display DNUMS...' |
| Remove item numbers DNUMS from the list of expressions to display. |
| |
| `undisplay' does not repeat if you press <RET> after using it. |
| (Otherwise you would just get the error `No display number ...'.) |
| |
| `disable display DNUMS...' |
| Disable the display of item numbers DNUMS. A disabled display |
| item is not printed automatically, but is not forgotten. It may be |
| enabled again later. |
| |
| `enable display DNUMS...' |
| Enable display of item numbers DNUMS. It becomes effective once |
| again in auto display of its expression, until you specify |
| otherwise. |
| |
| `display' |
| Display the current values of the expressions on the list, just as |
| is done when your program stops. |
| |
| `info display' |
| Print the list of expressions previously set up to display |
| automatically, each one with its item number, but without showing |
| the values. This includes disabled expressions, which are marked |
| as such. It also includes expressions which would not be |
| displayed right now because they refer to automatic variables not |
| currently available. |
| |
| If a display expression refers to local variables, then it does not |
| make sense outside the lexical context for which it was set up. Such an |
| expression is disabled when execution enters a context where one of its |
| variables is not defined. For example, if you give the command |
| `display last_char' while inside a function with an argument |
| `last_char', GDB displays this argument while your program continues to |
| stop inside that function. When it stops elsewhere--where there is no |
| variable `last_char'--the display is disabled automatically. The next |
| time your program stops where `last_char' is meaningful, you can enable |
| the display expression once again. |
| |
| |
| File: gdb.info, Node: Print Settings, Next: Value History, Prev: Auto Display, Up: Data |
| |
| 8.7 Print Settings |
| ================== |
| |
| GDB provides the following ways to control how arrays, structures, and |
| symbols are printed. |
| |
| These settings are useful for debugging programs in any language: |
| |
| `set print address' |
| `set print address on' |
| GDB prints memory addresses showing the location of stack traces, |
| structure values, pointer values, breakpoints, and so forth, even |
| when it also displays the contents of those addresses. The default |
| is `on'. For example, this is what a stack frame display looks |
| like with `set print address on': |
| |
| (gdb) f |
| #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") |
| at input.c:530 |
| 530 if (lquote != def_lquote) |
| |
| `set print address off' |
| Do not print addresses when displaying their contents. For |
| example, this is the same stack frame displayed with `set print |
| address off': |
| |
| (gdb) set print addr off |
| (gdb) f |
| #0 set_quotes (lq="<<", rq=">>") at input.c:530 |
| 530 if (lquote != def_lquote) |
| |
| You can use `set print address off' to eliminate all machine |
| dependent displays from the GDB interface. For example, with |
| `print address off', you should get the same text for backtraces on |
| all machines--whether or not they involve pointer arguments. |
| |
| `show print address' |
| Show whether or not addresses are to be printed. |
| |
| When GDB prints a symbolic address, it normally prints the closest |
| earlier symbol plus an offset. If that symbol does not uniquely |
| identify the address (for example, it is a name whose scope is a single |
| source file), you may need to clarify. One way to do this is with |
| `info line', for example `info line *0x4537'. Alternately, you can set |
| GDB to print the source file and line number when it prints a symbolic |
| address: |
| |
| `set print symbol-filename on' |
| Tell GDB to print the source file name and line number of a symbol |
| in the symbolic form of an address. |
| |
| `set print symbol-filename off' |
| Do not print source file name and line number of a symbol. This |
| is the default. |
| |
| `show print symbol-filename' |
| Show whether or not GDB will print the source file name and line |
| number of a symbol in the symbolic form of an address. |
| |
| Another situation where it is helpful to show symbol filenames and |
| line numbers is when disassembling code; GDB shows you the line number |
| and source file that corresponds to each instruction. |
| |
| Also, you may wish to see the symbolic form only if the address being |
| printed is reasonably close to the closest earlier symbol: |
| |
| `set print max-symbolic-offset MAX-OFFSET' |
| Tell GDB to only display the symbolic form of an address if the |
| offset between the closest earlier symbol and the address is less |
| than MAX-OFFSET. The default is 0, which tells GDB to always |
| print the symbolic form of an address if any symbol precedes it. |
| |
| `show print max-symbolic-offset' |
| Ask how large the maximum offset is that GDB prints in a symbolic |
| address. |
| |
| If you have a pointer and you are not sure where it points, try `set |
| print symbol-filename on'. Then you can determine the name and source |
| file location of the variable where it points, using `p/a POINTER'. |
| This interprets the address in symbolic form. For example, here GDB |
| shows that a variable `ptt' points at another variable `t', defined in |
| `hi2.c': |
| |
| (gdb) set print symbol-filename on |
| (gdb) p/a ptt |
| $4 = 0xe008 <t in hi2.c> |
| |
| _Warning:_ For pointers that point to a local variable, `p/a' does |
| not show the symbol name and filename of the referent, even with |
| the appropriate `set print' options turned on. |
| |
| Other settings control how different kinds of objects are printed: |
| |
| `set print array' |
| `set print array on' |
| Pretty print arrays. This format is more convenient to read, but |
| uses more space. The default is off. |
| |
| `set print array off' |
| Return to compressed format for arrays. |
| |
| `show print array' |
| Show whether compressed or pretty format is selected for displaying |
| arrays. |
| |
| `set print array-indexes' |
| `set print array-indexes on' |
| Print the index of each element when displaying arrays. May be |
| more convenient to locate a given element in the array or quickly |
| find the index of a given element in that printed array. The |
| default is off. |
| |
| `set print array-indexes off' |
| Stop printing element indexes when displaying arrays. |
| |
| `show print array-indexes' |
| Show whether the index of each element is printed when displaying |
| arrays. |
| |
| `set print elements NUMBER-OF-ELEMENTS' |
| Set a limit on how many elements of an array GDB will print. If |
| GDB is printing a large array, it stops printing after it has |
| printed the number of elements set by the `set print elements' |
| command. This limit also applies to the display of strings. When |
| GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS |
| to zero means that the printing is unlimited. |
| |
| `show print elements' |
| Display the number of elements of a large array that GDB will |
| print. If the number is 0, then the printing is unlimited. |
| |
| `set print frame-arguments VALUE' |
| This command allows to control how the values of arguments are |
| printed when the debugger prints a frame (*note Frames::). The |
| possible values are: |
| |
| `all' |
| The values of all arguments are printed. This is the default. |
| |
| `scalars' |
| Print the value of an argument only if it is a scalar. The |
| value of more complex arguments such as arrays, structures, |
| unions, etc, is replaced by `...'. Here is an example where |
| only scalar arguments are shown: |
| |
| #1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green) |
| at frame-args.c:23 |
| |
| `none' |
| None of the argument values are printed. Instead, the value |
| of each argument is replaced by `...'. In this case, the |
| example above now becomes: |
| |
| #1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...) |
| at frame-args.c:23 |
| |
| By default, all argument values are always printed. But this |
| command can be useful in several cases. For instance, it can be |
| used to reduce the amount of information printed in each frame, |
| making the backtrace more readable. Also, this command can be |
| used to improve performance when displaying Ada frames, because |
| the computation of large arguments can sometimes be CPU-intensive, |
| especiallly in large applications. Setting `print |
| frame-arguments' to `scalars' or `none' avoids this computation, |
| thus speeding up the display of each Ada frame. |
| |
| `show print frame-arguments' |
| Show how the value of arguments should be displayed when printing |
| a frame. |
| |
| `set print repeats' |
| Set the threshold for suppressing display of repeated array |
| elements. When the number of consecutive identical elements of an |
| array exceeds the threshold, GDB prints the string `"<repeats N |
| times>"', where N is the number of identical repetitions, instead |
| of displaying the identical elements themselves. Setting the |
| threshold to zero will cause all elements to be individually |
| printed. The default threshold is 10. |
| |
| `show print repeats' |
| Display the current threshold for printing repeated identical |
| elements. |
| |
| `set print null-stop' |
| Cause GDB to stop printing the characters of an array when the |
| first NULL is encountered. This is useful when large arrays |
| actually contain only short strings. The default is off. |
| |
| `show print null-stop' |
| Show whether GDB stops printing an array on the first NULL |
| character. |
| |
| `set print pretty on' |
| Cause GDB to print structures in an indented format with one member |
| per line, like this: |
| |
| $1 = { |
| next = 0x0, |
| flags = { |
| sweet = 1, |
| sour = 1 |
| }, |
| meat = 0x54 "Pork" |
| } |
| |
| `set print pretty off' |
| Cause GDB to print structures in a compact format, like this: |
| |
| $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \ |
| meat = 0x54 "Pork"} |
| |
| This is the default format. |
| |
| `show print pretty' |
| Show which format GDB is using to print structures. |
| |
| `set print sevenbit-strings on' |
| Print using only seven-bit characters; if this option is set, GDB |
| displays any eight-bit characters (in strings or character values) |
| using the notation `\'NNN. This setting is best if you are |
| working in English (ASCII) and you use the high-order bit of |
| characters as a marker or "meta" bit. |
| |
| `set print sevenbit-strings off' |
| Print full eight-bit characters. This allows the use of more |
| international character sets, and is the default. |
| |
| `show print sevenbit-strings' |
| Show whether or not GDB is printing only seven-bit characters. |
| |
| `set print union on' |
| Tell GDB to print unions which are contained in structures and |
| other unions. This is the default setting. |
| |
| `set print union off' |
| Tell GDB not to print unions which are contained in structures and |
| other unions. GDB will print `"{...}"' instead. |
| |
| `show print union' |
| Ask GDB whether or not it will print unions which are contained in |
| structures and other unions. |
| |
| For example, given the declarations |
| |
| typedef enum {Tree, Bug} Species; |
| typedef enum {Big_tree, Acorn, Seedling} Tree_forms; |
| typedef enum {Caterpillar, Cocoon, Butterfly} |
| Bug_forms; |
| |
| struct thing { |
| Species it; |
| union { |
| Tree_forms tree; |
| Bug_forms bug; |
| } form; |
| }; |
| |
| struct thing foo = {Tree, {Acorn}}; |
| |
| with `set print union on' in effect `p foo' would print |
| |
| $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}} |
| |
| and with `set print union off' in effect it would print |
| |
| $1 = {it = Tree, form = {...}} |
| |
| `set print union' affects programs written in C-like languages and |
| in Pascal. |
| |
| These settings are of interest when debugging C++ programs: |
| |
| `set print demangle' |
| `set print demangle on' |
| Print C++ names in their source form rather than in the encoded |
| ("mangled") form passed to the assembler and linker for type-safe |
| linkage. The default is on. |
| |
| `show print demangle' |
| Show whether C++ names are printed in mangled or demangled form. |
| |
| `set print asm-demangle' |
| `set print asm-demangle on' |
| Print C++ names in their source form rather than their mangled |
| form, even in assembler code printouts such as instruction |
| disassemblies. The default is off. |
| |
| `show print asm-demangle' |
| Show whether C++ names in assembly listings are printed in mangled |
| or demangled form. |
| |
| `set demangle-style STYLE' |
| Choose among several encoding schemes used by different compilers |
| to represent C++ names. The choices for STYLE are currently: |
| |
| `auto' |
| Allow GDB to choose a decoding style by inspecting your |
| program. |
| |
| `gnu' |
| Decode based on the GNU C++ compiler (`g++') encoding |
| algorithm. This is the default. |
| |
| `hp' |
| Decode based on the HP ANSI C++ (`aCC') encoding algorithm. |
| |
| `lucid' |
| Decode based on the Lucid C++ compiler (`lcc') encoding |
| algorithm. |
| |
| `arm' |
| Decode using the algorithm in the `C++ Annotated Reference |
| Manual'. *Warning:* this setting alone is not sufficient to |
| allow debugging `cfront'-generated executables. GDB would |
| require further enhancement to permit that. |
| |
| If you omit STYLE, you will see a list of possible formats. |
| |
| `show demangle-style' |
| Display the encoding style currently in use for decoding C++ |
| symbols. |
| |
| `set print object' |
| `set print object on' |
| When displaying a pointer to an object, identify the _actual_ |
| (derived) type of the object rather than the _declared_ type, using |
| the virtual function table. |
| |
| `set print object off' |
| Display only the declared type of objects, without reference to the |
| virtual function table. This is the default setting. |
| |
| `show print object' |
| Show whether actual, or declared, object types are displayed. |
| |
| `set print static-members' |
| `set print static-members on' |
| Print static members when displaying a C++ object. The default is |
| on. |
| |
| `set print static-members off' |
| Do not print static members when displaying a C++ object. |
| |
| `show print static-members' |
| Show whether C++ static members are printed or not. |
| |
| `set print pascal_static-members' |
| `set print pascal_static-members on' |
| Print static members when displaying a Pascal object. The default |
| is on. |
| |
| `set print pascal_static-members off' |
| Do not print static members when displaying a Pascal object. |
| |
| `show print pascal_static-members' |
| Show whether Pascal static members are printed or not. |
| |
| `set print vtbl' |
| `set print vtbl on' |
| Pretty print C++ virtual function tables. The default is off. |
| (The `vtbl' commands do not work on programs compiled with the HP |
| ANSI C++ compiler (`aCC').) |
| |
| `set print vtbl off' |
| Do not pretty print C++ virtual function tables. |
| |
| `show print vtbl' |
| Show whether C++ virtual function tables are pretty printed, or |
| not. |
| |
| |
| File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Print Settings, Up: Data |
| |
| 8.8 Value History |
| ================= |
| |
| Values printed by the `print' command are saved in the GDB "value |
| history". This allows you to refer to them in other expressions. |
| Values are kept until the symbol table is re-read or discarded (for |
| example with the `file' or `symbol-file' commands). When the symbol |
| table changes, the value history is discarded, since the values may |
| contain pointers back to the types defined in the symbol table. |
| |
| The values printed are given "history numbers" by which you can |
| refer to them. These are successive integers starting with one. |
| `print' shows you the history number assigned to a value by printing |
| `$NUM = ' before the value; here NUM is the history number. |
| |
| To refer to any previous value, use `$' followed by the value's |
| history number. The way `print' labels its output is designed to |
| remind you of this. Just `$' refers to the most recent value in the |
| history, and `$$' refers to the value before that. `$$N' refers to the |
| Nth value from the end; `$$2' is the value just prior to `$$', `$$1' is |
| equivalent to `$$', and `$$0' is equivalent to `$'. |
| |
| For example, suppose you have just printed a pointer to a structure |
| and want to see the contents of the structure. It suffices to type |
| |
| p *$ |
| |
| If you have a chain of structures where the component `next' points |
| to the next one, you can print the contents of the next one with this: |
| |
| p *$.next |
| |
| You can print successive links in the chain by repeating this |
| command--which you can do by just typing <RET>. |
| |
| Note that the history records values, not expressions. If the value |
| of `x' is 4 and you type these commands: |
| |
| print x |
| set x=5 |
| |
| then the value recorded in the value history by the `print' command |
| remains 4 even though the value of `x' has changed. |
| |
| `show values' |
| Print the last ten values in the value history, with their item |
| numbers. This is like `p $$9' repeated ten times, except that |
| `show values' does not change the history. |
| |
| `show values N' |
| Print ten history values centered on history item number N. |
| |
| `show values +' |
| Print ten history values just after the values last printed. If |
| no more values are available, `show values +' produces no display. |
| |
| Pressing <RET> to repeat `show values N' has exactly the same effect |
| as `show values +'. |
| |
| |
| File: gdb.info, Node: Convenience Vars, Next: Registers, Prev: Value History, Up: Data |
| |
| 8.9 Convenience Variables |
| ========================= |
| |
| GDB provides "convenience variables" that you can use within GDB to |
| hold on to a value and refer to it later. These variables exist |
| entirely within GDB; they are not part of your program, and setting a |
| convenience variable has no direct effect on further execution of your |
| program. That is why you can use them freely. |
| |
| Convenience variables are prefixed with `$'. Any name preceded by |
| `$' can be used for a convenience variable, unless it is one of the |
| predefined machine-specific register names (*note Registers: |
| Registers.). (Value history references, in contrast, are _numbers_ |
| preceded by `$'. *Note Value History: Value History.) |
| |
| You can save a value in a convenience variable with an assignment |
| expression, just as you would set a variable in your program. For |
| example: |
| |
| set $foo = *object_ptr |
| |
| would save in `$foo' the value contained in the object pointed to by |
| `object_ptr'. |
| |
| Using a convenience variable for the first time creates it, but its |
| value is `void' until you assign a new value. You can alter the value |
| with another assignment at any time. |
| |
| Convenience variables have no fixed types. You can assign a |
| convenience variable any type of value, including structures and |
| arrays, even if that variable already has a value of a different type. |
| The convenience variable, when used as an expression, has the type of |
| its current value. |
| |
| `show convenience' |
| Print a list of convenience variables used so far, and their |
| values. Abbreviated `show conv'. |
| |
| `init-if-undefined $VARIABLE = EXPRESSION' |
| Set a convenience variable if it has not already been set. This |
| is useful for user-defined commands that keep some state. It is |
| similar, in concept, to using local static variables with |
| initializers in C (except that convenience variables are global). |
| It can also be used to allow users to override default values used |
| in a command script. |
| |
| If the variable is already defined then the expression is not |
| evaluated so any side-effects do not occur. |
| |
| One of the ways to use a convenience variable is as a counter to be |
| incremented or a pointer to be advanced. For example, to print a field |
| from successive elements of an array of structures: |
| |
| set $i = 0 |
| print bar[$i++]->contents |
| |
| Repeat that command by typing <RET>. |
| |
| Some convenience variables are created automatically by GDB and given |
| values likely to be useful. |
| |
| `$_' |
| The variable `$_' is automatically set by the `x' command to the |
| last address examined (*note Examining Memory: Memory.). Other |
| commands which provide a default address for `x' to examine also |
| set `$_' to that address; these commands include `info line' and |
| `info breakpoint'. The type of `$_' is `void *' except when set |
| by the `x' command, in which case it is a pointer to the type of |
| `$__'. |
| |
| `$__' |
| The variable `$__' is automatically set by the `x' command to the |
| value found in the last address examined. Its type is chosen to |
| match the format in which the data was printed. |
| |
| `$_exitcode' |
| The variable `$_exitcode' is automatically set to the exit code |
| when the program being debugged terminates. |
| |
| On HP-UX systems, if you refer to a function or variable name that |
| begins with a dollar sign, GDB searches for a user or system name |
| first, before it searches for a convenience variable. |
| |
| |
| File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Vars, Up: Data |
| |
| 8.10 Registers |
| ============== |
| |
| You can refer to machine register contents, in expressions, as variables |
| with names starting with `$'. The names of registers are different for |
| each machine; use `info registers' to see the names used on your |
| machine. |
| |
| `info registers' |
| Print the names and values of all registers except floating-point |
| and vector registers (in the selected stack frame). |
| |
| `info all-registers' |
| Print the names and values of all registers, including |
| floating-point and vector registers (in the selected stack frame). |
| |
| `info registers REGNAME ...' |
| Print the "relativized" value of each specified register REGNAME. |
| As discussed in detail below, register values are normally |
| relative to the selected stack frame. REGNAME may be any register |
| name valid on the machine you are using, with or without the |
| initial `$'. |
| |
| GDB has four "standard" register names that are available (in |
| expressions) on most machines--whenever they do not conflict with an |
| architecture's canonical mnemonics for registers. The register names |
| `$pc' and `$sp' are used for the program counter register and the stack |
| pointer. `$fp' is used for a register that contains a pointer to the |
| current stack frame, and `$ps' is used for a register that contains the |
| processor status. For example, you could print the program counter in |
| hex with |
| |
| p/x $pc |
| |
| or print the instruction to be executed next with |
| |
| x/i $pc |
| |
| or add four to the stack pointer(1) with |
| |
| set $sp += 4 |
| |
| Whenever possible, these four standard register names are available |
| on your machine even though the machine has different canonical |
| mnemonics, so long as there is no conflict. The `info registers' |
| command shows the canonical names. For example, on the SPARC, `info |
| registers' displays the processor status register as `$psr' but you can |
| also refer to it as `$ps'; and on x86-based machines `$ps' is an alias |
| for the EFLAGS register. |
| |
| GDB always considers the contents of an ordinary register as an |
| integer when the register is examined in this way. Some machines have |
| special registers which can hold nothing but floating point; these |
| registers are considered to have floating point values. There is no way |
| to refer to the contents of an ordinary register as floating point value |
| (although you can _print_ it as a floating point value with `print/f |
| $REGNAME'). |
| |
| Some registers have distinct "raw" and "virtual" data formats. This |
| means that the data format in which the register contents are saved by |
| the operating system is not the same one that your program normally |
| sees. For example, the registers of the 68881 floating point |
| coprocessor are always saved in "extended" (raw) format, but all C |
| programs expect to work with "double" (virtual) format. In such cases, |
| GDB normally works with the virtual format only (the format that makes |
| sense for your program), but the `info registers' command prints the |
| data in both formats. |
| |
| Some machines have special registers whose contents can be |
| interpreted in several different ways. For example, modern x86-based |
| machines have SSE and MMX registers that can hold several values packed |
| together in several different formats. GDB refers to such registers in |
| `struct' notation: |
| |
| (gdb) print $xmm1 |
| $1 = { |
| v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044}, |
| v2_double = {9.92129282474342e-303, 2.7585945287983262e-313}, |
| v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", |
| v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0}, |
| v4_int32 = {0, 20657912, 11, 13}, |
| v2_int64 = {88725056443645952, 55834574859}, |
| uint128 = 0x0000000d0000000b013b36f800000000 |
| } |
| |
| To set values of such registers, you need to tell GDB which view of the |
| register you wish to change, as if you were assigning value to a |
| `struct' member: |
| |
| (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF |
| |
| Normally, register values are relative to the selected stack frame |
| (*note Selecting a Frame: Selection.). This means that you get the |
| value that the register would contain if all stack frames farther in |
| were exited and their saved registers restored. In order to see the |
| true contents of hardware registers, you must select the innermost |
| frame (with `frame 0'). |
| |
| However, GDB must deduce where registers are saved, from the machine |
| code generated by your compiler. If some registers are not saved, or if |
| GDB is unable to locate the saved registers, the selected stack frame |
| makes no difference. |
| |
| ---------- Footnotes ---------- |
| |
| (1) This is a way of removing one word from the stack, on machines |
| where stacks grow downward in memory (most machines, nowadays). This |
| assumes that the innermost stack frame is selected; setting `$sp' is |
| not allowed when other stack frames are selected. To pop entire frames |
| off the stack, regardless of machine architecture, use `return'; see |
| *note Returning from a Function: Returning. |
| |
| |
| File: gdb.info, Node: Floating Point Hardware, Next: Vector Unit, Prev: Registers, Up: Data |
| |
| 8.11 Floating Point Hardware |
| ============================ |
| |
| Depending on the configuration, GDB may be able to give you more |
| information about the status of the floating point hardware. |
| |
| `info float' |
| Display hardware-dependent information about the floating point |
| unit. The exact contents and layout vary depending on the |
| floating point chip. Currently, `info float' is supported on the |
| ARM and x86 machines. |
| |
| |
| File: gdb.info, Node: Vector Unit, Next: OS Information, Prev: Floating Point Hardware, Up: Data |
| |
| 8.12 Vector Unit |
| ================ |
| |
| Depending on the configuration, GDB may be able to give you more |
| information about the status of the vector unit. |
| |
| `info vector' |
| Display information about the vector unit. The exact contents and |
| layout vary depending on the hardware. |
| |
| |
| File: gdb.info, Node: OS Information, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data |
| |
| 8.13 Operating System Auxiliary Information |
| =========================================== |
| |
| GDB provides interfaces to useful OS facilities that can help you debug |
| your program. |
| |
| When GDB runs on a "Posix system" (such as GNU or Unix machines), it |
| interfaces with the inferior via the `ptrace' system call. The |
| operating system creates a special sata structure, called `struct |
| user', for this interface. You can use the command `info udot' to |
| display the contents of this data structure. |
| |
| `info udot' |
| Display the contents of the `struct user' maintained by the OS |
| kernel for the program being debugged. GDB displays the contents |
| of `struct user' as a list of hex numbers, similar to the |
| `examine' command. |
| |
| Some operating systems supply an "auxiliary vector" to programs at |
| startup. This is akin to the arguments and environment that you |
| specify for a program, but contains a system-dependent variety of |
| binary values that tell system libraries important details about the |
| hardware, operating system, and process. Each value's purpose is |
| identified by an integer tag; the meanings are well-known but |
| system-specific. Depending on the configuration and operating system |
| facilities, GDB may be able to show you this information. For remote |
| targets, this functionality may further depend on the remote stub's |
| support of the `qXfer:auxv:read' packet, see *note qXfer auxiliary |
| vector read::. |
| |
| `info auxv' |
| Display the auxiliary vector of the inferior, which can be either a |
| live process or a core dump file. GDB prints each tag value |
| numerically, and also shows names and text descriptions for |
| recognized tags. Some values in the vector are numbers, some bit |
| masks, and some pointers to strings or other data. GDB displays |
| each value in the most appropriate form for a recognized tag, and |
| in hexadecimal for an unrecognized tag. |
| |
| |
| File: gdb.info, Node: Memory Region Attributes, Next: Dump/Restore Files, Prev: OS Information, Up: Data |
| |
| 8.14 Memory Region Attributes |
| ============================= |
| |
| "Memory region attributes" allow you to describe special handling |
| required by regions of your target's memory. GDB uses attributes to |
| determine whether to allow certain types of memory accesses; whether to |
| use specific width accesses; and whether to cache target memory. By |
| default the description of memory regions is fetched from the target |
| (if the current target supports this), but the user can override the |
| fetched regions. |
| |
| Defined memory regions can be individually enabled and disabled. |
| When a memory region is disabled, GDB uses the default attributes when |
| accessing memory in that region. Similarly, if no memory regions have |
| been defined, GDB uses the default attributes when accessing all memory. |
| |
| When a memory region is defined, it is given a number to identify it; |
| to enable, disable, or remove a memory region, you specify that number. |
| |
| `mem LOWER UPPER ATTRIBUTES...' |
| Define a memory region bounded by LOWER and UPPER with attributes |
| ATTRIBUTES..., and add it to the list of regions monitored by GDB. |
| Note that UPPER == 0 is a special case: it is treated as the |
| target's maximum memory address. (0xffff on 16 bit targets, |
| 0xffffffff on 32 bit targets, etc.) |
| |
| `mem auto' |
| Discard any user changes to the memory regions and use |
| target-supplied regions, if available, or no regions if the target |
| does not support. |
| |
| `delete mem NUMS...' |
| Remove memory regions NUMS... from the list of regions monitored |
| by GDB. |
| |
| `disable mem NUMS...' |
| Disable monitoring of memory regions NUMS.... A disabled memory |
| region is not forgotten. It may be enabled again later. |
| |
| `enable mem NUMS...' |
| Enable monitoring of memory regions NUMS.... |
| |
| `info mem' |
| Print a table of all defined memory regions, with the following |
| columns for each region: |
| |
| _Memory Region Number_ |
| |
| _Enabled or Disabled._ |
| Enabled memory regions are marked with `y'. Disabled memory |
| regions are marked with `n'. |
| |
| _Lo Address_ |
| The address defining the inclusive lower bound of the memory |
| region. |
| |
| _Hi Address_ |
| The address defining the exclusive upper bound of the memory |
| region. |
| |
| _Attributes_ |
| The list of attributes set for this memory region. |
| |
| 8.14.1 Attributes |
| ----------------- |
| |
| 8.14.1.1 Memory Access Mode |
| ........................... |
| |
| The access mode attributes set whether GDB may make read or write |
| accesses to a memory region. |
| |
| While these attributes prevent GDB from performing invalid memory |
| accesses, they do nothing to prevent the target system, I/O DMA, etc. |
| from accessing memory. |
| |
| `ro' |
| Memory is read only. |
| |
| `wo' |
| Memory is write only. |
| |
| `rw' |
| Memory is read/write. This is the default. |
| |
| 8.14.1.2 Memory Access Size |
| ........................... |
| |
| The access size attribute tells GDB to use specific sized accesses in |
| the memory region. Often memory mapped device registers require |
| specific sized accesses. If no access size attribute is specified, GDB |
| may use accesses of any size. |
| |
| `8' |
| Use 8 bit memory accesses. |
| |
| `16' |
| Use 16 bit memory accesses. |
| |
| `32' |
| Use 32 bit memory accesses. |
| |
| `64' |
| Use 64 bit memory accesses. |
| |
| 8.14.1.3 Data Cache |
| ................... |
| |
| The data cache attributes set whether GDB will cache target memory. |
| While this generally improves performance by reducing debug protocol |
| overhead, it can lead to incorrect results because GDB does not know |
| about volatile variables or memory mapped device registers. |
| |
| `cache' |
| Enable GDB to cache target memory. |
| |
| `nocache' |
| Disable GDB from caching target memory. This is the default. |
| |
| 8.14.2 Memory Access Checking |
| ----------------------------- |
| |
| GDB can be instructed to refuse accesses to memory that is not |
| explicitly described. This can be useful if accessing such regions has |
| undesired effects for a specific target, or to provide better error |
| checking. The following commands control this behaviour. |
| |
| `set mem inaccessible-by-default [on|off]' |
| If `on' is specified, make GDB treat memory not explicitly |
| described by the memory ranges as non-existent and refuse accesses |
| to such memory. The checks are only performed if there's at least |
| one memory range defined. If `off' is specified, make GDB treat |
| the memory not explicitly described by the memory ranges as RAM. |
| The default value is `on'. |
| |
| `show mem inaccessible-by-default' |
| Show the current handling of accesses to unknown memory. |
| |
| |
| File: gdb.info, Node: Dump/Restore Files, Next: Core File Generation, Prev: Memory Region Attributes, Up: Data |
| |
| 8.15 Copy Between Memory and a File |
| =================================== |
| |
| You can use the commands `dump', `append', and `restore' to copy data |
| between target memory and a file. The `dump' and `append' commands |
| write data to a file, and the `restore' command reads data from a file |
| back into the inferior's memory. Files may be in binary, Motorola |
| S-record, Intel hex, or Tektronix Hex format; however, GDB can only |
| append to binary files. |
| |
| `dump [FORMAT] memory FILENAME START_ADDR END_ADDR' |
| `dump [FORMAT] value FILENAME EXPR' |
| Dump the contents of memory from START_ADDR to END_ADDR, or the |
| value of EXPR, to FILENAME in the given format. |
| |
| The FORMAT parameter may be any one of: |
| `binary' |
| Raw binary form. |
| |
| `ihex' |
| Intel hex format. |
| |
| `srec' |
| Motorola S-record format. |
| |
| `tekhex' |
| Tektronix Hex format. |
| |
| GDB uses the same definitions of these formats as the GNU binary |
| utilities, like `objdump' and `objcopy'. If FORMAT is omitted, |
| GDB dumps the data in raw binary form. |
| |
| `append [binary] memory FILENAME START_ADDR END_ADDR' |
| `append [binary] value FILENAME EXPR' |
| Append the contents of memory from START_ADDR to END_ADDR, or the |
| value of EXPR, to the file FILENAME, in raw binary form. (GDB can |
| only append data to files in raw binary form.) |
| |
| `restore FILENAME [binary] BIAS START END' |
| Restore the contents of file FILENAME into memory. The `restore' |
| command can automatically recognize any known BFD file format, |
| except for raw binary. To restore a raw binary file you must |
| specify the optional keyword `binary' after the filename. |
| |
| If BIAS is non-zero, its value will be added to the addresses |
| contained in the file. Binary files always start at address zero, |
| so they will be restored at address BIAS. Other bfd files have a |
| built-in location; they will be restored at offset BIAS from that |
| location. |
| |
| If START and/or END are non-zero, then only data between file |
| offset START and file offset END will be restored. These offsets |
| are relative to the addresses in the file, before the BIAS |
| argument is applied. |
| |
| |
| |
| File: gdb.info, Node: Core File Generation, Next: Character Sets, Prev: Dump/Restore Files, Up: Data |
| |
| 8.16 How to Produce a Core File from Your Program |
| ================================================= |
| |
| A "core file" or "core dump" is a file that records the memory image of |
| a running process and its process status (register values etc.). Its |
| primary use is post-mortem debugging of a program that crashed while it |
| ran outside a debugger. A program that crashes automatically produces |
| a core file, unless this feature is disabled by the user. *Note |
| Files::, for information on invoking GDB in the post-mortem debugging |
| mode. |
| |
| Occasionally, you may wish to produce a core file of the program you |
| are debugging in order to preserve a snapshot of its state. GDB has a |
| special command for that. |
| |
| `generate-core-file [FILE]' |
| `gcore [FILE]' |
| Produce a core dump of the inferior process. The optional argument |
| FILE specifies the file name where to put the core dump. If not |
| specified, the file name defaults to `core.PID', where PID is the |
| inferior process ID. |
| |
| Note that this command is implemented only for some systems (as of |
| this writing, GNU/Linux, FreeBSD, Solaris, Unixware, and S390). |
| |
| |
| File: gdb.info, Node: Character Sets, Next: Caching Remote Data, Prev: Core File Generation, Up: Data |
| |
| 8.17 Character Sets |
| =================== |
| |
| If the program you are debugging uses a different character set to |
| represent characters and strings than the one GDB uses itself, GDB can |
| automatically translate between the character sets for you. The |
| character set GDB uses we call the "host character set"; the one the |
| inferior program uses we call the "target character set". |
| |
| For example, if you are running GDB on a GNU/Linux system, which |
| uses the ISO Latin 1 character set, but you are using GDB's remote |
| protocol (*note Remote Debugging::) to debug a program running on an |
| IBM mainframe, which uses the EBCDIC character set, then the host |
| character set is Latin-1, and the target character set is EBCDIC. If |
| you give GDB the command `set target-charset EBCDIC-US', then GDB |
| translates between EBCDIC and Latin 1 as you print character or string |
| values, or use character and string literals in expressions. |
| |
| GDB has no way to automatically recognize which character set the |
| inferior program uses; you must tell it, using the `set target-charset' |
| command, described below. |
| |
| Here are the commands for controlling GDB's character set support: |
| |
| `set target-charset CHARSET' |
| Set the current target character set to CHARSET. We list the |
| character set names GDB recognizes below, but if you type `set |
| target-charset' followed by <TAB><TAB>, GDB will list the target |
| character sets it supports. |
| |
| `set host-charset CHARSET' |
| Set the current host character set to CHARSET. |
| |
| By default, GDB uses a host character set appropriate to the |
| system it is running on; you can override that default using the |
| `set host-charset' command. |
| |
| GDB can only use certain character sets as its host character set. |
| We list the character set names GDB recognizes below, and indicate |
| which can be host character sets, but if you type `set |
| target-charset' followed by <TAB><TAB>, GDB will list the host |
| character sets it supports. |
| |
| `set charset CHARSET' |
| Set the current host and target character sets to CHARSET. As |
| above, if you type `set charset' followed by <TAB><TAB>, GDB will |
| list the name of the character sets that can be used for both host |
| and target. |
| |
| `show charset' |
| Show the names of the current host and target charsets. |
| |
| `show host-charset' |
| Show the name of the current host charset. |
| |
| `show target-charset' |
| Show the name of the current target charset. |
| |
| |
| GDB currently includes support for the following character sets: |
| |
| `ASCII' |
| Seven-bit U.S. ASCII. GDB can use this as its host character set. |
| |
| `ISO-8859-1' |
| The ISO Latin 1 character set. This extends ASCII with accented |
| characters needed for French, German, and Spanish. GDB can use |
| this as its host character set. |
| |
| `EBCDIC-US' |
| `IBM1047' |
| Variants of the EBCDIC character set, used on some of IBM's |
| mainframe operating systems. (GNU/Linux on the S/390 uses U.S. |
| ASCII.) GDB cannot use these as its host character set. |
| |
| |
| Note that these are all single-byte character sets. More work inside |
| GDB is needed to support multi-byte or variable-width character |
| encodings, like the UTF-8 and UCS-2 encodings of Unicode. |
| |
| Here is an example of GDB's character set support in action. Assume |
| that the following source code has been placed in the file |
| `charset-test.c': |
| |
| #include <stdio.h> |
| |
| char ascii_hello[] |
| = {72, 101, 108, 108, 111, 44, 32, 119, |
| 111, 114, 108, 100, 33, 10, 0}; |
| char ibm1047_hello[] |
| = {200, 133, 147, 147, 150, 107, 64, 166, |
| 150, 153, 147, 132, 90, 37, 0}; |
| |
| main () |
| { |
| printf ("Hello, world!\n"); |
| } |
| |
| In this program, `ascii_hello' and `ibm1047_hello' are arrays |
| containing the string `Hello, world!' followed by a newline, encoded in |
| the ASCII and IBM1047 character sets. |
| |
| We compile the program, and invoke the debugger on it: |
| |
| $ gcc -g charset-test.c -o charset-test |
| $ gdb -nw charset-test |
| GNU gdb 2001-12-19-cvs |
| Copyright 2001 Free Software Foundation, Inc. |
| ... |
| (gdb) |
| |
| We can use the `show charset' command to see what character sets GDB |
| is currently using to interpret and display characters and strings: |
| |
| (gdb) show charset |
| The current host and target character set is `ISO-8859-1'. |
| (gdb) |
| |
| For the sake of printing this manual, let's use ASCII as our initial |
| character set: |
| (gdb) set charset ASCII |
| (gdb) show charset |
| The current host and target character set is `ASCII'. |
| (gdb) |
| |
| Let's assume that ASCII is indeed the correct character set for our |
| host system -- in other words, let's assume that if GDB prints |
| characters using the ASCII character set, our terminal will display |
| them properly. Since our current target character set is also ASCII, |
| the contents of `ascii_hello' print legibly: |
| |
| (gdb) print ascii_hello |
| $1 = 0x401698 "Hello, world!\n" |
| (gdb) print ascii_hello[0] |
| $2 = 72 'H' |
| (gdb) |
| |
| GDB uses the target character set for character and string literals |
| you use in expressions: |
| |
| (gdb) print '+' |
| $3 = 43 '+' |
| (gdb) |
| |
| The ASCII character set uses the number 43 to encode the `+' |
| character. |
| |
| GDB relies on the user to tell it which character set the target |
| program uses. If we print `ibm1047_hello' while our target character |
| set is still ASCII, we get jibberish: |
| |
| (gdb) print ibm1047_hello |
| $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%" |
| (gdb) print ibm1047_hello[0] |
| $5 = 200 '\310' |
| (gdb) |
| |
| If we invoke the `set target-charset' followed by <TAB><TAB>, GDB |
| tells us the character sets it supports: |
| |
| (gdb) set target-charset |
| ASCII EBCDIC-US IBM1047 ISO-8859-1 |
| (gdb) set target-charset |
| |
| We can select IBM1047 as our target character set, and examine the |
| program's strings again. Now the ASCII string is wrong, but GDB |
| translates the contents of `ibm1047_hello' from the target character |
| set, IBM1047, to the host character set, ASCII, and they display |
| correctly: |
| |
| (gdb) set target-charset IBM1047 |
| (gdb) show charset |
| The current host character set is `ASCII'. |
| The current target character set is `IBM1047'. |
| (gdb) print ascii_hello |
| $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" |
| (gdb) print ascii_hello[0] |
| $7 = 72 '\110' |
| (gdb) print ibm1047_hello |
| $8 = 0x4016a8 "Hello, world!\n" |
| (gdb) print ibm1047_hello[0] |
| $9 = 200 'H' |
| (gdb) |
| |
| As above, GDB uses the target character set for character and string |
| literals you use in expressions: |
| |
| (gdb) print '+' |
| $10 = 78 '+' |
| (gdb) |
| |
| The IBM1047 character set uses the number 78 to encode the `+' |
| character. |
| |
| |
| File: gdb.info, Node: Caching Remote Data, Prev: Character Sets, Up: Data |
| |
| 8.18 Caching Data of Remote Targets |
| =================================== |
| |
| GDB can cache data exchanged between the debugger and a remote target |
| (*note Remote Debugging::). Such caching generally improves |
| performance, because it reduces the overhead of the remote protocol by |
| bundling memory reads and writes into large chunks. Unfortunately, GDB |
| does not currently know anything about volatile registers, and thus |
| data caching will produce incorrect results when volatile registers are |
| in use. |
| |
| `set remotecache on' |
| `set remotecache off' |
| Set caching state for remote targets. When `ON', use data |
| caching. By default, this option is `OFF'. |
| |
| `show remotecache' |
| Show the current state of data caching for remote targets. |
| |
| `info dcache' |
| Print the information about the data cache performance. The |
| information displayed includes: the dcache width and depth; and for |
| each cache line, how many times it was referenced, and its data and |
| state (dirty, bad, ok, etc.). This command is useful for debugging |
| the data cache operation. |
| |
| |
| File: gdb.info, Node: Macros, Next: Tracepoints, Prev: Data, Up: Top |
| |
| 9 C Preprocessor Macros |
| *********************** |
| |
| Some languages, such as C and C++, provide a way to define and invoke |
| "preprocessor macros" which expand into strings of tokens. GDB can |
| evaluate expressions containing macro invocations, show the result of |
| macro expansion, and show a macro's definition, including where it was |
| defined. |
| |
| You may need to compile your program specially to provide GDB with |
| information about preprocessor macros. Most compilers do not include |
| macros in their debugging information, even when you compile with the |
| `-g' flag. *Note Compilation::. |
| |
| A program may define a macro at one point, remove that definition |
| later, and then provide a different definition after that. Thus, at |
| different points in the program, a macro may have different |
| definitions, or have no definition at all. If there is a current stack |
| frame, GDB uses the macros in scope at that frame's source code line. |
| Otherwise, GDB uses the macros in scope at the current listing location; |
| see *note List::. |
| |
| At the moment, GDB does not support the `##' token-splicing |
| operator, the `#' stringification operator, or variable-arity macros. |
| |
| Whenever GDB evaluates an expression, it always expands any macro |
| invocations present in the expression. GDB also provides the following |
| commands for working with macros explicitly. |
| |
| `macro expand EXPRESSION' |
| `macro exp EXPRESSION' |
| Show the results of expanding all preprocessor macro invocations in |
| EXPRESSION. Since GDB simply expands macros, but does not parse |
| the result, EXPRESSION need not be a valid expression; it can be |
| any string of tokens. |
| |
| `macro expand-once EXPRESSION' |
| `macro exp1 EXPRESSION' |
| (This command is not yet implemented.) Show the results of |
| expanding those preprocessor macro invocations that appear |
| explicitly in EXPRESSION. Macro invocations appearing in that |
| expansion are left unchanged. This command allows you to see the |
| effect of a particular macro more clearly, without being confused |
| by further expansions. Since GDB simply expands macros, but does |
| not parse the result, EXPRESSION need not be a valid expression; it |
| can be any string of tokens. |
| |
| `info macro MACRO' |
| Show the definition of the macro named MACRO, and describe the |
| source location where that definition was established. |
| |
| `macro define MACRO REPLACEMENT-LIST' |
| `macro define MACRO(ARGLIST) REPLACEMENT-LIST' |
| (This command is not yet implemented.) Introduce a definition for |
| a preprocessor macro named MACRO, invocations of which are replaced |
| by the tokens given in REPLACEMENT-LIST. The first form of this |
| command defines an "object-like" macro, which takes no arguments; |
| the second form defines a "function-like" macro, which takes the |
| arguments given in ARGLIST. |
| |
| A definition introduced by this command is in scope in every |
| expression evaluated in GDB, until it is removed with the `macro |
| undef' command, described below. The definition overrides all |
| definitions for MACRO present in the program being debugged, as |
| well as any previous user-supplied definition. |
| |
| `macro undef MACRO' |
| (This command is not yet implemented.) Remove any user-supplied |
| definition for the macro named MACRO. This command only affects |
| definitions provided with the `macro define' command, described |
| above; it cannot remove definitions present in the program being |
| debugged. |
| |
| `macro list' |
| (This command is not yet implemented.) List all the macros |
| defined using the `macro define' command. |
| |
| Here is a transcript showing the above commands in action. First, we |
| show our source files: |
| |
| $ cat sample.c |
| #include <stdio.h> |
| #include "sample.h" |
| |
| #define M 42 |
| #define ADD(x) (M + x) |
| |
| main () |
| { |
| #define N 28 |
| printf ("Hello, world!\n"); |
| #undef N |
| printf ("We're so creative.\n"); |
| #define N 1729 |
| printf ("Goodbye, world!\n"); |
| } |
| $ cat sample.h |
| #define Q < |
| $ |
| |
| Now, we compile the program using the GNU C compiler, GCC. We pass |
| the `-gdwarf-2' and `-g3' flags to ensure the compiler includes |
| information about preprocessor macros in the debugging information. |
| |
| $ gcc -gdwarf-2 -g3 sample.c -o sample |
| $ |
| |
| Now, we start GDB on our sample program: |
| |
| $ gdb -nw sample |
| GNU gdb 2002-05-06-cvs |
| Copyright 2002 Free Software Foundation, Inc. |
| GDB is free software, ... |
| (gdb) |
| |
| We can expand macros and examine their definitions, even when the |
| program is not running. GDB uses the current listing position to |
| decide which macro definitions are in scope: |
| |
| (gdb) list main |
| 3 |
| 4 #define M 42 |
| 5 #define ADD(x) (M + x) |
| 6 |
| 7 main () |
| 8 { |
| 9 #define N 28 |
| 10 printf ("Hello, world!\n"); |
| 11 #undef N |
| 12 printf ("We're so creative.\n"); |
| (gdb) info macro ADD |
| Defined at /home/jimb/gdb/macros/play/sample.c:5 |
| #define ADD(x) (M + x) |
| (gdb) info macro Q |
| Defined at /home/jimb/gdb/macros/play/sample.h:1 |
| included at /home/jimb/gdb/macros/play/sample.c:2 |
| #define Q < |
| (gdb) macro expand ADD(1) |
| expands to: (42 + 1) |
| (gdb) macro expand-once ADD(1) |
| expands to: once (M + 1) |
| (gdb) |
| |
| In the example above, note that `macro expand-once' expands only the |
| macro invocation explicit in the original text -- the invocation of |
| `ADD' -- but does not expand the invocation of the macro `M', which was |
| introduced by `ADD'. |
| |
| Once the program is running, GDB uses the macro definitions in force |
| at the source line of the current stack frame: |
| |
| (gdb) break main |
| Breakpoint 1 at 0x8048370: file sample.c, line 10. |
| (gdb) run |
| Starting program: /home/jimb/gdb/macros/play/sample |
| |
| Breakpoint 1, main () at sample.c:10 |
| 10 printf ("Hello, world!\n"); |
| (gdb) |
| |
| At line 10, the definition of the macro `N' at line 9 is in force: |
| |
| (gdb) info macro N |
| Defined at /home/jimb/gdb/macros/play/sample.c:9 |
| #define N 28 |
| (gdb) macro expand N Q M |
| expands to: 28 < 42 |
| (gdb) print N Q M |
| $1 = 1 |
| (gdb) |
| |
| As we step over directives that remove `N''s definition, and then |
| give it a new definition, GDB finds the definition (or lack thereof) in |
| force at each point: |
| |
| (gdb) next |
| Hello, world! |
| 12 printf ("We're so creative.\n"); |
| (gdb) info macro N |
| The symbol `N' has no definition as a C/C++ preprocessor macro |
| at /home/jimb/gdb/macros/play/sample.c:12 |
| (gdb) next |
| We're so creative. |
| 14 printf ("Goodbye, world!\n"); |
| (gdb) info macro N |
| Defined at /home/jimb/gdb/macros/play/sample.c:13 |
| #define N 1729 |
| (gdb) macro expand N Q M |
| expands to: 1729 < 42 |
| (gdb) print N Q M |
| $2 = 0 |
| (gdb) |
| |
| |
| File: gdb.info, Node: Tracepoints, Next: Overlays, Prev: Macros, Up: Top |
| |
| 10 Tracepoints |
| ************** |
| |
| In some applications, it is not feasible for the debugger to interrupt |
| the program's execution long enough for the developer to learn anything |
| helpful about its behavior. If the program's correctness depends on |
| its real-time behavior, delays introduced by a debugger might cause the |
| program to change its behavior drastically, or perhaps fail, even when |
| the code itself is correct. It is useful to be able to observe the |
| program's behavior without interrupting it. |
| |
| Using GDB's `trace' and `collect' commands, you can specify |
| locations in the program, called "tracepoints", and arbitrary |
| expressions to evaluate when those tracepoints are reached. Later, |
| using the `tfind' command, you can examine the values those expressions |
| had when the program hit the tracepoints. The expressions may also |
| denote objects in memory--structures or arrays, for example--whose |
| values GDB should record; while visiting a particular tracepoint, you |
| may inspect those objects as if they were in memory at that moment. |
| However, because GDB records these values without interacting with you, |
| it can do so quickly and unobtrusively, hopefully not disturbing the |
| program's behavior. |
| |
| The tracepoint facility is currently available only for remote |
| targets. *Note Targets::. In addition, your remote target must know |
| how to collect trace data. This functionality is implemented in the |
| remote stub; however, none of the stubs distributed with GDB support |
| tracepoints as of this writing. The format of the remote packets used |
| to implement tracepoints are described in *note Tracepoint Packets::. |
| |
| This chapter describes the tracepoint commands and features. |
| |
| * Menu: |
| |
| * Set Tracepoints:: |
| * Analyze Collected Data:: |
| * Tracepoint Variables:: |
| |
| |
| File: gdb.info, Node: Set Tracepoints, Next: Analyze Collected Data, Up: Tracepoints |
| |
| 10.1 Commands to Set Tracepoints |
| ================================ |
| |
| Before running such a "trace experiment", an arbitrary number of |
| tracepoints can be set. Like a breakpoint (*note Set Breaks::), a |
| tracepoint has a number assigned to it by GDB. Like with breakpoints, |
| tracepoint numbers are successive integers starting from one. Many of |
| the commands associated with tracepoints take the tracepoint number as |
| their argument, to identify which tracepoint to work on. |
| |
| For each tracepoint, you can specify, in advance, some arbitrary set |
| of data that you want the target to collect in the trace buffer when it |
| hits that tracepoint. The collected data can include registers, local |
| variables, or global data. Later, you can use GDB commands to examine |
| the values these data had at the time the tracepoint was hit. |
| |
| This section describes commands to set tracepoints and associated |
| conditions and actions. |
| |
| * Menu: |
| |
| * Create and Delete Tracepoints:: |
| * Enable and Disable Tracepoints:: |
| * Tracepoint Passcounts:: |
| * Tracepoint Actions:: |
| * Listing Tracepoints:: |
| * Starting and Stopping Trace Experiments:: |
| |
| |
| File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints |
| |
| 10.1.1 Create and Delete Tracepoints |
| ------------------------------------ |
| |
| `trace' |
| The `trace' command is very similar to the `break' command. Its |
| argument can be a source line, a function name, or an address in |
| the target program. *Note Set Breaks::. The `trace' command |
| defines a tracepoint, which is a point in the target program where |
| the debugger will briefly stop, collect some data, and then allow |
| the program to continue. Setting a tracepoint or changing its |
| commands doesn't take effect until the next `tstart' command; |
| thus, you cannot change the tracepoint attributes once a trace |
| experiment is running. |
| |
| Here are some examples of using the `trace' command: |
| |
| (gdb) trace foo.c:121 // a source file and line number |
| |
| (gdb) trace +2 // 2 lines forward |
| |
| (gdb) trace my_function // first source line of function |
| |
| (gdb) trace *my_function // EXACT start address of function |
| |
| (gdb) trace *0x2117c4 // an address |
| |
| You can abbreviate `trace' as `tr'. |
| |
| The convenience variable `$tpnum' records the tracepoint number of |
| the most recently set tracepoint. |
| |
| `delete tracepoint [NUM]' |
| Permanently delete one or more tracepoints. With no argument, the |
| default is to delete all tracepoints. |
| |
| Examples: |
| |
| (gdb) delete trace 1 2 3 // remove three tracepoints |
| |
| (gdb) delete trace // remove all tracepoints |
| |
| You can abbreviate this command as `del tr'. |
| |
| |
| File: gdb.info, Node: Enable and Disable Tracepoints, Next: Tracepoint Passcounts, Prev: Create and Delete Tracepoints, Up: Set Tracepoints |
| |
| 10.1.2 Enable and Disable Tracepoints |
| ------------------------------------- |
| |
| `disable tracepoint [NUM]' |
| Disable tracepoint NUM, or all tracepoints if no argument NUM is |
| given. A disabled tracepoint will have no effect during the next |
| trace experiment, but it is not forgotten. You can re-enable a |
| disabled tracepoint using the `enable tracepoint' command. |
| |
| `enable tracepoint [NUM]' |
| Enable tracepoint NUM, or all tracepoints. The enabled |
| tracepoints will become effective the next time a trace experiment |
| is run. |
| |
| |
| File: gdb.info, Node: Tracepoint Passcounts, Next: Tracepoint Actions, Prev: Enable and Disable Tracepoints, Up: Set Tracepoints |
| |
| 10.1.3 Tracepoint Passcounts |
| ---------------------------- |
| |
| `passcount [N [NUM]]' |
| Set the "passcount" of a tracepoint. The passcount is a way to |
| automatically stop a trace experiment. If a tracepoint's |
| passcount is N, then the trace experiment will be automatically |
| stopped on the N'th time that tracepoint is hit. If the |
| tracepoint number NUM is not specified, the `passcount' command |
| sets the passcount of the most recently defined tracepoint. If no |
| passcount is given, the trace experiment will run until stopped |
| explicitly by the user. |
| |
| Examples: |
| |
| (gdb) passcount 5 2 // Stop on the 5th execution of |
| `// tracepoint 2' |
| |
| (gdb) passcount 12 // Stop on the 12th execution of the |
| `// most recently defined tracepoint.' |
| (gdb) trace foo |
| (gdb) pass 3 |
| (gdb) trace bar |
| (gdb) pass 2 |
| (gdb) trace baz |
| (gdb) pass 1 // Stop tracing when foo has been |
| `// executed 3 times OR when bar has' |
| `// been executed 2 times' |
| `// OR when baz has been executed 1 time.' |
| |
| |
| |
| File: gdb.info, Node: Tracepoint Actions, Next: Listing Tracepoints, Prev: Tracepoint Passcounts, Up: Set Tracepoints |
| |
| 10.1.4 Tracepoint Action Lists |
| ------------------------------ |
| |
| `actions [NUM]' |
| This command will prompt for a list of actions to be taken when the |
| tracepoint is hit. If the tracepoint number NUM is not specified, |
| this command sets the actions for the one that was most recently |
| defined (so that you can define a tracepoint and then say |
| `actions' without bothering about its number). You specify the |
| actions themselves on the following lines, one action at a time, |
| and terminate the actions list with a line containing just `end'. |
| So far, the only defined actions are `collect' and |
| `while-stepping'. |
| |
| To remove all actions from a tracepoint, type `actions NUM' and |
| follow it immediately with `end'. |
| |
| (gdb) collect DATA // collect some data |
| |
| (gdb) while-stepping 5 // single-step 5 times, collect data |
| |
| (gdb) end // signals the end of actions. |
| |
| In the following example, the action list begins with `collect' |
| commands indicating the things to be collected when the tracepoint |
| is hit. Then, in order to single-step and collect additional data |
| following the tracepoint, a `while-stepping' command is used, |
| followed by the list of things to be collected while stepping. The |
| `while-stepping' command is terminated by its own separate `end' |
| command. Lastly, the action list is terminated by an `end' |
| command. |
| |
| (gdb) trace foo |
| (gdb) actions |
| Enter actions for tracepoint 1, one per line: |
| > collect bar,baz |
| > collect $regs |
| > while-stepping 12 |
| > collect $fp, $sp |
| > end |
| end |
| |
| `collect EXPR1, EXPR2, ...' |
| Collect values of the given expressions when the tracepoint is hit. |
| This command accepts a comma-separated list of any valid |
| expressions. In addition to global, static, or local variables, |
| the following special arguments are supported: |
| |
| `$regs' |
| collect all registers |
| |
| `$args' |
| collect all function arguments |
| |
| `$locals' |
| collect all local variables. |
| |
| You can give several consecutive `collect' commands, each one with |
| a single argument, or one `collect' command with several arguments |
| separated by commas: the effect is the same. |
| |
| The command `info scope' (*note info scope: Symbols.) is |
| particularly useful for figuring out what data to collect. |
| |
| `while-stepping N' |
| Perform N single-step traces after the tracepoint, collecting new |
| data at each step. The `while-stepping' command is followed by |
| the list of what to collect while stepping (followed by its own |
| `end' command): |
| |
| > while-stepping 12 |
| > collect $regs, myglobal |
| > end |
| > |
| |
| You may abbreviate `while-stepping' as `ws' or `stepping'. |
| |
| |
| File: gdb.info, Node: Listing Tracepoints, Next: Starting and Stopping Trace Experiments, Prev: Tracepoint Actions, Up: Set Tracepoints |
| |
| 10.1.5 Listing Tracepoints |
| -------------------------- |
| |
| `info tracepoints [NUM]' |
| Display information about the tracepoint NUM. If you don't specify |
| a tracepoint number, displays information about all the tracepoints |
| defined so far. For each tracepoint, the following information is |
| shown: |
| |
| * its number |
| |
| * whether it is enabled or disabled |
| |
| * its address |
| |
| * its passcount as given by the `passcount N' command |
| |
| * its step count as given by the `while-stepping N' command |
| |
| * where in the source files is the tracepoint set |
| |
| * its action list as given by the `actions' command |
| |
| (gdb) info trace |
| Num Enb Address PassC StepC What |
| 1 y 0x002117c4 0 0 <gdb_asm> |
| 2 y 0x0020dc64 0 0 in g_test at g_test.c:1375 |
| 3 y 0x0020b1f4 0 0 in get_data at ../foo.c:41 |
| (gdb) |
| |
| This command can be abbreviated `info tp'. |
| |
| |
| File: gdb.info, Node: Starting and Stopping Trace Experiments, Prev: Listing Tracepoints, Up: Set Tracepoints |
| |
| 10.1.6 Starting and Stopping Trace Experiments |
| ---------------------------------------------- |
| |
| `tstart' |
| This command takes no arguments. It starts the trace experiment, |
| and begins collecting data. This has the side effect of |
| discarding all the data collected in the trace buffer during the |
| previous trace experiment. |
| |
| `tstop' |
| This command takes no arguments. It ends the trace experiment, and |
| stops collecting data. |
| |
| *Note*: a trace experiment and data collection may stop |
| automatically if any tracepoint's passcount is reached (*note |
| Tracepoint Passcounts::), or if the trace buffer becomes full. |
| |
| `tstatus' |
| This command displays the status of the current trace data |
| collection. |
| |
| Here is an example of the commands we described so far: |
| |
| (gdb) trace gdb_c_test |
| (gdb) actions |
| Enter actions for tracepoint #1, one per line. |
| > collect $regs,$locals,$args |
| > while-stepping 11 |
| > collect $regs |
| > end |
| > end |
| (gdb) tstart |
| [time passes ...] |
| (gdb) tstop |
| |
| |
| File: gdb.info, Node: Analyze Collected Data, Next: Tracepoint Variables, Prev: Set Tracepoints, Up: Tracepoints |
| |
| 10.2 Using the Collected Data |
| ============================= |
| |
| After the tracepoint experiment ends, you use GDB commands for |
| examining the trace data. The basic idea is that each tracepoint |
| collects a trace "snapshot" every time it is hit and another snapshot |
| every time it single-steps. All these snapshots are consecutively |
| numbered from zero and go into a buffer, and you can examine them |
| later. The way you examine them is to "focus" on a specific trace |
| snapshot. When the remote stub is focused on a trace snapshot, it will |
| respond to all GDB requests for memory and registers by reading from |
| the buffer which belongs to that snapshot, rather than from _real_ |
| memory or registers of the program being debugged. This means that |
| *all* GDB commands (`print', `info registers', `backtrace', etc.) will |
| behave as if we were currently debugging the program state as it was |
| when the tracepoint occurred. Any requests for data that are not in |
| the buffer will fail. |
| |
| * Menu: |
| |
| * tfind:: How to select a trace snapshot |
| * tdump:: How to display all data for a snapshot |
| * save-tracepoints:: How to save tracepoints for a future run |
| |
| |
| File: gdb.info, Node: tfind, Next: tdump, Up: Analyze Collected Data |
| |
| 10.2.1 `tfind N' |
| ---------------- |
| |
| The basic command for selecting a trace snapshot from the buffer is |
| `tfind N', which finds trace snapshot number N, counting from zero. If |
| no argument N is given, the next snapshot is selected. |
| |
| Here are the various forms of using the `tfind' command. |
| |
| `tfind start' |
| Find the first snapshot in the buffer. This is a synonym for |
| `tfind 0' (since 0 is the number of the first snapshot). |
| |
| `tfind none' |
| Stop debugging trace snapshots, resume _live_ debugging. |
| |
| `tfind end' |
| Same as `tfind none'. |
| |
| `tfind' |
| No argument means find the next trace snapshot. |
| |
| `tfind -' |
| Find the previous trace snapshot before the current one. This |
| permits retracing earlier steps. |
| |
| `tfind tracepoint NUM' |
| Find the next snapshot associated with tracepoint NUM. Search |
| proceeds forward from the last examined trace snapshot. If no |
| argument NUM is given, it means find the next snapshot collected |
| for the same tracepoint as the current snapshot. |
| |
| `tfind pc ADDR' |
| Find the next snapshot associated with the value ADDR of the |
| program counter. Search proceeds forward from the last examined |
| trace snapshot. If no argument ADDR is given, it means find the |
| next snapshot with the same value of PC as the current snapshot. |
| |
| `tfind outside ADDR1, ADDR2' |
| Find the next snapshot whose PC is outside the given range of |
| addresses. |
| |
| `tfind range ADDR1, ADDR2' |
| Find the next snapshot whose PC is between ADDR1 and ADDR2. |
| |
| `tfind line [FILE:]N' |
| Find the next snapshot associated with the source line N. If the |
| optional argument FILE is given, refer to line N in that source |
| file. Search proceeds forward from the last examined trace |
| snapshot. If no argument N is given, it means find the next line |
| other than the one currently being examined; thus saying `tfind |
| line' repeatedly can appear to have the same effect as stepping |
| from line to line in a _live_ debugging session. |
| |
| The default arguments for the `tfind' commands are specifically |
| designed to make it easy to scan through the trace buffer. For |
| instance, `tfind' with no argument selects the next trace snapshot, and |
| `tfind -' with no argument selects the previous trace snapshot. So, by |
| giving one `tfind' command, and then simply hitting <RET> repeatedly |
| you can examine all the trace snapshots in order. Or, by saying `tfind |
| -' and then hitting <RET> repeatedly you can examine the snapshots in |
| reverse order. The `tfind line' command with no argument selects the |
| snapshot for the next source line executed. The `tfind pc' command with |
| no argument selects the next snapshot with the same program counter |
| (PC) as the current frame. The `tfind tracepoint' command with no |
| argument selects the next trace snapshot collected by the same |
| tracepoint as the current one. |
| |
| In addition to letting you scan through the trace buffer manually, |
| these commands make it easy to construct GDB scripts that scan through |
| the trace buffer and print out whatever collected data you are |
| interested in. Thus, if we want to examine the PC, FP, and SP |
| registers from each trace frame in the buffer, we can say this: |
| |
| (gdb) tfind start |
| (gdb) while ($trace_frame != -1) |
| > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ |
| $trace_frame, $pc, $sp, $fp |
| > tfind |
| > end |
| |
| Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 |
| Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 |
| Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 |
| Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 |
| Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 |
| Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 |
| Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 |
| Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 |
| Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 |
| Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 |
| Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 |
| |
| Or, if we want to examine the variable `X' at each source line in |
| the buffer: |
| |
| (gdb) tfind start |
| (gdb) while ($trace_frame != -1) |
| > printf "Frame %d, X == %d\n", $trace_frame, X |
| > tfind line |
| > end |
| |
| Frame 0, X = 1 |
| Frame 7, X = 2 |
| Frame 13, X = 255 |
| |
| |
| File: gdb.info, Node: tdump, Next: save-tracepoints, Prev: tfind, Up: Analyze Collected Data |
| |
| 10.2.2 `tdump' |
| -------------- |
| |
| This command takes no arguments. It prints all the data collected at |
| the current trace snapshot. |
| |
| (gdb) trace 444 |
| (gdb) actions |
| Enter actions for tracepoint #2, one per line: |
| > collect $regs, $locals, $args, gdb_long_test |
| > end |
| |
| (gdb) tstart |
| |
| (gdb) tfind line 444 |
| #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) |
| at gdb_test.c:444 |
| 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) |
| |
| (gdb) tdump |
| Data collected at tracepoint 2, trace frame 1: |
| d0 0xc4aa0085 -995491707 |
| d1 0x18 24 |
| d2 0x80 128 |
| d3 0x33 51 |
| d4 0x71aea3d 119204413 |
| d5 0x22 34 |
| d6 0xe0 224 |
| d7 0x380035 3670069 |
| a0 0x19e24a 1696330 |
| a1 0x3000668 50333288 |
| a2 0x100 256 |
| a3 0x322000 3284992 |
| a4 0x3000698 50333336 |
| a5 0x1ad3cc 1758156 |
| fp 0x30bf3c 0x30bf3c |
| sp 0x30bf34 0x30bf34 |
| ps 0x0 0 |
| pc 0x20b2c8 0x20b2c8 |
| fpcontrol 0x0 0 |
| fpstatus 0x0 0 |
| fpiaddr 0x0 0 |
| p = 0x20e5b4 "gdb-test" |
| p1 = (void *) 0x11 |
| p2 = (void *) 0x22 |
| p3 = (void *) 0x33 |
| p4 = (void *) 0x44 |
| p5 = (void *) 0x55 |
| p6 = (void *) 0x66 |
| gdb_long_test = 17 '\021' |
| |
| (gdb) |
| |
| |
| File: gdb.info, Node: save-tracepoints, Prev: tdump, Up: Analyze Collected Data |
| |
| 10.2.3 `save-tracepoints FILENAME' |
| ---------------------------------- |
| |
| This command saves all current tracepoint definitions together with |
| their actions and passcounts, into a file `FILENAME' suitable for use |
| in a later debugging session. To read the saved tracepoint |
| definitions, use the `source' command (*note Command Files::). |
| |
| |
| File: gdb.info, Node: Tracepoint Variables, Prev: Analyze Collected Data, Up: Tracepoints |
| |
| 10.3 Convenience Variables for Tracepoints |
| ========================================== |
| |
| `(int) $trace_frame' |
| The current trace snapshot (a.k.a. "frame") number, or -1 if no |
| snapshot is selected. |
| |
| `(int) $tracepoint' |
| The tracepoint for the current trace snapshot. |
| |
| `(int) $trace_line' |
| The line number for the current trace snapshot. |
| |
| `(char []) $trace_file' |
| The source file for the current trace snapshot. |
| |
| `(char []) $trace_func' |
| The name of the function containing `$tracepoint'. |
| |
| Note: `$trace_file' is not suitable for use in `printf', use |
| `output' instead. |
| |
| Here's a simple example of using these convenience variables for |
| stepping through all the trace snapshots and printing some of their |
| data. |
| |
| (gdb) tfind start |
| |
| (gdb) while $trace_frame != -1 |
| > output $trace_file |
| > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint |
| > tfind |
| > end |
| |
| |
| File: gdb.info, Node: Overlays, Next: Languages, Prev: Tracepoints, Up: Top |
| |
| 11 Debugging Programs That Use Overlays |
| *************************************** |
| |
| If your program is too large to fit completely in your target system's |
| memory, you can sometimes use "overlays" to work around this problem. |
| GDB provides some support for debugging programs that use overlays. |
| |
| * Menu: |
| |
| * How Overlays Work:: A general explanation of overlays. |
| * Overlay Commands:: Managing overlays in GDB. |
| * Automatic Overlay Debugging:: GDB can find out which overlays are |
| mapped by asking the inferior. |
| * Overlay Sample Program:: A sample program using overlays. |
| |
| |
| File: gdb.info, Node: How Overlays Work, Next: Overlay Commands, Up: Overlays |
| |
| 11.1 How Overlays Work |
| ====================== |
| |
| Suppose you have a computer whose instruction address space is only 64 |
| kilobytes long, but which has much more memory which can be accessed by |
| other means: special instructions, segment registers, or memory |
| management hardware, for example. Suppose further that you want to |
| adapt a program which is larger than 64 kilobytes to run on this system. |
| |
| One solution is to identify modules of your program which are |
| relatively independent, and need not call each other directly; call |
| these modules "overlays". Separate the overlays from the main program, |
| and place their machine code in the larger memory. Place your main |
| program in instruction memory, but leave at least enough space there to |
| hold the largest overlay as well. |
| |
| Now, to call a function located in an overlay, you must first copy |
| that overlay's machine code from the large memory into the space set |
| aside for it in the instruction memory, and then jump to its entry point |
| there. |
| |
| Data Instruction Larger |
| Address Space Address Space Address Space |
| +-----------+ +-----------+ +-----------+ |
| | | | | | | |
| +-----------+ +-----------+ +-----------+<-- overlay 1 |
| | program | | main | .----| overlay 1 | load address |
| | variables | | program | | +-----------+ |
| | and heap | | | | | | |
| +-----------+ | | | +-----------+<-- overlay 2 |
| | | +-----------+ | | | load address |
| +-----------+ | | | .-| overlay 2 | |
| | | | | | | |
| mapped --->+-----------+ | | +-----------+ |
| address | | | | | | |
| | overlay | <-' | | | |
| | area | <---' +-----------+<-- overlay 3 |
| | | <---. | | load address |
| +-----------+ `--| overlay 3 | |
| | | | | |
| +-----------+ | | |
| +-----------+ |
| | | |
| +-----------+ |
| |
| A code overlay |
| |
| The diagram (*note A code overlay::) shows a system with separate |
| data and instruction address spaces. To map an overlay, the program |
| copies its code from the larger address space to the instruction |
| address space. Since the overlays shown here all use the same mapped |
| address, only one may be mapped at a time. For a system with a single |
| address space for data and instructions, the diagram would be similar, |
| except that the program variables and heap would share an address space |
| with the main program and the overlay area. |
| |
| An overlay loaded into instruction memory and ready for use is |
| called a "mapped" overlay; its "mapped address" is its address in the |
| instruction memory. An overlay not present (or only partially present) |
| in instruction memory is called "unmapped"; its "load address" is its |
| address in the larger memory. The mapped address is also called the |
| "virtual memory address", or "VMA"; the load address is also called the |
| "load memory address", or "LMA". |
| |
| Unfortunately, overlays are not a completely transparent way to |
| adapt a program to limited instruction memory. They introduce a new |
| set of global constraints you must keep in mind as you design your |
| program: |
| |
| * Before calling or returning to a function in an overlay, your |
| program must make sure that overlay is actually mapped. |
| Otherwise, the call or return will transfer control to the right |
| address, but in the wrong overlay, and your program will probably |
| crash. |
| |
| * If the process of mapping an overlay is expensive on your system, |
| you will need to choose your overlays carefully to minimize their |
| effect on your program's performance. |
| |
| * The executable file you load onto your system must contain each |
| overlay's instructions, appearing at the overlay's load address, |
| not its mapped address. However, each overlay's instructions must |
| be relocated and its symbols defined as if the overlay were at its |
| mapped address. You can use GNU linker scripts to specify |
| different load and relocation addresses for pieces of your |
| program; see *note Overlay Description: (ld.info)Overlay |
| Description. |
| |
| * The procedure for loading executable files onto your system must |
| be able to load their contents into the larger address space as |
| well as the instruction and data spaces. |
| |
| |
| The overlay system described above is rather simple, and could be |
| improved in many ways: |
| |
| * If your system has suitable bank switch registers or memory |
| management hardware, you could use those facilities to make an |
| overlay's load area contents simply appear at their mapped address |
| in instruction space. This would probably be faster than copying |
| the overlay to its mapped area in the usual way. |
| |
| * If your overlays are small enough, you could set aside more than |
| one overlay area, and have more than one overlay mapped at a time. |
| |
| * You can use overlays to manage data, as well as instructions. In |
| general, data overlays are even less transparent to your design |
| than code overlays: whereas code overlays only require care when |
| you call or return to functions, data overlays require care every |
| time you access the data. Also, if you change the contents of a |
| data overlay, you must copy its contents back out to its load |
| address before you can copy a different data overlay into the same |
| mapped area. |
| |
| |
| |
| File: gdb.info, Node: Overlay Commands, Next: Automatic Overlay Debugging, Prev: How Overlays Work, Up: Overlays |
| |
| 11.2 Overlay Commands |
| ===================== |
| |
| To use GDB's overlay support, each overlay in your program must |
| correspond to a separate section of the executable file. The section's |
| virtual memory address and load memory address must be the overlay's |
| mapped and load addresses. Identifying overlays with sections allows |
| GDB to determine the appropriate address of a function or variable, |
| depending on whether the overlay is mapped or not. |
| |
| GDB's overlay commands all start with the word `overlay'; you can |
| abbreviate this as `ov' or `ovly'. The commands are: |
| |
| `overlay off' |
| Disable GDB's overlay support. When overlay support is disabled, |
| GDB assumes that all functions and variables are always present at |
| their mapped addresses. By default, GDB's overlay support is |
| disabled. |
| |
| `overlay manual' |
| Enable "manual" overlay debugging. In this mode, GDB relies on |
| you to tell it which overlays are mapped, and which are not, using |
| the `overlay map-overlay' and `overlay unmap-overlay' commands |
| described below. |
| |
| `overlay map-overlay OVERLAY' |
| `overlay map OVERLAY' |
| Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of |
| the object file section containing the overlay. When an overlay |
| is mapped, GDB assumes it can find the overlay's functions and |
| variables at their mapped addresses. GDB assumes that any other |
| overlays whose mapped ranges overlap that of OVERLAY are now |
| unmapped. |
| |
| `overlay unmap-overlay OVERLAY' |
| `overlay unmap OVERLAY' |
| Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the |
| name of the object file section containing the overlay. When an |
| overlay is unmapped, GDB assumes it can find the overlay's |
| functions and variables at their load addresses. |
| |
| `overlay auto' |
| Enable "automatic" overlay debugging. In this mode, GDB consults |
| a data structure the overlay manager maintains in the inferior to |
| see which overlays are mapped. For details, see *note Automatic |
| Overlay Debugging::. |
| |
| `overlay load-target' |
| `overlay load' |
| Re-read the overlay table from the inferior. Normally, GDB |
| re-reads the table GDB automatically each time the inferior stops, |
| so this command should only be necessary if you have changed the |
| overlay mapping yourself using GDB. This command is only useful |
| when using automatic overlay debugging. |
| |
| `overlay list-overlays' |
| `overlay list' |
| Display a list of the overlays currently mapped, along with their |
| mapped addresses, load addresses, and sizes. |
| |
| |
| Normally, when GDB prints a code address, it includes the name of |
| the function the address falls in: |
| |
| (gdb) print main |
| $3 = {int ()} 0x11a0 <main> |
| When overlay debugging is enabled, GDB recognizes code in unmapped |
| overlays, and prints the names of unmapped functions with asterisks |
| around them. For example, if `foo' is a function in an unmapped |
| overlay, GDB prints it this way: |
| |
| (gdb) overlay list |
| No sections are mapped. |
| (gdb) print foo |
| $5 = {int (int)} 0x100000 <*foo*> |
| When `foo''s overlay is mapped, GDB prints the function's name |
| normally: |
| |
| (gdb) overlay list |
| Section .ov.foo.text, loaded at 0x100000 - 0x100034, |
| mapped at 0x1016 - 0x104a |
| (gdb) print foo |
| $6 = {int (int)} 0x1016 <foo> |
| |
| When overlay debugging is enabled, GDB can find the correct address |
| for functions and variables in an overlay, whether or not the overlay |
| is mapped. This allows most GDB commands, like `break' and |
| `disassemble', to work normally, even on unmapped code. However, GDB's |
| breakpoint support has some limitations: |
| |
| * You can set breakpoints in functions in unmapped overlays, as long |
| as GDB can write to the overlay at its load address. |
| |
| * GDB can not set hardware or simulator-based breakpoints in |
| unmapped overlays. However, if you set a breakpoint at the end of |
| your overlay manager (and tell GDB which overlays are now mapped, |
| if you are using manual overlay management), GDB will re-set its |
| breakpoints properly. |
| |
| |
| File: gdb.info, Node: Automatic Overlay Debugging, Next: Overlay Sample Program, Prev: Overlay Commands, Up: Overlays |
| |
| 11.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 |
| |
| 11.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 |
| |
| 12 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 |
| |
| 12.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 |
| |
| 12.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 |
| |
| `.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 |
| |
| 12.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 |
| |
| 12.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 |
| |
| 12.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 |
| |
| 12.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 |
| |
| 12.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 |
| |
| 12.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 |
| |
| 12.4 Supported Languages |
| ======================== |
| |
| GDB supports C, C++, Objective-C, Fortran, Java, 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++ |
| * Objective-C:: Objective-C |
| * Fortran:: Fortran |
| * Pascal:: Pascal |
| * Modula-2:: Modula-2 |
| * Ada:: Ada |
| |
| |
| File: gdb.info, Node: C, Next: Objective-C, Up: Supported Languages |
| |
| 12.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 |
| |
| 12.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 |
| |
| 12.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 |
| |
| 12.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 |
| |
| 12.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 |
| |
| 12.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 |
| |
| 12.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 |
| |
| 12.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 breakpoint menus help you specify which function definition |
| you want. *Note Breakpoint Menus: Breakpoint Menus. |
| |
| `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 |
| |
| 12.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: Objective-C, Next: Fortran, Prev: C, Up: Supported Languages |
| |
| 12.4.2 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 |
| |
| 12.4.2.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 |
| |
| 12.4.2.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: Fortran, Next: Pascal, Prev: Objective-C, Up: Supported Languages |
| |
| 12.4.3 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 |
| |
| 12.4.3.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. |
| |
| |
| File: gdb.info, Node: Fortran Defaults, Next: Special Fortran Commands, Prev: Fortran Operators, Up: Fortran |
| |
| 12.4.3.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 |
| |
| 12.4.3.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 |
| |
| 12.4.4 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 |
| |
| 12.4.5 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 |
| |
| 12.4.5.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 |
| |
| 12.4.5.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 |
| |
| 12.4.5.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 |
| |
| 12.4.5.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 |
| |
| 12.4.5.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 |
| |
| 12.4.5.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 |
| |
| 12.4.5.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 |
| |
| 12.4.5.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 |
| |
| 12.4.5.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 |
| |
| 12.4.6 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 Glitches:: Known peculiarities of Ada mode. |
| |
| |
| File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada |
| |
| 12.4.6.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 there were implicit |
| `with' and `use' clauses in effect for all user-written packages, |
| 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 |
| |
| 12.4.6.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: |
| |
| set An_Array := (1, 2, 3, 4, 5, 6) |
| set An_Array := (1, others => 0) |
| set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) |
| set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) |
| set A_Record := (1, "Peter", True); |
| 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: |
| |
| set A_Rec.Len := 4 |
| 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. |
| |
| |
| File: gdb.info, Node: Additions to Ada, Next: Stopping Before Main Program, Prev: Omissions from Ada, Up: Ada |
| |
| 12.4.6.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 |
| |
| set x := y + 3 |
| 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: |
| |
| break f |
| 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 |
| |
| 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 Glitches, Prev: Additions to Ada, Up: Ada |
| |
| 12.4.6.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 Glitches, Prev: Stopping Before Main Program, Up: Ada |
| |
| 12.4.6.5 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. |
| |
| * Currently, the debugger has insufficient information to determine |
| whether certain pointers represent pointers to objects or the |
| objects themselves. Thus, the user may have to tack an extra |
| `.all' after an expression to get it printed properly. |
| |
| * 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 type of the 'Address attribute may not be `System.Address'. |
| |
| * 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. |
| |
| |
| File: gdb.info, Node: Unsupported Languages, Prev: Supported Languages, Up: Languages |
| |
| 12.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 |
| |
| 13 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. |
| |
| `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 declared |
| 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. |
| |
| `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 |
| |
| 14 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 |
| |
| 14.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 |
| |
| 14.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 |
| |
| 14.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 |
| |
| 14.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. |
| |
| |
| File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering |
| |
| 14.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. |
| |
| `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. |
| |
| 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 |
| |
| 14.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 |
| |
| 15 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 |
| * Symbol Errors:: Errors reading symbol files |
| |
| |
| File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files |
| |
| 15.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 FILENAME [ -readnow ]' |
| `file FILENAME [ -readnow ]' |
| 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' |
| `info sharedlibrary' |
| Print the names of the shared libraries which are currently 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. A copy of the target's libraries need to be present on |
| the host system; 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. |
| |
| 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. |
| |
| |
| File: gdb.info, Node: Separate Debug Files, Next: Symbol Errors, Prev: Files, Up: GDB Files |
| |
| 15.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 CRC32 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 DIRECTORY' |
| Set the directory which GDB searches for separate debugging |
| information files to DIRECTORY. |
| |
| `show debug-file-directory' |
| Show the directory 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. |
| |
| Since there are many different ways to compute CRC's for the debug link |
| (different polynomials, reversals, byte ordering, etc.), the simplest |
| way to describe the CRC used in `.gnu_debuglink' sections is to give |
| the complete code for a function that computes it: |
| |
| 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: Symbol Errors, Prev: Separate Debug Files, Up: GDB Files |
| |
| 15.3 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: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top |
| |
| 16 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 |
| |
| 16.1 Active Targets |
| =================== |
| |
| There are three classes of targets: processes, core files, and |
| executable files. GDB can work concurrently on up to three active |
| targets, one in each class. This allows you to (for example) start a |
| process and inspect its activity without abandoning your work on a core |
| file. |
| |
| For example, if you execute `gdb a.out', then the executable file |
| `a.out' is the only active target. If you designate a core file as |
| well--presumably from a prior run that crashed and coredumped--then GDB |
| has two active targets and uses them in tandem, looking first in the |
| corefile target, then in the executable file, to satisfy requests for |
| memory addresses. (Typically, these two classes of target are |
| complementary, since core files contain only a program's read-write |
| memory--variables and so on--plus machine status, while executable |
| files contain only the program text and initialized data.) |
| |
| When you type `run', your executable file becomes an active process |
| target as well. When a process target is active, all GDB commands |
| requesting memory addresses refer to that target; addresses in an |
| active core file or executable file target are obscured while the |
| process target is active. |
| |
| 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 |
| |
| 16.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' |
| 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 |
| |
| 16.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 |
| |
| 17 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 |
| |
| 17.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 and to step and continue the remote |
| program. |
| |
| 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 |
| |
| 17.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 |
| |
| 17.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'. |
| |
| 17.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. |
| |
| 17.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. |
| |
| 17.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::). |
| |
| 17.3.1.3 Other Command-Line Arguments for `gdbserver' |
| ..................................................... |
| |
| You can include `--debug' on the `gdbserver' command line. `gdbserver' |
| will display extra status information about the debugging process. |
| This option is intended for `gdbserver' development and for bug reports |
| to the developers. |
| |
| 17.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. |
| |
| 17.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 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. |
| |
| |
| ---------- 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 |
| |
| 17.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). |
| |
| 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-spu-object' `qXfer:spu:read' `info spu' |
| `write-spu-object' `qXfer:spu:write' `info spu' |
| `get-thread-local- `qGetTLSAddr' Displaying |
| storage-address' `__thread' |
| variables |
| `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' |
| |
| |
| File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Debugging |
| |
| 17.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 |
| |
| 17.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 |
| |
| 17.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 |
| |
| 17.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 |
| |
| 18 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 |
| |
| 18.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 |
| |
| |
| File: gdb.info, Node: HP-UX, Next: BSD libkvm Interface, Up: Native |
| |
| 18.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 |
| |
| 18.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 |
| |
| 18.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 |
| |
| 18.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 |
| |
| 18.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. 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 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'i, 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 |
| |
| 18.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. |
| |
| 18.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...] |
| |
| 18.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 |
| |
| 18.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, Prev: Hurd Native, Up: Native |
| |
| 18.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: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations |
| |
| 18.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 |
| |
| 18.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 |
| |
| 18.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 |
| |
| 18.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 |
| |
| 18.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 |
| |
| 18.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 |
| * 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 |
| |
| 18.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 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. |
| |
| |
| File: gdb.info, Node: M32R/D, Next: M68K, Prev: ARM, Up: Embedded Processors |
| |
| 18.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: MIPS Embedded, Prev: M32R/D, Up: Embedded Processors |
| |
| 18.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: MIPS Embedded, Next: OpenRISC 1000, Prev: M68K, Up: Embedded Processors |
| |
| 18.3.4 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 acknowledgement 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 |
| |
| 18.3.5 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 |
| |
| 18.3.6 PowerPC Embedded |
| ----------------------- |
| |
| GDB provides the following PowerPC-specific commands: |
| |
| `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. |
| |
| `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 |
| |
| 18.3.7 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 |
| |
| 18.3.8 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 |
| |
| 18.3.8.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 |
| |
| 18.3.8.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 |
| |
| 18.3.8.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 |
| |
| 18.3.8.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 |
| |
| 18.3.9 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 |
| |
| 18.3.10 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 |
| |
| 18.3.11 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 |
| |
| 18.3.12 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 |
| |
| 18.3.13 Renesas Super-H |
| ----------------------- |
| |
| For the Renesas Super-H processor, GDB provides these commands: |
| |
| `regs' |
| Show the values of all Super-H registers. |
| |
| |
| File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations |
| |
| 18.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 |
| |
| 18.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 |
| |
| 18.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 |
| |
| 18.4.3 Alpha |
| ------------ |
| |
| See the following section. |
| |
| |
| File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures |
| |
| 18.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 |
| |
| 18.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 |
| |
| 18.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. |
| |
| |
| |
| File: gdb.info, Node: PowerPC, Prev: SPU, Up: Architectures |
| |
| 18.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. |
| |
| |
| File: gdb.info, Node: Controlling GDB, Next: Sequences, Prev: Configurations, Up: Top |
| |
| 19 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 |
| |
| |
| File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB |
| |
| 19.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 |
| |
| 19.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 |
| |
| 19.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 |
| |
| 19.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'. |
| |
| `show pagination' |
| Show the current pagination mode. |
| |
| |
| File: gdb.info, Node: Numbers, Next: ABI, Prev: Screen Size, Up: Controlling GDB |
| |
| 19.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 |
| |
| 19.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 |
| |
| 19.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. |
| |
| `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, Prev: Messages/Warnings, Up: Controlling GDB |
| |
| 19.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 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 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 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 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 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 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: Sequences, Next: Interpreters, Prev: Controlling GDB, Up: Top |
| |
| 20 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 |
| |
| 20.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. |
| |
| 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 |
| |
| 20.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'. 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 |
| |
| 20.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: |
| |
| `source [`-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 searches for FILENAME in the current directory and then on the |
| search path (specified with the `directory' command). |
| |
| 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 |
| |
| 20.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 |
| |
| |
| |
| File: gdb.info, Node: Interpreters, Next: TUI, Prev: Sequences, Up: Top |
| |
| 21 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 |
| |
| 22 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 |
| |
| 22.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 |
| |
| 22.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 |
| |
| 22.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 |
| |
| 22.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. |
| |
| `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 |
| |
| 22.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 |
| |
| 23 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 |
| |
| 24 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 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 Command Syntax, Next: GDB/MI Compatibility with CLI, Up: GDB/MI |
| |
| 24.1 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 |
| |
| 24.1.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 |
| |
| 24.1.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. If an execution |
| command is interrupted by the `-exec-interrupt' command, the TOKEN |
| associated with the `*stopped' message is the one of the original |
| execution command, not the one of the interrupt 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 |
| |
| 24.2 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 |
| |
| 24.3 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>. |
| There is also the mailing list <dmi-discuss@lists.freestandards.org>, |
| hosted by the Free Standards Group, which has the aim of creating a |
| more general MI protocol called Debugger Machine Interface (DMI) that |
| will become a standard for all debuggers, not just GDB. |
| |
| |
| File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI |
| |
| 24.4 GDB/MI Output Records |
| ========================== |
| |
| * Menu: |
| |
| * GDB/MI Result Records:: |
| * GDB/MI Stream Records:: |
| * GDB/MI Out-of-band Records:: |
| |
| |
| File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records |
| |
| 24.4.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"' |
| The asynchronous operation was successfully started. The target is |
| running. |
| |
| `"^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 Out-of-band Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records |
| |
| 24.4.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 Out-of-band Records, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records |
| |
| 24.4.3 GDB/MI Out-of-band Records |
| --------------------------------- |
| |
| "Out-of-band" 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 (e.g., a breakpoint modified) or a result of |
| target activity (e.g., target stopped). |
| |
| The following is a preliminary list of possible out-of-band records. |
| In particular, the EXEC-ASYNC-OUTPUT records. |
| |
| `*stopped,reason="REASON"' |
| |
| REASON can be one of the following: |
| |
| `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. |
| |
| |
| File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI |
| |
| 24.5 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",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 |
| |
| 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 |
| |
| 24.6 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 |
| |
| 24.7 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",addr="0x000100d0",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-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 ] |
| [ -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. |
| |
| 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-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 |
| |
| 24.8 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 |
| ....... |
| |
| Don't have one around. |
| |
| The `-exec-show-arguments' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-show-arguments |
| |
| Print the arguments of the program. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `show args'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| 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 |
| |
| 24.9 GDB/MI Thread Commands |
| =========================== |
| |
| The `-thread-info' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -thread-info |
| |
| GDB Command |
| ........... |
| |
| No equivalent. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-thread-list-all-threads' Command |
| -------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -thread-list-all-threads |
| |
| GDB Command |
| ........... |
| |
| The equivalent GDB command is `info threads'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| 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. |
| |
| GDB Command |
| ........... |
| |
| Part of `info threads' supplies the same information. |
| |
| Example |
| ....... |
| |
| No threads present, besides the main process: |
| |
| (gdb) |
| -thread-list-ids |
| ^done,thread-ids={},number-of-threads="0" |
| (gdb) |
| |
| Several threads: |
| |
| (gdb) |
| -thread-list-ids |
| ^done,thread-ids={thread-id="3",thread-id="2",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. |
| |
| 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 |
| |
| 24.10 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 |
| |
| Resumes the execution of the inferior program until a breakpoint is |
| encountered, or until the inferior exits. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB corresponding is `continue'. |
| |
| Example |
| ....... |
| |
| -exec-continue |
| ^running |
| (gdb) |
| @Hello world |
| *stopped,reason="breakpoint-hit",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 |
| |
| Resumes the execution of the inferior program until the current |
| function is exited. Displays the results returned by the function. |
| |
| 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 |
| |
| 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. |
| |
| 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-next' Command |
| ------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-next |
| |
| Resumes execution of the inferior program, stopping when the |
| beginning of the next source line is reached. |
| |
| 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 |
| |
| 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. |
| |
| 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",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 |
| |
| 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. |
| |
| 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",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 |
| |
| 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. |
| |
| 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 |
| |
| Resumes the inferior which executes one machine 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 |
| |
| 24.11 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 SHOW-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. |
| |
| The SHOW-VALUES argument must have a value of 0 or 1. A value of 0 |
| means that only the names of the arguments are listed, a value of 1 |
| means that both names and values of the arguments are printed. |
| |
| 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. |
| |
| `LINE' |
| Line number corresponding to the `$pc'. |
| |
| 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. |
| |
| 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-select-frame' Command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-select-frame FRAMENUM |
| |
| Change the selected frame. Select a different frame FRAMENUM on the |
| stack. |
| |
| 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 |
| |
| 24.12 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. |
| |
| The following is the complete set of GDB/MI operations defined to |
| access this functionality: |
| |
| *Operation* *Description* |
| `-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 |
| |
| 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 `-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 on 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. |
| |
| 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 |
| |
| Result |
| ...... |
| |
| This operation returns the name, number of children and the type of the |
| object created. Type is returned as a string as the ones generated by |
| the GDB CLI: |
| |
| name="NAME",numchild="N",type="TYPE" |
| |
| 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 |
| |
| The `-var-list-children' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-list-children [PRINT-VALUES] NAME |
| 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 for 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. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-list-children n |
| ^done,numchild=N,children=[{name=NAME, |
| numchild=N,type=TYPE},(repeats N times)] |
| (gdb) |
| -var-list-children --all-values n |
| ^done,numchild=N,children=[{name=NAME, |
| 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. |
| |
| 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 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 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 options 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. |
| |
| 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 field in_scope may take 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. |
| |
| 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) |
| |
| |
| File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI |
| |
| 24.13 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) or 1 (meaning mixed source |
| and disassembly). |
| |
| 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",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 |
| ------------------------------- |
| |
| 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) |
| |
| |
| File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI |
| |
| 24.14 GDB/MI Tracepoint Commands |
| ================================ |
| |
| The tracepoint commands are not yet implemented. |
| |
| |
| File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI |
| |
| 24.15 GDB/MI Symbol Query Commands |
| ================================== |
| |
| The `-symbol-info-address' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-address SYMBOL |
| |
| Describe where SYMBOL is stored. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info address'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-info-file' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-file |
| |
| Show the file for the symbol. |
| |
| GDB Command |
| ........... |
| |
| There's no equivalent GDB command. `gdbtk' has `gdb_find_file'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-info-function' Command |
| ----------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-function |
| |
| Show which function the symbol lives in. |
| |
| GDB Command |
| ........... |
| |
| `gdb_get_function' in `gdbtk'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-info-line' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-line |
| |
| Show the core addresses of the code for a source line. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info line'. `gdbtk' has the |
| `gdb_get_line' and `gdb_get_file' commands. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-info-symbol' Command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-info-symbol ADDR |
| |
| Describe what symbol is at location ADDR. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info symbol'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-list-functions' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -symbol-list-functions |
| |
| List the functions in the executable. |
| |
| GDB Command |
| ........... |
| |
| `info functions' in GDB, `gdb_listfunc' and `gdb_search' in `gdbtk'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| 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) |
| |
| The `-symbol-list-types' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-list-types |
| |
| List all the type names. |
| |
| GDB Command |
| ........... |
| |
| The corresponding commands are `info types' in GDB, `gdb_search' in |
| `gdbtk'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-list-variables' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -symbol-list-variables |
| |
| List all the global and static variable names. |
| |
| GDB Command |
| ........... |
| |
| `info variables' in GDB, `gdb_search' in `gdbtk'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-locate' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-locate |
| |
| GDB Command |
| ........... |
| |
| `gdb_loc' in `gdbtk'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-symbol-type' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-type VARIABLE |
| |
| Show type of VARIABLE. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `ptype', `gdbtk' has |
| `gdb_obj_variable'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| |
| File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI |
| |
| 24.16 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-sections' Command |
| -------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -file-list-exec-sections |
| |
| List the sections of the current executable file. |
| |
| GDB Command |
| ........... |
| |
| The GDB command `info file' shows, among the rest, the same information |
| as this command. `gdbtk' has a corresponding command `gdb_load_info'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| 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-list-shared-libraries' Command |
| ----------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -file-list-shared-libraries |
| |
| List the shared libraries in the program. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info shared'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-file-list-symbol-files' Command |
| ------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -file-list-symbol-files |
| |
| List symbol files. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info file' (part of it). |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| 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 |
| |
| 24.17 GDB/MI Target Manipulation Commands |
| ========================================= |
| |
| The `-target-attach' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-attach PID | FILE |
| |
| Attach to a process PID or a file FILE outside of GDB. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `attach'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-target-compare-sections' Command |
| -------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-compare-sections [ SECTION ] |
| |
| Compare data of section SECTION on target to the exec file. Without |
| the argument, all sections are compared. |
| |
| GDB Command |
| ........... |
| |
| The GDB equivalent is `compare-sections'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-target-detach' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-detach |
| |
| Detach from the remote target which normally resumes its execution. |
| 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) |
| |
| The `-target-exec-status' Command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-exec-status |
| |
| Provide information on the state of the target (whether it is |
| running or not, for instance). |
| |
| GDB Command |
| ........... |
| |
| There's no equivalent GDB command. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-target-list-available-targets' Command |
| -------------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-list-available-targets |
| |
| List the possible targets to connect to. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `help target'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-target-list-current-targets' Command |
| ------------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -target-list-current-targets |
| |
| Describe the current target. |
| |
| GDB Command |
| ........... |
| |
| The corresponding information is printed by `info file' (among other |
| things). |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-target-list-parameters' Command |
| ------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-list-parameters |
| |
| 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 `async', `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 async /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 |
| |
| 24.18 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-put' 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 |
| |
| 24.19 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 `-exec-abort' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-abort |
| |
| Kill the inferior running program. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `kill'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| 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. |
| |
| |
| 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",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: GDB Bugs, Prev: GDB/MI, Up: Top |
| |
| 25 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 |
| |
| 25.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 |
| |
| 25.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. |
| |
| |
| File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations |
| |
| 25.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 |
| |
| 25.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 |
| |
| 25.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 |
| |
| 25.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 |
| |
| 25.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: GDB Bugs, Next: Command Line Editing, Prev: Annotations, Up: Top |
| |
| 26 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 |
| |
| 26.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 |
| |
| 26.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 |
| |
| 27 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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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 |
| |
| 27.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: Formatting Documentation, Prev: Command Line Editing, Up: Top |
| |
| 28 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 |
| |
| 28.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 |
| |
| 28.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 |
| |
| 28.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 |
| |
| 28.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: Formatting Documentation, Next: Installing GDB, Prev: Using History Interactively, Up: Top |
| |
| Appendix A 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-6.8/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-6.8', in the case of version 6.8), 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-6.8/gdb') and type: |
| |
| make gdb.dvi |
| |
| Then give `gdb.dvi' to your DVI printing program. |
| |
| ---------- Footnotes ---------- |
| |
| (1) In `gdb-6.8/gdb/refcard.ps' of the version 6.8 release. |
| |
| |
| File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top |
| |
| Appendix B 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 |
| |
| |
| File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB |
| |
| B.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::) |
| |
| |
| |
| File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB |
| |
| B.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 6.8 distribution is in the `gdb-6.8' |
| directory. That directory contains: |
| |
| `gdb-6.8/configure (and supporting files)' |
| script for configuring GDB and all its supporting libraries |
| |
| `gdb-6.8/gdb' |
| the source specific to GDB itself |
| |
| `gdb-6.8/bfd' |
| source for the Binary File Descriptor library |
| |
| `gdb-6.8/include' |
| GNU include files |
| |
| `gdb-6.8/libiberty' |
| source for the `-liberty' free software library |
| |
| `gdb-6.8/opcodes' |
| source for the library of opcode tables and disassemblers |
| |
| `gdb-6.8/readline' |
| source for the GNU command-line interface |
| |
| `gdb-6.8/glob' |
| source for the GNU filename pattern-matching subroutine |
| |
| `gdb-6.8/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-6.8' 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-6.8 |
| ./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-6.8' |
| source directory for version 6.8, `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 |
| |
| B.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 6.8, you can build GDB in a separate |
| directory for a Sun 4 like this: |
| |
| cd gdb-6.8 |
| mkdir ../gdb-sun4 |
| cd ../gdb-sun4 |
| ../gdb-6.8/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-6.8/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-6.8' (or in a separate configured directory configured with |
| `--srcdir=DIRNAME/gdb-6.8'), 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 |
| |
| B.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-6.8', for version 6.8). |
| |
| |
| File: gdb.info, Node: Configure Options, Prev: Config Names, Up: Installing GDB |
| |
| B.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: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top |
| |
| Appendix C 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' |
| Translate the given EXPRESSION into remote agent bytecodes. This |
| command is useful for debugging the Agent Expression mechanism |
| (*note Agent Expressions::). |
| |
| `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. |
| |
| |
| `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 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; 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 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 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 show-debug-regs' |
| Control whether to show variables that mirror the x86 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 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. 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. |
| |
| |
| 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 D GDB Remote Serial Protocol |
| ************************************* |
| |
| * Menu: |
| |
| * Overview:: |
| * Packets:: |
| * Stop Reply Packets:: |
| * General Query Packets:: |
| * Register Packet Format:: |
| * Tracepoint Packets:: |
| * Host I/O Packets:: |
| * Interrupts:: |
| * Examples:: |
| * File-I/O Remote Protocol Extension:: |
| * Library List Format:: |
| * Memory Map Format:: |
| |
| |
| File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol |
| |
| D.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) 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 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 (the target has again stopped). |
| |
| 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 |
| |
| D.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. |
| |
| 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. |
| |
| 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::). |
| |
| `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' |
| Detach GDB from the remote system. Sent to the remote target |
| before GDB disconnects via the `detach' command. |
| |
| 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. |
| |
| `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 T' |
| 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 T may be `-1', meaning all the threads, a thread |
| number, or `0' which means pick any thread. |
| |
| 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 XX' |
| Find out if the thread XX is alive. |
| |
| 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 is a |
| hexadecimal integer identifying the process. The attached process |
| is stopped. |
| |
| 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::) |
| |
| `vCont[;ACTION[:TID]]...' |
| Resume the inferior, specifying different actions for each thread. |
| If an action is specified with no TID, 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. |
| Specifying multiple default actions is an error; specifying no |
| actions is also an error. Thread IDs are specified in |
| hexadecimal. Currently supported actions are: |
| |
| `c' |
| Continue. |
| |
| `C SIG' |
| Continue with signal SIG. SIG should be two hex digits. |
| |
| `s' |
| Step. |
| |
| `S SIG' |
| Step with signal SIG. SIG should be two hex digits. |
| |
| The optional ADDR argument normally associated with these packets |
| is not supported in `vCont'. |
| |
| 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. |
| |
| 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. |
| |
| `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::) |
| |
| `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,LENGTH' |
| `Z TYPE,ADDR,LENGTH' |
| Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint |
| starting at address ADDRESS and covering the next LENGTH bytes. |
| |
| 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,LENGTH' |
| `Z0,ADDR,LENGTH' |
| Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR |
| of size LENGTH. |
| |
| A memory breakpoint is implemented by replacing the instruction at |
| ADDR with a software breakpoint or trap instruction. The LENGTH |
| is used by targets that 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). |
| |
| _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,LENGTH' |
| `Z1,ADDR,LENGTH' |
| Insert (`Z1') or remove (`z1') a hardware breakpoint at address |
| ADDR of size LENGTH. |
| |
| A hardware breakpoint is implemented using a mechanism that is not |
| dependant on being able to modify the target's memory. |
| |
| _Implementation note: A hardware breakpoint is not affected by code |
| movement._ |
| |
| Reply: |
| `OK' |
| success |
| |
| `' |
| not supported |
| |
| `E NN' |
| for an error |
| |
| `z2,ADDR,LENGTH' |
| `Z2,ADDR,LENGTH' |
| Insert (`Z2') or remove (`z2') a write watchpoint. |
| |
| Reply: |
| `OK' |
| success |
| |
| `' |
| not supported |
| |
| `E NN' |
| for an error |
| |
| `z3,ADDR,LENGTH' |
| `Z3,ADDR,LENGTH' |
| Insert (`Z3') or remove (`z3') a read watchpoint. |
| |
| Reply: |
| `OK' |
| success |
| |
| `' |
| not supported |
| |
| `E NN' |
| for an error |
| |
| `z4,ADDR,LENGTH' |
| `Z4,ADDR,LENGTH' |
| Insert (`Z4') or remove (`z4') an access watchpoint. |
| |
| 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 |
| |
| D.3 Stop Reply Packets |
| ====================== |
| |
| The `C', `c', `S', `s' and `?' packets can receive any of the below as |
| a reply. In the case of the `C', `c', `S' and `s' packets, 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 process ID, in hex. |
| |
| * 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. |
| |
| `W AA' |
| The process exited, and AA is the exit status. This is only |
| applicable to certain targets. |
| |
| `X AA' |
| The process terminated with signal AA. |
| |
| `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. |
| |
| `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: Register Packet Format, Prev: Stop Reply Packets, Up: Remote Protocol |
| |
| D.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: |
| |
| `qC' |
| Return the current thread id. |
| |
| Reply: |
| `QC PID' |
| Where PID is an unsigned hexadecimal process id. |
| |
| `(anything else)' |
| Any other reply implies the old pid. |
| |
| `qCRC:ADDR,LENGTH' |
| Compute the CRC checksum of a block of memory. 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 ID' |
| A single thread id |
| |
| `m ID,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, in big-endian unsigned hex, 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 el, for "last"). |
| |
| `qGetTLSAddr:THREAD-ID,OFFSET,LM' |
| Fetch the address associated with thread local storage specified |
| by THREAD-ID, OFFSET, and LM. |
| |
| THREAD-ID is the (big endian, hex encoded) thread id associated |
| with the thread for which to fetch the TLS address. |
| |
| 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. |
| |
| `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 THREADID' |
| Returns information on THREADID. Where: MODE is a hex encoded 32 |
| bit mode; THREADID is a hex encoded 64 bit thread ID. |
| |
| Don't use this packet; use the `qThreadExtraInfo' query instead |
| (see below). |
| |
| Reply: see `remote.c:remote_unpack_thread_info_response()'. |
| |
| `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.) |
| |
| `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. |
| |
| No values of GDBFEATURE (for the packet sent by GDB) are defined |
| yet. 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). 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--support for |
| unlimited length responses would be a GDBFEATURE example, if it |
| were not implied by the `qSupported' query. 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:spu:read' No `-' Yes |
| `qXfer:spu:write' No `-' Yes |
| `QPassSignals' No `-' Yes |
| |
| 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: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::). |
| |
| `QPassSignals' |
| The remote stub understands the `QPassSignals' packet (*note |
| QPassSignals::). |
| |
| |
| `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. |
| |
| `QTDP' |
| `QTFrame' |
| *Note Tracepoint Packets::. |
| |
| `qThreadExtraInfo,ID' |
| Obtain a printable string description of a thread's attributes from |
| the target OS. ID is a thread-id in big-endian hex. 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.) |
| |
| `QTStart' |
| `QTStop' |
| `QTinit' |
| `QTro' |
| `qTStatus' |
| *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: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::). |
| |
| 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: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. |
| |
| |
| ---------- 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: Register Packet Format, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol |
| |
| D.5 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: Register Packet Format, Up: Remote Protocol |
| |
| D.6 Tracepoint Packets |
| ====================== |
| |
| Here we describe the packets GDB uses to implement tracepoints (*note |
| Tracepoints::). |
| |
| `QTDP:N:ADDR:ENA:STEP:PASS[-]' |
| 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 the trailing `-' is present, further `QTDP' |
| packets will follow to specify this tracepoint's actions. |
| |
| Replies: |
| `OK' |
| The packet was understood and carried out. |
| |
| `' |
| 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. |
| |
| `' |
| The packet was not recognized. |
| |
| `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 (exclusive); 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. |
| |
| `QTStart' |
| Begin the tracepoint experiment. Begin collecting data from |
| tracepoint hits in the trace frame buffer. |
| |
| `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. |
| |
| `qTStatus' |
| Ask the stub if there is a trace experiment running right now. |
| |
| Replies: |
| `T0' |
| There is no trace experiment running. |
| |
| `T1' |
| There is a trace experiment running. |
| |
| |
| |
| File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol |
| |
| D.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: Examples, Prev: Host I/O Packets, Up: Remote Protocol |
| |
| D.8 Interrupts |
| ============== |
| |
| When a program on the remote target is running, GDB may attempt to |
| interrupt it by sending a `Ctrl-C' or a `BREAK', control of which is |
| specified via GDB's `remotebreak' setting (*note set remotebreak::). |
| |
| 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. |
| |
| `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. |
| |
| Stubs are not required to recognize these interrupt mechanisms and |
| the precise meaning associated with receipt of the interrupt is |
| implementation defined. If the stub is successful at interrupting the |
| running program, it is expected that it will send one of the Stop Reply |
| Packets (*note Stop Reply Packets::) to GDB as a result of successfully |
| stopping the program. Interrupts received while the program is stopped |
| will be discarded. |
| |
| |
| File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Interrupts, Up: Remote Protocol |
| |
| D.9 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 |
| |
| D.10 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 |
| |
| D.10.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: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension |
| |
| D.10.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 |
| |
| D.10.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 |
| |
| D.10.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 |
| |
| D.10.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 |
| |
| D.10.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 |
| |
| D.10.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 |
| |
| D.10.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 |
| |
| D.10.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 |
| |
| D.10.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 |
| |
| D.11 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 base addresses, which report |
| where the library was loaded in memory. The segment 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> |
| |
| 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)*> |
| <!ATTLIST library name CDATA #REQUIRED> |
| <!ELEMENT segment EMPTY> |
| <!ATTLIST segment address CDATA #REQUIRED> |
| |
| |
| File: gdb.info, Node: Memory Map Format, Prev: Library List Format, Up: Remote Protocol |
| |
| D.12 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: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top |
| |
| Appendix E 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. |
| * Tracing on Symmetrix:: Special info for implementation on EMC's |
| boxes. |
| * Rationale:: Why we did it this way. |
| |
| |
| File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions |
| |
| E.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 |
| |
| E.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. |
| |
| `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. |
| |
| `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. |
| |
| `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 |
| |
| E.3 Using Agent Expressions |
| =========================== |
| |
| Here is a sketch of a full non-stop debugging cycle, showing how agent |
| expressions fit into the process. |
| |
| * 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. Note |
| that, on some systems, the target operating system is completely |
| responsible for collecting the data; see *note Tracing on |
| Symmetrix::. |
| |
| * 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: Tracing on Symmetrix, Prev: Using Agent Expressions, Up: Agent Expressions |
| |
| E.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: Tracing on Symmetrix, Next: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions |
| |
| E.5 Tracing on Symmetrix |
| ======================== |
| |
| This section documents the API used by the GDB agent to collect data on |
| Symmetrix systems. |
| |
| Cygnus originally implemented these tracing features to help EMC |
| Corporation debug their Symmetrix high-availability disk drives. The |
| Symmetrix application code already includes substantial tracing |
| facilities; the GDB agent for the Symmetrix system uses those facilities |
| for its own data collection, via the API described here. |
| |
| -- Function: DTC_RESPONSE adbg_find_memory_in_frame (FRAME_DEF *FRAME, |
| char *ADDRESS, char **BUFFER, unsigned int *SIZE) |
| Search the trace frame FRAME for memory saved from ADDRESS. If |
| the memory is available, provide the address of the buffer holding |
| it; otherwise, provide the address of the next saved area. |
| |
| * If the memory at ADDRESS was saved in FRAME, set `*BUFFER' to |
| point to the buffer in which that memory was saved, set |
| `*SIZE' to the number of bytes from ADDRESS that are saved at |
| `*BUFFER', and return `OK_TARGET_RESPONSE'. (Clearly, in |
| this case, the function will always set `*SIZE' to a value |
| greater than zero.) |
| |
| * If FRAME does not record any memory at ADDRESS, set `*SIZE' |
| to the distance from ADDRESS to the start of the saved region |
| with the lowest address higher than ADDRESS. If there is no |
| memory saved from any higher address, set `*SIZE' to zero. |
| Return `NOT_FOUND_TARGET_RESPONSE'. |
| |
| These two possibilities allow the caller to either retrieve the |
| data, or walk the address space to the next saved area. |
| |
| This function allows the GDB agent to map the regions of memory |
| saved in a particular frame, and retrieve their contents efficiently. |
| |
| This function also provides a clean interface between the GDB agent |
| and the Symmetrix tracing structures, making it easier to adapt the GDB |
| agent to future versions of the Symmetrix system, and vice versa. This |
| function searches all data saved in FRAME, whether the data is there at |
| the request of a bytecode expression, or because it falls in one of the |
| format's memory ranges, or because it was saved from the top of the |
| stack. EMC can arbitrarily change and enhance the tracing mechanism, |
| but as long as this function works properly, all collected memory is |
| visible to GDB. |
| |
| The function itself is straightforward to implement. A single pass |
| over the trace frame's stack area, memory ranges, and expression blocks |
| can yield the address of the buffer (if the requested address was |
| saved), and also note the address of the next higher range of memory, |
| to be returned when the search fails. |
| |
| As an example, suppose the trace frame `f' has saved sixteen bytes |
| from address `0x8000' in a buffer at `0x1000', and thirty-two bytes |
| from address `0xc000' in a buffer at `0x1010'. Here are some sample |
| calls, and the effect each would have: |
| |
| `adbg_find_memory_in_frame (f, (char*) 0x8000, &buffer, &size)' |
| This would set `buffer' to `0x1000', set `size' to sixteen, and |
| return `OK_TARGET_RESPONSE', since `f' saves sixteen bytes from |
| `0x8000' at `0x1000'. |
| |
| `adbg_find_memory_in_frame (f, (char *) 0x8004, &buffer, &size)' |
| This would set `buffer' to `0x1004', set `size' to twelve, and |
| return `OK_TARGET_RESPONSE', since `f' saves the twelve bytes from |
| `0x8004' starting four bytes into the buffer at `0x1000'. This |
| shows that request addresses may fall in the middle of saved |
| areas; the function should return the address and size of the |
| remainder of the buffer. |
| |
| `adbg_find_memory_in_frame (f, (char *) 0x8100, &buffer, &size)' |
| This would set `size' to `0x3f00' and return |
| `NOT_FOUND_TARGET_RESPONSE', since there is no memory saved in `f' |
| from the address `0x8100', and the next memory available is at |
| `0x8100 + 0x3f00', or `0xc000'. This shows that request addresses |
| may fall outside of all saved memory ranges; the function should |
| indicate the next saved area, if any. |
| |
| `adbg_find_memory_in_frame (f, (char *) 0x7000, &buffer, &size)' |
| This would set `size' to `0x1000' and return |
| `NOT_FOUND_TARGET_RESPONSE', since the next saved memory is at |
| `0x7000 + 0x1000', or `0x8000'. |
| |
| `adbg_find_memory_in_frame (f, (char *) 0xf000, &buffer, &size)' |
| This would set `size' to zero, and return |
| `NOT_FOUND_TARGET_RESPONSE'. This shows how the function tells the |
| caller that no further memory ranges have been saved. |
| |
| |
| As another example, here is a function which will print out the |
| addresses of all memory saved in the trace frame `frame' on the |
| Symmetrix INLINES console: |
| void |
| print_frame_addresses (FRAME_DEF *frame) |
| { |
| char *addr; |
| char *buffer; |
| unsigned long size; |
| |
| addr = 0; |
| for (;;) |
| { |
| /* Either find out how much memory we have here, or discover |
| where the next saved region is. */ |
| if (adbg_find_memory_in_frame (frame, addr, &buffer, &size) |
| == OK_TARGET_RESPONSE) |
| printp ("saved %x to %x\n", addr, addr + size); |
| if (size == 0) |
| break; |
| addr += size; |
| } |
| } |
| |
| Note that there is not necessarily any connection between the order |
| in which the data is saved in the trace frame, and the order in which |
| `adbg_find_memory_in_frame' will return those memory ranges. The code |
| above will always print the saved memory regions in order of increasing |
| address, while the underlying frame structure might store the data in a |
| random order. |
| |
| [[This section should cover the rest of the Symmetrix functions the |
| stub relies upon, too.]] |
| |
| |
| File: gdb.info, Node: Rationale, Prev: Tracing on Symmetrix, Up: Agent Expressions |
| |
| E.6 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: Copying, Prev: Agent Expressions, Up: Top |
| |
| Appendix F 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 |
| |
| F.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 |
| |
| F.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. 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] |
| [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. |
| |
| F.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. |
| |
| F.2.2 Architecture |
| ------------------ |
| |
| An `<architecture>' element has this form: |
| |
| <architecture>ARCH</architecture> |
| |
| ARCH is an architecture name from the same selection accepted by |
| `set architecture' (*note Specifying a Debugging Target: Targets.). |
| |
| F.2.3 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::. |
| |
| F.2.4 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> |
| |
| F.2.5 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 |
| |
| F.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. |
| |
| |
| |
| File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions |
| |
| F.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:: |
| * MIPS Features:: |
| * M68K Features:: |
| * PowerPC Features:: |
| |
| |
| File: gdb.info, Node: ARM Features, Next: MIPS Features, Up: Standard Target Features |
| |
| F.4.1 ARM Features |
| ------------------ |
| |
| The `org.gnu.gdb.arm.core' feature is required for ARM targets. It |
| should contain registers `r0' through `r13', `sp', `lr', `pc', and |
| `cpsr'. |
| |
| 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. |
| |
| |
| File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: ARM Features, Up: Standard Target Features |
| |
| F.4.2 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 |
| |
| F.4.3 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 m86k 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 |
| |
| F.4.4 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.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: Copying, Next: GNU Free Documentation License, Prev: Target Descriptions, Up: Top |
| |
| Appendix G GNU GENERAL PUBLIC LICENSE |
| ************************************* |
| |
| Version 2, June 1991 |
| |
| Copyright (C) 1989, 1991 Free Software Foundation, Inc. |
| 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
| |
| Everyone is permitted to copy and distribute verbatim copies |
| of this license document, but changing it is not allowed. |
| |
| Preamble |
| ======== |
| |
| The licenses for most software are designed to take away your freedom |
| to share and change it. By contrast, the GNU General Public License is |
| intended to guarantee your freedom to share and change free |
| software--to make sure the software is free for all its users. This |
| General Public License applies to most of the Free Software |
| Foundation's software and to any other program whose authors commit to |
| using it. (Some other Free Software Foundation software is covered by |
| the GNU Library General Public License instead.) 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 |
| this service 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 make restrictions that forbid |
| anyone to deny you these rights or to ask you to surrender the rights. |
| These restrictions translate to certain responsibilities for you if you |
| distribute copies of the software, or if you modify it. |
| |
| For example, if you distribute copies of such a program, whether |
| gratis or for a fee, you must give the recipients all the rights that |
| you have. 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. |
| |
| We protect your rights with two steps: (1) copyright the software, |
| and (2) offer you this license which gives you legal permission to copy, |
| distribute and/or modify the software. |
| |
| Also, for each author's protection and ours, we want to make certain |
| that everyone understands that there is no warranty for this free |
| software. If the software is modified by someone else and passed on, we |
| want its recipients to know that what they have is not the original, so |
| that any problems introduced by others will not reflect on the original |
| authors' reputations. |
| |
| Finally, any free program is threatened constantly by software |
| patents. We wish to avoid the danger that redistributors of a free |
| program will individually obtain patent licenses, in effect making the |
| program proprietary. To prevent this, we have made it clear that any |
| patent must be licensed for everyone's free use or not licensed at all. |
| |
| The precise terms and conditions for copying, distribution and |
| modification follow. |
| |
| TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION |
| 0. This License applies to any program or other work which contains a |
| notice placed by the copyright holder saying it may be distributed |
| under the terms of this General Public License. The "Program", |
| below, refers to any such program or work, and a "work based on |
| the Program" means either the Program or any derivative work under |
| copyright law: that is to say, a work containing the Program or a |
| portion of it, either verbatim or with modifications and/or |
| translated into another language. (Hereinafter, translation is |
| included without limitation in the term "modification".) Each |
| licensee is addressed as "you". |
| |
| Activities other than copying, distribution and modification are |
| not covered by this License; they are outside its scope. The act |
| of running the Program is not restricted, and the output from the |
| Program is covered only if its contents constitute a work based on |
| the Program (independent of having been made by running the |
| Program). Whether that is true depends on what the Program does. |
| |
| 1. You may copy and distribute 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 and disclaimer of warranty; keep intact all the |
| notices that refer to this License and to the absence of any |
| warranty; and give any other recipients of the Program a copy of |
| this License along with the Program. |
| |
| You may charge a fee for the physical act of transferring a copy, |
| and you may at your option offer warranty protection in exchange |
| for a fee. |
| |
| 2. You may modify your copy or copies of the Program or any portion |
| of it, thus forming a work based on the Program, and copy and |
| distribute such modifications or work under the terms of Section 1 |
| above, provided that you also meet all of these conditions: |
| |
| a. You must cause the modified files to carry prominent notices |
| stating that you changed the files and the date of any change. |
| |
| b. You must cause any work that you distribute or publish, that |
| in whole or in part contains or is derived from the Program |
| or any part thereof, to be licensed as a whole at no charge |
| to all third parties under the terms of this License. |
| |
| c. If the modified program normally reads commands interactively |
| when run, you must cause it, when started running for such |
| interactive use in the most ordinary way, to print or display |
| an announcement including an appropriate copyright notice and |
| a notice that there is no warranty (or else, saying that you |
| provide a warranty) and that users may redistribute the |
| program under these conditions, and telling the user how to |
| view a copy of this License. (Exception: if the Program |
| itself is interactive but does not normally print such an |
| announcement, your work based on the Program is not required |
| to print an announcement.) |
| |
| These requirements apply to the modified work as a whole. If |
| identifiable sections of that work are not derived from the |
| Program, and can be reasonably considered independent and separate |
| works in themselves, then this License, and its terms, do not |
| apply to those sections when you distribute them as separate |
| works. But when you distribute the same sections as part of a |
| whole which is a work based on the Program, the distribution of |
| the whole must be on the terms of this License, whose permissions |
| for other licensees extend to the entire whole, and thus to each |
| and every part regardless of who wrote it. |
| |
| Thus, it is not the intent of this section to claim rights or |
| contest your rights to work written entirely by you; rather, the |
| intent is to exercise the right to control the distribution of |
| derivative or collective works based on the Program. |
| |
| In addition, mere aggregation of another work not based on the |
| Program with the Program (or with a work based on the Program) on |
| a volume of a storage or distribution medium does not bring the |
| other work under the scope of this License. |
| |
| 3. You may copy and distribute the Program (or a work based on it, |
| under Section 2) in object code or executable form under the terms |
| of Sections 1 and 2 above provided that you also do one of the |
| following: |
| |
| a. Accompany it with the complete corresponding machine-readable |
| source code, which must be distributed under the terms of |
| Sections 1 and 2 above on a medium customarily used for |
| software interchange; or, |
| |
| b. Accompany it with a written offer, valid for at least three |
| years, to give any third party, for a charge no more than your |
| cost of physically performing source distribution, a complete |
| machine-readable copy of the corresponding source code, to be |
| distributed under the terms of Sections 1 and 2 above on a |
| medium customarily used for software interchange; or, |
| |
| c. Accompany it with the information you received as to the offer |
| to distribute corresponding source code. (This alternative is |
| allowed only for noncommercial distribution and only if you |
| received the program in object code or executable form with |
| such an offer, in accord with Subsection b above.) |
| |
| The source code for a work means the preferred form of the work for |
| making modifications to it. For an executable work, complete |
| source code means all the source code for all modules it contains, |
| plus any associated interface definition files, plus the scripts |
| used to control compilation and installation of the executable. |
| However, as a special exception, the source code distributed need |
| not include anything that is normally distributed (in either |
| source or binary form) with the major components (compiler, |
| kernel, and so on) of the operating system on which the executable |
| runs, unless that component itself accompanies the executable. |
| |
| If distribution of executable or object code is made by offering |
| access to copy from a designated place, then offering equivalent |
| access to copy the source code from the same place counts as |
| distribution of the source code, even though third parties are not |
| compelled to copy the source along with the object code. |
| |
| 4. You may not copy, modify, sublicense, or distribute the Program |
| except as expressly provided under this License. Any attempt |
| otherwise to copy, modify, sublicense or distribute the Program is |
| void, and will automatically terminate your rights under this |
| License. However, parties who have received copies, or rights, |
| from you under this License will not have their licenses |
| terminated so long as such parties remain in full compliance. |
| |
| 5. You are not required to accept this License, since you have not |
| signed it. However, nothing else grants you permission to modify |
| or distribute the Program or its derivative works. These actions |
| are prohibited by law if you do not accept this License. |
| Therefore, by modifying or distributing the Program (or any work |
| based on the Program), you indicate your acceptance of this |
| License to do so, and all its terms and conditions for copying, |
| distributing or modifying the Program or works based on it. |
| |
| 6. Each time you redistribute the Program (or any work based on the |
| Program), the recipient automatically receives a license from the |
| original licensor to copy, distribute or modify the Program |
| subject to these terms and conditions. You may not impose any |
| further restrictions on the recipients' exercise of the rights |
| granted herein. You are not responsible for enforcing compliance |
| by third parties to this License. |
| |
| 7. If, as a consequence of a court judgment or allegation of patent |
| infringement or for any other reason (not limited to patent |
| issues), 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 distribute so as to satisfy simultaneously |
| your obligations under this License and any other pertinent |
| obligations, then as a consequence you may not distribute the |
| Program at all. For example, if a patent license would not permit |
| royalty-free redistribution of the Program by all those who |
| receive copies directly or indirectly through you, then the only |
| way you could satisfy both it and this License would be to refrain |
| entirely from distribution of the Program. |
| |
| If any portion of this section is held invalid or unenforceable |
| under any particular circumstance, the balance of the section is |
| intended to apply and the section as a whole is intended to apply |
| in other circumstances. |
| |
| It is not the purpose of this section to induce you to infringe any |
| patents or other property right claims or to contest validity of |
| any such claims; this section has the sole purpose of protecting |
| the integrity of the free software distribution system, which is |
| implemented by public license practices. Many people have made |
| generous contributions to the wide range of software distributed |
| through that system in reliance on consistent application of that |
| system; it is up to the author/donor to decide if he or she is |
| willing to distribute software through any other system and a |
| licensee cannot impose that choice. |
| |
| This section is intended to make thoroughly clear what is believed |
| to be a consequence of the rest of this License. |
| |
| 8. If the distribution and/or use of the Program is restricted in |
| certain countries either by patents or by copyrighted interfaces, |
| the original copyright holder who places the Program under this |
| License may add an explicit geographical distribution limitation |
| excluding those countries, so that distribution is permitted only |
| in or among countries not thus excluded. In such case, this |
| License incorporates the limitation as if written in the body of |
| this License. |
| |
| 9. The Free Software Foundation may publish revised and/or new |
| versions of the 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 a version number of this License which applies |
| to it and "any later version", you have the option of following |
| the terms and conditions either of that version or of any later |
| version published by the Free Software Foundation. If the Program |
| does not specify a version number of this License, you may choose |
| any version ever published by the Free Software Foundation. |
| |
| 10. If you wish to incorporate parts of the Program into other free |
| programs whose distribution conditions are different, write to the |
| author to ask for permission. For software which is copyrighted |
| by the Free Software Foundation, write to the Free Software |
| Foundation; we sometimes make exceptions for this. Our decision |
| will be guided by the two goals of preserving the free status of |
| all derivatives of our free software and of promoting the sharing |
| and reuse of software generally. |
| |
| NO WARRANTY |
| 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, 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. |
| |
| 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN |
| WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY |
| MODIFY AND/OR REDISTRIBUTE 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. |
| |
| 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 |
| convey 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 2 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, write to the Free Software |
| Foundation, Inc., 51 Franklin Street, Fifth Floor, |
| Boston, MA 02110-1301, USA. |
| |
| Also add information on how to contact you by electronic and paper |
| mail. |
| |
| If the program is interactive, make it output a short notice like |
| this when it starts in an interactive mode: |
| |
| Gnomovision version 69, Copyright (C) YEAR NAME OF AUTHOR |
| Gnomovision 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, the |
| commands you use may be called something other than `show w' and `show |
| c'; they could even be mouse-clicks or menu items--whatever suits your |
| program. |
| |
| You should also get your employer (if you work as a programmer) or |
| your school, if any, to sign a "copyright disclaimer" for the program, |
| if necessary. Here is a sample; alter the names: |
| |
| Yoyodyne, Inc., hereby disclaims all copyright interest in the program |
| `Gnomovision' (which makes passes at compilers) written by James Hacker. |
| |
| SIGNATURE OF TY COON, 1 April 1989 |
| Ty Coon, President of Vice |
| |
| This 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 Library General Public License instead of this License. |
| |
| |
| File: gdb.info, Node: GNU Free Documentation License, Next: Index, Prev: Copying, Up: Top |
| |
| Appendix H GNU Free Documentation License |
| ***************************************** |
| |
| Version 1.2, November 2002 |
| |
| Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. |
| 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
| |
| 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. |
| |
| 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 for under this License. Any other |
| attempt to copy, modify, sublicense or distribute the Document is |
| void, and will automatically terminate your rights under this |
| License. However, parties who have received copies, or rights, |
| from you under this License will not have their licenses |
| terminated so long as such parties remain in full compliance. |
| |
| 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. |
| |
| H.1 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.2 |
| 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 |
| ***** |
| |
| [index] |
| * Menu: |
| |
| * ! packet: Packets. (line 26) |
| * "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 112) |
| * $_ and info line: Machine Code. (line 29) |
| * $_, $__, and value history: Memory. (line 91) |
| * $_, convenience variable: Convenience Vars. (line 64) |
| * $__, convenience variable: Convenience Vars. (line 73) |
| * $_exitcode, convenience variable: Convenience Vars. (line 79) |
| * $bpnum, convenience variable: Set Breaks. (line 6) |
| * $cdir, convenience variable: Source Path. (line 99) |
| * $cwd, convenience variable: Source Path. (line 99) |
| * $tpnum: Create and Delete Tracepoints. |
| (line 31) |
| * $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 101) |
| * --args: Mode Options. (line 114) |
| * --batch: Mode Options. (line 23) |
| * --batch-silent: Mode Options. (line 39) |
| * --baud: Mode Options. (line 120) |
| * --cd: Mode Options. (line 80) |
| * --command: File Options. (line 51) |
| * --core: File Options. (line 43) |
| * --directory: File Options. (line 66) |
| * --epoch: Mode Options. (line 96) |
| * --eval-command: File Options. (line 56) |
| * --exec: File Options. (line 35) |
| * --fullname: Mode Options. (line 85) |
| * --interpreter: Mode Options. (line 141) |
| * --nowindows: Mode Options. (line 70) |
| * --nx: Mode Options. (line 11) |
| * --pid: File Options. (line 47) |
| * --quiet: Mode Options. (line 19) |
| * --readnow: File Options. (line 70) |
| * --return-child-result: Mode Options. (line 51) |
| * --se: File Options. (line 39) |
| * --silent: Mode Options. (line 19) |
| * --statistics: Mode Options. (line 158) |
| * --symbols: File Options. (line 31) |
| * --tty: Mode Options. (line 129) |
| * --tui: Mode Options. (line 132) |
| * --version: Mode Options. (line 162) |
| * --windows: Mode Options. (line 76) |
| * --with-sysroot: Files. (line 381) |
| * --write: Mode Options. (line 153) |
| * -b: Mode Options. (line 120) |
| * -break-after: GDB/MI Breakpoint Commands. |
| (line 11) |
| * -break-condition: GDB/MI Breakpoint Commands. |
| (line 54) |
| * -break-delete: GDB/MI Breakpoint Commands. |
| (line 91) |
| * -break-disable: GDB/MI Breakpoint Commands. |
| (line 125) |
| * -break-enable: GDB/MI Breakpoint Commands. |
| (line 161) |
| * -break-info: GDB/MI Breakpoint Commands. |
| (line 196) |
| * -break-insert: GDB/MI Breakpoint Commands. |
| (line 216) |
| * -break-list: GDB/MI Breakpoint Commands. |
| (line 314) |
| * -break-watch: GDB/MI Breakpoint Commands. |
| (line 389) |
| * -c: File Options. (line 43) |
| * -d: File Options. (line 66) |
| * -data-disassemble: GDB/MI Data Manipulation. |
| (line 12) |
| * -data-evaluate-expression: GDB/MI Data Manipulation. |
| (line 140) |
| * -data-list-changed-registers: GDB/MI Data Manipulation. |
| (line 178) |
| * -data-list-register-names: GDB/MI Data Manipulation. |
| (line 213) |
| * -data-list-register-values: GDB/MI Data Manipulation. |
| (line 253) |
| * -data-read-memory: GDB/MI Data Manipulation. |
| (line 343) |
| * -e: File Options. (line 35) |
| * -enable-timings: GDB/MI Miscellaneous Commands. |
| (line 234) |
| * -environment-cd: GDB/MI Program Context. |
| (line 50) |
| * -environment-directory: GDB/MI Program Context. |
| (line 73) |
| * -environment-path: GDB/MI Program Context. |
| (line 117) |
| * -environment-pwd: GDB/MI Program Context. |
| (line 158) |
| * -ex: File Options. (line 56) |
| * -exec-abort: GDB/MI Miscellaneous Commands. |
| (line 31) |
| * -exec-arguments: GDB/MI Program Context. |
| (line 9) |
| * -exec-continue: GDB/MI Program Execution. |
| (line 13) |
| * -exec-finish: GDB/MI Program Execution. |
| (line 40) |
| * -exec-interrupt: GDB/MI Program Execution. |
| (line 81) |
| * -exec-next: GDB/MI Program Execution. |
| (line 121) |
| * -exec-next-instruction: GDB/MI Program Execution. |
| (line 146) |
| * -exec-return: GDB/MI Program Execution. |
| (line 176) |
| * -exec-run: GDB/MI Program Execution. |
| (line 219) |
| * -exec-show-arguments: GDB/MI Program Context. |
| (line 30) |
| * -exec-step: GDB/MI Program Execution. |
| (line 279) |
| * -exec-step-instruction: GDB/MI Program Execution. |
| (line 319) |
| * -exec-until: GDB/MI Program Execution. |
| (line 358) |
| * -f: Mode Options. (line 85) |
| * -file-exec-and-symbols: GDB/MI File Commands. |
| (line 12) |
| * -file-exec-file: GDB/MI File Commands. |
| (line 40) |
| * -file-list-exec-sections: GDB/MI File Commands. |
| (line 67) |
| * -file-list-exec-source-file: GDB/MI File Commands. |
| (line 88) |
| * -file-list-exec-source-files: GDB/MI File Commands. |
| (line 114) |
| * -file-list-shared-libraries: GDB/MI File Commands. |
| (line 144) |
| * -file-list-symbol-files: GDB/MI File Commands. |
| (line 164) |
| * -file-symbol-file: GDB/MI File Commands. |
| (line 184) |
| * -gdb-exit: GDB/MI Miscellaneous Commands. |
| (line 9) |
| * -gdb-set: GDB/MI Miscellaneous Commands. |
| (line 51) |
| * -gdb-show: GDB/MI Miscellaneous Commands. |
| (line 74) |
| * -gdb-version: GDB/MI Miscellaneous Commands. |
| (line 97) |
| * -inferior-tty-set: GDB/MI Miscellaneous Commands. |
| (line 185) |
| * -inferior-tty-show: GDB/MI Miscellaneous Commands. |
| (line 208) |
| * -interpreter-exec: GDB/MI Miscellaneous Commands. |
| (line 160) |
| * -l: Mode Options. (line 124) |
| * -list-features: GDB/MI Miscellaneous Commands. |
| (line 131) |
| * -n: Mode Options. (line 11) |
| * -nw: Mode Options. (line 70) |
| * -p: File Options. (line 47) |
| * -q: Mode Options. (line 19) |
| * -r: File Options. (line 70) |
| * -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 157) |
| * -stack-list-locals: GDB/MI Stack Manipulation. |
| (line 253) |
| * -stack-select-frame: GDB/MI Stack Manipulation. |
| (line 290) |
| * -symbol-info-address: GDB/MI Symbol Query. (line 9) |
| * -symbol-info-file: GDB/MI Symbol Query. (line 29) |
| * -symbol-info-function: GDB/MI Symbol Query. (line 49) |
| * -symbol-info-line: GDB/MI Symbol Query. (line 69) |
| * -symbol-info-symbol: GDB/MI Symbol Query. (line 90) |
| * -symbol-list-functions: GDB/MI Symbol Query. (line 110) |
| * -symbol-list-lines: GDB/MI Symbol Query. (line 130) |
| * -symbol-list-types: GDB/MI Symbol Query. (line 155) |
| * -symbol-list-variables: GDB/MI Symbol Query. (line 176) |
| * -symbol-locate: GDB/MI Symbol Query. (line 196) |
| * -symbol-type: GDB/MI Symbol Query. (line 214) |
| * -t: Mode Options. (line 129) |
| * -target-attach: GDB/MI Target Manipulation. |
| (line 9) |
| * -target-compare-sections: GDB/MI Target Manipulation. |
| (line 29) |
| * -target-detach: GDB/MI Target Manipulation. |
| (line 50) |
| * -target-disconnect: GDB/MI Target Manipulation. |
| (line 74) |
| * -target-download: GDB/MI Target Manipulation. |
| (line 98) |
| * -target-exec-status: GDB/MI Target Manipulation. |
| (line 201) |
| * -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-list-available-targets: GDB/MI Target Manipulation. |
| (line 222) |
| * -target-list-current-targets: GDB/MI Target Manipulation. |
| (line 242) |
| * -target-list-parameters: GDB/MI Target Manipulation. |
| (line 263) |
| * -target-select: GDB/MI Target Manipulation. |
| (line 281) |
| * -thread-info: GDB/MI Thread Commands. |
| (line 9) |
| * -thread-list-all-threads: GDB/MI Thread Commands. |
| (line 27) |
| * -thread-list-ids: GDB/MI Thread Commands. |
| (line 45) |
| * -thread-select: GDB/MI Thread Commands. |
| (line 79) |
| * -var-assign: GDB/MI Variable Objects. |
| (line 303) |
| * -var-create: GDB/MI Variable Objects. |
| (line 85) |
| * -var-delete: GDB/MI Variable Objects. |
| (line 126) |
| * -var-evaluate-expression: GDB/MI Variable Objects. |
| (line 286) |
| * -var-info-expression: GDB/MI Variable Objects. |
| (line 227) |
| * -var-info-num-children: GDB/MI Variable Objects. |
| (line 175) |
| * -var-info-path-expression: GDB/MI Variable Objects. |
| (line 251) |
| * -var-info-type: GDB/MI Variable Objects. |
| (line 214) |
| * -var-list-children: GDB/MI Variable Objects. |
| (line 187) |
| * -var-set-format: GDB/MI Variable Objects. |
| (line 139) |
| * -var-set-frozen: GDB/MI Variable Objects. |
| (line 380) |
| * -var-show-attributes: GDB/MI Variable Objects. |
| (line 272) |
| * -var-show-format: GDB/MI Variable Objects. |
| (line 162) |
| * -var-update: GDB/MI Variable Objects. |
| (line 327) |
| * -w: Mode Options. (line 76) |
| * -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) |
| * .gdbinit: Startup. (line 37) |
| * .gnu_debuglink sections: Separate Debug Files. |
| (line 77) |
| * .note.gnu.build-id sections: Separate Debug Files. |
| (line 95) |
| * .o files, reading symbols from: Files. (line 132) |
| * /proc: SVR4 Process Information. |
| (line 6) |
| * <architecture>: Target Description Format. |
| (line 70) |
| * <feature>: Target Description Format. |
| (line 80) |
| * <reg>: Target Description Format. |
| (line 127) |
| * <union>: Target Description Format. |
| (line 114) |
| * <vector>: Target Description Format. |
| (line 107) |
| * ? packet: Packets. (line 35) |
| * @, referencing memory as an array: Arrays. (line 6) |
| * ^connected: GDB/MI Result Records. |
| (line 18) |
| * ^done: GDB/MI Result Records. |
| (line 9) |
| * ^error: GDB/MI Result Records. |
| (line 21) |
| * ^exit: GDB/MI Result Records. |
| (line 25) |
| * ^running: GDB/MI Result Records. |
| (line 14) |
| * _NSPrintForDebugger, and printing Objective-C objects: The Print Command with Objective-C. |
| (line 11) |
| * A packet: Packets. (line 41) |
| * 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: Overview. (line 33) |
| * 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, deviations from: Additions to Ada. (line 6) |
| * Ada, omissions from: Omissions from Ada. (line 6) |
| * Ada, problems: Ada Glitches. (line 6) |
| * adbg_find_memory_in_frame: Tracing on Symmetrix. |
| (line 17) |
| * add new commands for external monitor: Connecting. (line 104) |
| * add-shared-symbol-files: Files. (line 172) |
| * add-symbol-file: Files. (line 113) |
| * add-symbol-file-from-memory: Files. (line 162) |
| * address of a symbol: Symbols. (line 44) |
| * address size for remote targets: Remote Configuration. |
| (line 12) |
| * ADP (Angel Debugger Protocol) logging: ARM. (line 70) |
| * advance LOCATION: Continuing and Stepping. |
| (line 180) |
| * aggregates (Ada): Omissions from Ada. (line 44) |
| * AIX threads: Debugging Output. (line 28) |
| * alignment of remote memory accesses: Packets. (line 172) |
| * Alpha stack: MIPS. (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 146) |
| * 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) |
| * arrays: Arrays. (line 6) |
| * arrays in expressions: Expressions. (line 14) |
| * artificial array: Arrays. (line 6) |
| * ASCII character set: Character Sets. (line 65) |
| * assembly instructions: Machine Code. (line 35) |
| * assf: Files. (line 172) |
| * assignment: Assignment. (line 6) |
| * async output in GDB/MI: GDB/MI Output Syntax. |
| (line 96) |
| * AT&T disassembly flavor: Machine Code. (line 67) |
| * attach: Attach. (line 6) |
| * attach to a program by name: Server. (line 79) |
| * automatic display: Auto Display. (line 6) |
| * automatic hardware breakpoints: Set Breaks. (line 269) |
| * automatic overlay debugging: Automatic Overlay Debugging. |
| (line 6) |
| * automatic thread selection: Threads. (line 169) |
| * auxiliary vector: OS Information. (line 21) |
| * AVR: AVR. (line 6) |
| * awatch: Set Watchpoints. (line 51) |
| * b (break): Set Breaks. (line 6) |
| * B packet: Packets. (line 68) |
| * b packet: Packets. (line 53) |
| * backtrace: Backtrace. (line 11) |
| * backtrace beyond main function: Backtrace. (line 87) |
| * backtrace limit: Backtrace. (line 123) |
| * 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) |
| * baud rate for remote targets: Remote Configuration. |
| (line 21) |
| * bcache statistics: Maintenance Commands. |
| (line 166) |
| * 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) |
| * bookmark: Checkpoint/Restart. (line 6) |
| * break: Set Breaks. (line 6) |
| * break ... thread THREADNO: Thread Stops. (line 10) |
| * break in overloaded functions: Debugging C Plus Plus. |
| (line 9) |
| * break on fork/exec: Set Catchpoints. (line 33) |
| * break on load/unload of shared library: Set Catchpoints. (line 46) |
| * BREAK signal instead of Ctrl-C: Remote Configuration. |
| (line 29) |
| * break, and Objective-C: Method Names in Commands. |
| (line 9) |
| * 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: Breakpoints. (line 6) |
| * breakpoints and threads: Thread Stops. (line 10) |
| * breakpoints in functions matching a regexp: Set Breaks. (line 87) |
| * breakpoints in overlays: Overlay Commands. (line 93) |
| * breakpoints-invalid annotation: Invalidation. (line 13) |
| * 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 95) |
| * 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 80) |
| * c packet: Packets. (line 74) |
| * C++: C. (line 10) |
| * C++ compilers: C Plus Plus Expressions. |
| (line 8) |
| * C++ exception handling: Debugging C Plus Plus. |
| (line 19) |
| * C++ overload debugging info: Debugging Output. (line 80) |
| * C++ scope resolution: Variables. (line 54) |
| * C++ symbol decoding style: Print Settings. (line 294) |
| * C++ symbol display: Debugging C Plus Plus. |
| (line 28) |
| * 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 12) |
| * C-x a: TUI Keys. (line 11) |
| * 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 26) |
| * 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) |
| * casts, in expressions: Expressions. (line 27) |
| * casts, to view memory: Expressions. (line 42) |
| * 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 99) |
| * 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) |
| * choosing target byte order: Byte Order. (line 6) |
| * 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) |
| * close, file-i/o system call: close. (line 6) |
| * closest symbol and offset for an address: Symbols. (line 54) |
| * code address and its source line: Machine Code. (line 24) |
| * collect (tracepoints): Tracepoint Actions. (line 45) |
| * 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 65) |
| * command tracing: Messages/Warnings. (line 60) |
| * commands: Break Commands. (line 11) |
| * commands annotation: Prompting. (line 27) |
| * commands for C++: Debugging C Plus Plus. |
| (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 111) |
| * compatibility, GDB/MI and CLI: GDB/MI Compatibility with CLI. |
| (line 6) |
| * compilation directory: Source Path. (line 99) |
| * compiling, on Sparclet: Sparclet. (line 16) |
| * complete: Help. (line 76) |
| * complete (<TAB>): Commands For Completion. |
| (line 6) |
| * completion: Completion. (line 6) |
| * completion of quoted strings: Completion. (line 57) |
| * completion-query-items: Readline Init File Syntax. |
| (line 57) |
| * condition: Conditions. (line 45) |
| * conditional breakpoints: Conditions. (line 6) |
| * configuring GDB: Running Configure. (line 6) |
| * confirmation: Messages/Warnings. (line 50) |
| * 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 104) |
| * constants, in file-i/o protocol: Constants. (line 6) |
| * continue: Continuing and Stepping. |
| (line 15) |
| * continuing: Continuing and Stepping. |
| (line 6) |
| * continuing threads: Thread Stops. (line 70) |
| * control C, and remote debugging: Bootstrapping. (line 25) |
| * controlling terminal: Input/Output. (line 23) |
| * convenience variables: Convenience Vars. (line 6) |
| * convenience variables for tracepoints: Tracepoint Variables. |
| (line 6) |
| * 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 of memory block, remote request: General Query Packets. |
| (line 51) |
| * CRIS: CRIS. (line 6) |
| * CRIS mode: CRIS. (line 26) |
| * CRIS version: CRIS. (line 10) |
| * 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 directory: Source Path. (line 99) |
| * current stack frame: Frames. (line 45) |
| * current thread: Threads. (line 41) |
| * current thread, remote request: General Query Packets. |
| (line 41) |
| * cwd: Source Path. (line 99) |
| * Cygwin DLL, debugging: Cygwin Native. (line 30) |
| * Cygwin-specific commands: Cygwin Native. (line 6) |
| * d (delete): Delete Breaks. (line 41) |
| * d (SingleKey TUI key): TUI Single Key Mode. (line 13) |
| * D packet: Packets. (line 92) |
| * d packet: Packets. (line 86) |
| * data breakpoints: Breakpoints. (line 20) |
| * data manipulation, in GDB/MI: GDB/MI Data Manipulation. |
| (line 6) |
| * dead names, GNU Hurd: Hurd Native. (line 85) |
| * debug formats and C++: C Plus Plus Expressions. |
| (line 8) |
| * debug link sections: Separate Debug Files. |
| (line 77) |
| * debug remote protocol: Debugging Output. (line 86) |
| * 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 multiple processes: Processes. (line 52) |
| * debugging multithreaded programs (on HP-UX): Threads. (line 85) |
| * debugging optimized code: Compilation. (line 26) |
| * debugging stub, example: Remote Stub. (line 6) |
| * debugging target: Targets. (line 6) |
| * debugging the Cygwin DLL: Cygwin Native. (line 30) |
| * decimal floating point format: Decimal Floating Point. |
| (line 6) |
| * default system root: Files. (line 381) |
| * define: Define. (line 37) |
| * defining macros interactively: Macros. (line 54) |
| * definition, showing a macro's: Macros. (line 50) |
| * 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 fork FORK-ID: Processes. (line 105) |
| * delete mem: Memory Region Attributes. |
| (line 34) |
| * delete tracepoint: Create and Delete Tracepoints. |
| (line 34) |
| * 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 275) |
| * deprecated commands: Maintenance Commands. |
| (line 60) |
| * derived type of an object, printing: Print Settings. (line 327) |
| * descriptor tables display: DJGPP Native. (line 24) |
| * detach: Attach. (line 36) |
| * detach (remote): Connecting. (line 90) |
| * detach fork FORK-ID: Processes. (line 100) |
| * detach from task, GNU Hurd: Hurd Native. (line 60) |
| * detach from thread, GNU Hurd: Hurd Native. (line 110) |
| * 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 99) |
| * directory, current: Source Path. (line 99) |
| * dis (disable): Disabling. (line 38) |
| * disable: Disabling. (line 38) |
| * disable display: Auto Display. (line 52) |
| * disable mem: Memory Region Attributes. |
| (line 38) |
| * disable tracepoint: Enable and Disable Tracepoints. |
| (line 6) |
| * disable-completion: Readline Init File Syntax. |
| (line 73) |
| * disassemble: Machine Code. (line 35) |
| * disconnect: Connecting. (line 97) |
| * display: Auto Display. (line 23) |
| * display command history: Command History. (line 78) |
| * display derived types: Print Settings. (line 327) |
| * display disabled out of scope: Auto Display. (line 74) |
| * 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 86) |
| * DJGPP debugging: DJGPP Native. (line 6) |
| * dll-symbols: Cygwin Native. (line 26) |
| * 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 46) |
| * documentation: Formatting Documentation. |
| (line 22) |
| * don't repeat command: Define. (line 58) |
| * dont-repeat: Define. (line 58) |
| * DOS serial data link, remote debugging: DJGPP Native. (line 121) |
| * DOS serial port status: DJGPP Native. (line 142) |
| * Down: TUI Keys. (line 56) |
| * down: Selection. (line 40) |
| * 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) |
| * DWARF 2 compilation units cache: Maintenance Commands. |
| (line 202) |
| * DWARF-2 CFI and CRIS: CRIS. (line 18) |
| * dynamic linking: Files. (line 113) |
| * e (edit): Edit. (line 6) |
| * EBCDIC character set: Character Sets. (line 74) |
| * 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 220) |
| * elaboration phase: Starting. (line 82) |
| * else: Command Files. (line 56) |
| * Emacs: Emacs. (line 6) |
| * empty response, for unsupported packets: Overview. (line 90) |
| * enable: Disabling. (line 45) |
| * enable display: Auto Display. (line 57) |
| * enable mem: Memory Region Attributes. |
| (line 42) |
| * enable tracepoint: Enable and Disable Tracepoints. |
| (line 12) |
| * enable-keypad: Readline Init File Syntax. |
| (line 84) |
| * enable/disable a breakpoint: Disabling. (line 6) |
| * end (breakpoint commands): Break Commands. (line 11) |
| * end (if/else/while commands): Command Files. (line 85) |
| * end (user-defined commands): Define. (line 46) |
| * 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) |
| * event debugging info: Debugging Output. (line 35) |
| * 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) |
| * 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 commands from a file: Command Files. (line 14) |
| * execute remote command, remote request: General Query Packets. |
| (line 203) |
| * exited annotation: Annotations for Running. |
| (line 18) |
| * exiting GDB: Quitting GDB. (line 6) |
| * expand macro once: Macros. (line 41) |
| * expand-tilde: Readline Init File Syntax. |
| (line 89) |
| * expanding preprocessor macros: Macros. (line 32) |
| * expression debugging info: Debugging Output. (line 42) |
| * 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 104) |
| * f (frame): Selection. (line 11) |
| * f (SingleKey TUI key): TUI Single Key Mode. (line 16) |
| * F packet: Packets. (line 103) |
| * F reply packet: The F Reply Packet. (line 6) |
| * F request packet: The F Request Packet. |
| (line 6) |
| * fatal signal: Bug Criteria. (line 9) |
| * fatal signals: Signals. (line 15) |
| * FDL, GNU Free Documentation License: GNU Free Documentation License. |
| (line 6) |
| * features of the remote protocol: General Query Packets. |
| (line 228) |
| * fg (resume foreground execution): Continuing and Stepping. |
| (line 15) |
| * file: Files. (line 16) |
| * 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) |
| * find downloadable SREC files (M32R): M32R/D. (line 15) |
| * find trace snapshot: tfind. (line 6) |
| * finish: Continuing and Stepping. |
| (line 110) |
| * 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_i_cache: Bootstrapping. (line 60) |
| * flushregs: Maintenance Commands. |
| (line 158) |
| * focus: TUI Commands. (line 34) |
| * focus of debugging: Threads. (line 41) |
| * foo: Symbol Errors. (line 50) |
| * fork FORK-ID: Processes. (line 85) |
| * fork, debugging programs which call: Processes. (line 6) |
| * format options: Print Settings. (line 6) |
| * formatted output: Output Formats. (line 6) |
| * Fortran: Summary. (line 35) |
| * 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 104) |
| * frame debugging info: Debugging Output. (line 50) |
| * 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) |
| * frameless execution: Frames. (line 34) |
| * 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) |
| * Fujitsu: Remote Stub. (line 69) |
| * full symbol tables, listing GDB's internal: Symbols. (line 270) |
| * function call arguments, optimized out: Backtrace. (line 65) |
| * function entry/exit, wrong values of variables: Variables. (line 58) |
| * functions without line info, and stepping: Continuing and Stepping. |
| (line 93) |
| * G packet: Packets. (line 124) |
| * g packet: Packets. (line 108) |
| * 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 reference card: Formatting Documentation. |
| (line 6) |
| * GDB startup: Startup. (line 6) |
| * GDB version number: Help. (line 126) |
| * gdb.ini: Startup. (line 37) |
| * GDB/MI development: GDB/MI Development and Front Ends. |
| (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, out-of-band records: GDB/MI Out-of-band Records. |
| (line 6) |
| * 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) |
| * GDT: DJGPP Native. (line 24) |
| * generate-core-file: Core File Generation. |
| (line 18) |
| * get thread-local storage address, remote request: General Query Packets. |
| (line 87) |
| * 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/Linux LWP debug messages: Debugging Output. (line 66) |
| * gnu_debuglink_crc32: Separate Debug Files. |
| (line 144) |
| * h (help): Help. (line 9) |
| * H packet: Packets. (line 135) |
| * handle: Signals. (line 45) |
| * handle_exception: Stub Contents. (line 15) |
| * handling signals: Signals. (line 27) |
| * hardware breakpoints: Set Breaks. (line 57) |
| * hardware watchpoints: Set Watchpoints. (line 22) |
| * hash mark while downloading: Target Commands. (line 99) |
| * hbreak: Set Breaks. (line 57) |
| * help: Help. (line 6) |
| * help target: Target Commands. (line 19) |
| * help user-defined: Define. (line 63) |
| * heuristic-fence-post (Alpha, MIPS): MIPS. (line 14) |
| * 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) |
| * 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 154) |
| * i packet: Packets. (line 149) |
| * 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) |
| * IBM1047 character set: Character Sets. (line 74) |
| * IDT: DJGPP Native. (line 24) |
| * if: Command Files. (line 56) |
| * ignore: Conditions. (line 77) |
| * ignore count (of breakpoint): Conditions. (line 66) |
| * INCLUDE_RDB: VxWorks. (line 33) |
| * incomplete type: Symbols. (line 99) |
| * indentation in structure display: Print Settings. (line 196) |
| * inferior debugging info: Debugging Output. (line 57) |
| * inferior functions, calling: Calling. (line 6) |
| * inferior tty: Input/Output. (line 44) |
| * infinite recursion in user-defined commands: Define. (line 73) |
| * info: Help. (line 99) |
| * info address: Symbols. (line 44) |
| * info all-registers: Registers. (line 15) |
| * info args: Frame Info. (line 51) |
| * info auxv: OS Information. (line 33) |
| * info breakpoints: Set Breaks. (line 112) |
| * info catch: Frame Info. (line 60) |
| * info checkpoints: Checkpoint/Restart. (line 31) |
| * info classes: Symbols. (line 197) |
| * info common: Special Fortran Commands. |
| (line 9) |
| * info copying: Help. (line 136) |
| * info dcache: Caching Remote Data. (line 22) |
| * info display: Auto Display. (line 66) |
| * info dll: Cygwin Native. (line 23) |
| * 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 object files: Maintenance Commands. |
| (line 161) |
| * info forks: Processes. (line 80) |
| * info frame: Frame Info. (line 17) |
| * info frame, show the source language: Show. (line 15) |
| * info functions: Symbols. (line 176) |
| * info handle: Signals. (line 33) |
| * info io_registers, AVR: AVR. (line 10) |
| * info line: Machine Code. (line 13) |
| * info line, and Objective-C: Method Names in Commands. |
| (line 9) |
| * info locals: Frame Info. (line 55) |
| * info macro: Macros. (line 50) |
| * info mem: Memory Region Attributes. |
| (line 45) |
| * info meminfo: SVR4 Process Information. |
| (line 78) |
| * info or1k spr: OpenRISC 1000. (line 20) |
| * info pidlist: SVR4 Process Information. |
| (line 74) |
| * info proc: SVR4 Process Information. |
| (line 16) |
| * info program: Stopping. (line 18) |
| * info registers: Registers. (line 11) |
| * info scope: Symbols. (line 130) |
| * info selectors: Symbols. (line 203) |
| * 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 151) |
| * info source, show the source language: Show. (line 21) |
| * info sources: Symbols. (line 170) |
| * info spu: SPU. (line 10) |
| * info stack: Backtrace. (line 34) |
| * info symbol: Symbols. (line 54) |
| * info target: Files. (line 191) |
| * info terminal: Input/Output. (line 12) |
| * info threads: Threads. (line 62) |
| * info threads (HP-UX): Threads. (line 99) |
| * info tp: Listing Tracepoints. (line 6) |
| * info tracepoints: Listing Tracepoints. (line 6) |
| * info types: Symbols. (line 116) |
| * info udot: OS Information. (line 16) |
| * info variables: Symbols. (line 188) |
| * info vector: Vector Unit. (line 9) |
| * info w32: Cygwin Native. (line 12) |
| * info warranty: Help. (line 140) |
| * info watchpoints [N]: Set Watchpoints. (line 55) |
| * info win: TUI Commands. (line 12) |
| * information about tracepoints: Listing Tracepoints. (line 6) |
| * inheritance: Debugging C Plus Plus. |
| (line 24) |
| * init file: Startup. (line 11) |
| * init file name: Startup. (line 37) |
| * init-if-undefined: Convenience Vars. (line 41) |
| * initial frame: Frames. (line 12) |
| * initialization file, readline: Readline Init File. (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 35) |
| * integral datatypes, in file-i/o protocol: Integral Datatypes. |
| (line 6) |
| * Intel: Remote Stub. (line 57) |
| * Intel disassembly flavor: Machine Code. (line 67) |
| * interaction, readline: Readline Interaction. |
| (line 6) |
| * internal commands: Maintenance Commands. |
| (line 6) |
| * internal GDB breakpoints: Set Breaks. (line 289) |
| * interpreter-exec: Interpreters. (line 43) |
| * interrupt: Quitting GDB. (line 13) |
| * interrupt remote programs: Remote Configuration. |
| (line 29) |
| * interrupting remote programs: Connecting. (line 77) |
| * interrupting remote targets: Bootstrapping. (line 25) |
| * interrupts (remote protocol): Interrupts. (line 6) |
| * invalid input: Bug Criteria. (line 16) |
| * invoke another interpreter: Interpreters. (line 37) |
| * isatty, file-i/o system call: isatty. (line 6) |
| * isearch-terminators: Readline Init File Syntax. |
| (line 112) |
| * ISO 8859-1 character set: Character Sets. (line 68) |
| * ISO Latin 1 character set: Character Sets. (line 68) |
| * jump: Jumping. (line 10) |
| * jump, and Objective-C: Method Names in Commands. |
| (line 9) |
| * k packet: Packets. (line 158) |
| * kernel crash dump: BSD libkvm Interface. |
| (line 6) |
| * kernel memory image: BSD libkvm Interface. |
| (line 6) |
| * keymap: Readline Init File Syntax. |
| (line 119) |
| * kill: Kill Process. (line 6) |
| * 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 31) |
| * latest breakpoint: Set Breaks. (line 6) |
| * layout: TUI Commands. (line 15) |
| * LDT: DJGPP Native. (line 24) |
| * leaving GDB: Quitting GDB. (line 6) |
| * Left: TUI Keys. (line 59) |
| * 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) |
| * linespec: Specify Location. (line 6) |
| * Linux lightweight processes: Debugging Output. (line 66) |
| * list: List. (line 6) |
| * list active threads, remote request: General Query Packets. |
| (line 60) |
| * list of supported file-i/o calls: List of Supported Calls. |
| (line 6) |
| * list output in GDB/MI: GDB/MI Output Syntax. |
| (line 115) |
| * 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 270) |
| * listing machine instructions: Machine Code. (line 35) |
| * 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 130) |
| * locate address: Output Formats. (line 35) |
| * lock scheduler: Thread Stops. (line 90) |
| * log output in GDB/MI: GDB/MI Output Syntax. |
| (line 111) |
| * logging file name: Logging Output. (line 13) |
| * logging GDB output: Logging Output. (line 6) |
| * loop_break: Command Files. (line 75) |
| * loop_continue: Command Files. (line 79) |
| * lseek flags, in file-i/o protocol: Lseek Flags. (line 6) |
| * lseek, file-i/o system call: lseek. (line 6) |
| * M packet: Packets. (line 185) |
| * m packet: Packets. (line 165) |
| * 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 35) |
| * macro define: Macros. (line 54) |
| * macro definition, showing: Macros. (line 50) |
| * macro exp1: Macros. (line 39) |
| * macro expand: Macros. (line 32) |
| * macro expansion, showing the results of preprocessor: Macros. |
| (line 32) |
| * macro list: Macros. (line 76) |
| * macro undef: Macros. (line 69) |
| * macros, example of debugging with: Macros. (line 80) |
| * macros, user-defined: Macros. (line 54) |
| * mailing lists: GDB/MI Development and Front Ends. |
| (line 39) |
| * maint agent: Maintenance Commands. |
| (line 12) |
| * maint check-symtabs: Maintenance Commands. |
| (line 48) |
| * maint cplus first_component: Maintenance Commands. |
| (line 51) |
| * maint cplus namespace: Maintenance Commands. |
| (line 54) |
| * maint demangle: Maintenance Commands. |
| (line 57) |
| * maint deprecate: Maintenance Commands. |
| (line 60) |
| * maint dump-me: Maintenance Commands. |
| (line 68) |
| * maint info breakpoints: Maintenance Commands. |
| (line 17) |
| * maint info psymtabs: Symbols. (line 270) |
| * maint info sections: Files. (line 200) |
| * maint info sol-threads: Threads. (line 129) |
| * maint info symtabs: Symbols. (line 270) |
| * maint internal-error: Maintenance Commands. |
| (line 73) |
| * maint internal-warning: Maintenance Commands. |
| (line 73) |
| * maint packet: Maintenance Commands. |
| (line 94) |
| * maint print architecture: Maintenance Commands. |
| (line 100) |
| * maint print c-tdesc: Maintenance Commands. |
| (line 104) |
| * maint print cooked-registers: Maintenance Commands. |
| (line 127) |
| * maint print dummy-frames: Maintenance Commands. |
| (line 109) |
| * maint print objfiles: Maintenance Commands. |
| (line 161) |
| * maint print psymbols: Symbols. (line 251) |
| * maint print raw-registers: Maintenance Commands. |
| (line 127) |
| * maint print reggroups: Maintenance Commands. |
| (line 142) |
| * maint print register-groups: Maintenance Commands. |
| (line 127) |
| * maint print registers: Maintenance Commands. |
| (line 127) |
| * maint print statistics: Maintenance Commands. |
| (line 166) |
| * maint print symbols: Symbols. (line 251) |
| * maint print target-stack: Maintenance Commands. |
| (line 179) |
| * maint print type: Maintenance Commands. |
| (line 191) |
| * maint print unwind, HPPA: HPPA. (line 17) |
| * maint set dwarf2 max-cache-age: Maintenance Commands. |
| (line 198) |
| * maint set profile: Maintenance Commands. |
| (line 212) |
| * maint show dwarf2 max-cache-age: Maintenance Commands. |
| (line 198) |
| * maint show profile: Maintenance Commands. |
| (line 212) |
| * maint show-debug-regs: Maintenance Commands. |
| (line 228) |
| * maint space: Maintenance Commands. |
| (line 235) |
| * maint time: Maintenance Commands. |
| (line 242) |
| * maint translate-address: Maintenance Commands. |
| (line 249) |
| * maint undeprecate: Maintenance Commands. |
| (line 60) |
| * 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) |
| * match-hidden-files: Readline Init File Syntax. |
| (line 142) |
| * maximum value for offset of closest symbol: Print Settings. (line 70) |
| * 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 235) |
| * memory used for symbol tables: Files. (line 311) |
| * memory, alignment and size of remote accesses: Packets. (line 172) |
| * memory, viewing as typed object: Expressions. (line 42) |
| * 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) |
| * MMX registers (x86): Registers. (line 71) |
| * mode_t values, in file-i/o protocol: mode_t Values. (line 6) |
| * Modula-2: Summary. (line 27) |
| * 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 104) |
| * monitor commands, for gdbserver: Server. (line 149) |
| * 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 processes: Processes. (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) |
| * n (next): Continuing and Stepping. |
| (line 78) |
| * n (SingleKey TUI key): TUI Single Key Mode. (line 19) |
| * 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 289) |
| * NetROM ROM emulator target: Target Commands. (line 88) |
| * New SYSTAG message: Threads. (line 47) |
| * New SYSTAG message, on HP-UX: Threads. (line 89) |
| * next: Continuing and Stepping. |
| (line 78) |
| * next-history (C-n): Commands For History. |
| (line 16) |
| * nexti: Continuing and Stepping. |
| (line 202) |
| * ni (nexti): Continuing and Stepping. |
| (line 202) |
| * 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 103) |
| * noninvasive task options: Hurd Native. (line 73) |
| * nosharedlibrary: Files. (line 339) |
| * notation, readline: Readline Bare Essentials. |
| (line 6) |
| * notational conventions, for GDB/MI: GDB/MI. (line 25) |
| * notify output in GDB/MI: GDB/MI Output Syntax. |
| (line 100) |
| * NULL elements in arrays: Print Settings. (line 187) |
| * 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 197) |
| * Objective-C, print objects: The Print Command with Objective-C. |
| (line 6) |
| * observer debugging info: Debugging Output. (line 73) |
| * octal escapes in strings: Print Settings. (line 220) |
| * online documentation: Help. (line 6) |
| * opaque data types: Symbols. (line 233) |
| * open flags, in file-i/o protocol: Open Flags. (line 6) |
| * open, file-i/o system call: open. (line 6) |
| * OpenRISC 1000: OpenRISC 1000. (line 6) |
| * OpenRISC 1000 htrace: OpenRISC 1000. (line 58) |
| * optimized code, debugging: Compilation. (line 26) |
| * optimized code, wrong values of variables: Variables. (line 58) |
| * 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-band records in GDB/MI: GDB/MI Out-of-band Records. |
| (line 6) |
| * 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 47) |
| * overloading: Breakpoint Menus. (line 6) |
| * overloading in C++: Debugging C Plus Plus. |
| (line 14) |
| * overwrite-mode (): Commands For Text. (line 53) |
| * P packet: Packets. (line 213) |
| * p packet: Packets. (line 198) |
| * packet size, remote protocol: General Query Packets. |
| (line 326) |
| * packets, reporting on stdout: Debugging Output. (line 86) |
| * packets, tracepoint: Tracepoint Packets. (line 6) |
| * page tables display (MS-DOS): DJGPP Native. (line 56) |
| * page-completions: Readline Init File Syntax. |
| (line 154) |
| * partial symbol dump: Symbols. (line 251) |
| * partial symbol tables, listing GDB's internal: Symbols. (line 270) |
| * Pascal: Summary. (line 30) |
| * Pascal objects, static members display: Print Settings. (line 351) |
| * Pascal support in GDB, limitations: Pascal. (line 6) |
| * pass signals to inferior, remote request: General Query Packets. |
| (line 175) |
| * 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) |
| * pending breakpoints: Set Breaks. (line 217) |
| * PgDn: TUI Keys. (line 50) |
| * PgUp: TUI Keys. (line 47) |
| * physical address from linear address: DJGPP Native. (line 81) |
| * pipe, target remote to: Connecting. (line 60) |
| * pipes: Starting. (line 54) |
| * pmon, MIPS remote: MIPS Embedded. (line 132) |
| * po (print-object): The Print Command with Objective-C. |
| (line 6) |
| * 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) |
| * 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 shared library file names: Files. (line 369) |
| * prefix-meta (<ESC>): Miscellaneous Commands. |
| (line 18) |
| * premature return from system calls: Thread Stops. (line 37) |
| * preprocessor macro expansion, showing the results of: Macros. |
| (line 32) |
| * pretty print arrays: Print Settings. (line 98) |
| * pretty print C++ virtual function tables: Print Settings. (line 362) |
| * 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 messages on thread start and exit: Threads. (line 155) |
| * print settings: Print Settings. (line 6) |
| * print structures in indented form: Print Settings. (line 196) |
| * print-object: The Print Command with Objective-C. |
| (line 6) |
| * print/don't print memory addresses: Print Settings. (line 13) |
| * 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) |
| * 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 PROCESS-ID: Processes. (line 90) |
| * process status register: Registers. (line 26) |
| * processes, multiple: Processes. (line 6) |
| * procfs API calls: SVR4 Process Information. |
| (line 53) |
| * profiling GDB: Maintenance Commands. |
| (line 212) |
| * program counter register: Registers. (line 26) |
| * program entry point: Backtrace. (line 87) |
| * 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) |
| * ptrace system call: OS Information. (line 9) |
| * ptype: Symbols. (line 77) |
| * putDebugChar: Bootstrapping. (line 20) |
| * pwd: Working Directory. (line 19) |
| * q (quit): Quitting GDB. (line 6) |
| * q (SingleKey TUI key): TUI Single Key Mode. (line 22) |
| * Q packet: Packets. (line 226) |
| * q packet: Packets. (line 226) |
| * qC packet: General Query Packets. |
| (line 41) |
| * qCRC packet: General Query Packets. |
| (line 51) |
| * qfThreadInfo packet: General Query Packets. |
| (line 60) |
| * qGetTLSAddr packet: General Query Packets. |
| (line 87) |
| * QNX Neutrino: Neutrino. (line 6) |
| * qOffsets packet: General Query Packets. |
| (line 139) |
| * qP packet: General Query Packets. |
| (line 166) |
| * QPassSignals packet: General Query Packets. |
| (line 175) |
| * qRcmd packet: General Query Packets. |
| (line 203) |
| * qsThreadInfo packet: General Query Packets. |
| (line 60) |
| * qSupported packet: General Query Packets. |
| (line 228) |
| * qSymbol packet: General Query Packets. |
| (line 367) |
| * qThreadExtraInfo packet: General Query Packets. |
| (line 403) |
| * query annotation: Prompting. (line 36) |
| * 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 429) |
| * r (run): Starting. (line 6) |
| * r (SingleKey TUI key): TUI Single Key Mode. (line 25) |
| * R packet: Packets. (line 235) |
| * r packet: Packets. (line 230) |
| * raise exceptions: Set Catchpoints. (line 80) |
| * range checking: Type Checking. (line 65) |
| * ranges of breakpoints: Breakpoints. (line 48) |
| * rbreak: Set Breaks. (line 87) |
| * RDI heartbeat: ARM. (line 93) |
| * rdilogenable: ARM. (line 76) |
| * rdilogfile: ARM. (line 70) |
| * re-read-init-file (C-x C-r): Miscellaneous Commands. |
| (line 6) |
| * read special object, remote request: General Query Packets. |
| (line 429) |
| * read, file-i/o system call: read. (line 6) |
| * read-only sections: Files. (line 258) |
| * reading symbols from relocatable object files: Files. (line 132) |
| * reading symbols immediately: Files. (line 90) |
| * readline: Editing. (line 6) |
| * readnow: Files. (line 90) |
| * receive rights, GNU Hurd: Hurd Native. (line 85) |
| * recent tracepoint number: Create and Delete Tracepoints. |
| (line 31) |
| * record aggregates (Ada): Omissions from Ada. (line 44) |
| * record serial communications on file: Remote Configuration. |
| (line 57) |
| * recording a session script: Bug Reporting. (line 104) |
| * 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) |
| * refresh: TUI Commands. (line 52) |
| * register stack, AMD29K: A29K. (line 6) |
| * registers: Registers. (line 6) |
| * regs, Super-H: Super-H. (line 9) |
| * regular expression: Set Breaks. (line 87) |
| * reloading symbols: Symbols. (line 209) |
| * 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 105) |
| * remote monitor prompt: MIPS Embedded. (line 107) |
| * remote packets, enabling and disabling: Remote Configuration. |
| (line 84) |
| * remote programs, interrupting: Connecting. (line 77) |
| * remote protocol debugging: Debugging Output. (line 86) |
| * remote protocol, binary data: Overview. (line 55) |
| * remote protocol, field separator: Overview. (line 47) |
| * 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 17) |
| * rename, file-i/o system call: rename. (line 6) |
| * Renesas: Remote Stub. (line 63) |
| * repeated array elements: Print Settings. (line 174) |
| * repeating command sequences: Command Syntax. (line 42) |
| * repeating commands: Command Syntax. (line 21) |
| * reporting bugs in GDB: GDB Bugs. (line 6) |
| * reprint the last value: Data. (line 21) |
| * 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) |
| * 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-search: Search. (line 16) |
| * reverse-search-history (C-r): Commands For History. |
| (line 26) |
| * revert-line (M-r): Miscellaneous Commands. |
| (line 25) |
| * rewind program state: Checkpoint/Restart. (line 6) |
| * Right: TUI Keys. (line 62) |
| * ROM at zero address, RDI: ARM. (line 83) |
| * run: Starting. (line 6) |
| * run to main procedure: Starting. (line 71) |
| * run until specified location: Continuing and Stepping. |
| (line 117) |
| * running: Starting. (line 6) |
| * running and debugging Sparclet programs: Sparclet Execution. |
| (line 6) |
| * running VxWorks tasks: VxWorks Attach. (line 6) |
| * running, on Sparclet: Sparclet. (line 28) |
| * rwatch: Set Watchpoints. (line 47) |
| * s (SingleKey TUI key): TUI Single Key Mode. (line 28) |
| * s (step): Continuing and Stepping. |
| (line 46) |
| * S packet: Packets. (line 248) |
| * s packet: Packets. (line 242) |
| * save command history: Command History. (line 36) |
| * save GDB output to a file: Logging Output. (line 6) |
| * save tracepoints for future sessions: save-tracepoints. (line 6) |
| * save-tracepoints: save-tracepoints. (line 6) |
| * scheduler locking mode: Thread Stops. (line 90) |
| * scope: M2 Scope. (line 6) |
| * scripting commands: Command Files. (line 6) |
| * sdireset: M32R/D. (line 44) |
| * sdistatus: M32R/D. (line 47) |
| * SDS protocol: PowerPC Embedded. (line 34) |
| * sds, a command: PowerPC Embedded. (line 45) |
| * search: Search. (line 9) |
| * searching source files: Search. (line 6) |
| * section: Files. (line 182) |
| * section offsets, remote request: General Query Packets. |
| (line 139) |
| * segment descriptor tables: DJGPP Native. (line 24) |
| * select trace snapshot: tfind. (line 6) |
| * select-frame: Frames. (line 51) |
| * selected frame: Stack. (line 19) |
| * selecting frame silently: Frames. (line 51) |
| * self-insert (a, b, A, 1, !, ...): Commands For Text. (line 27) |
| * send command to remote monitor: Connecting. (line 104) |
| * send command to simulator: Embedded Processors. (line 9) |
| * 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 86) |
| * 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 annotate: Annotations Overview. |
| (line 29) |
| * set architecture: Targets. (line 21) |
| * set args: Arguments. (line 21) |
| * set arm: ARM. (line 18) |
| * set auto-solib-add: Files. (line 303) |
| * set backtrace: Backtrace. (line 98) |
| * set board-address: M32R/D. (line 21) |
| * set breakpoint auto-hw: Set Breaks. (line 279) |
| * set breakpoint pending: Set Breaks. (line 248) |
| * set breakpoints in many functions: Set Breaks. (line 87) |
| * set breakpoints on all functions: Set Breaks. (line 107) |
| * set can-use-hw-watchpoints: Set Watchpoints. (line 74) |
| * set case-sensitive: Symbols. (line 27) |
| * set charset: Character Sets. (line 47) |
| * set check range: Range Checking. (line 34) |
| * set check type: Type Checking. (line 42) |
| * 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 30) |
| * set debug: Debugging Output. (line 18) |
| * set debug hppa: HPPA. (line 10) |
| * 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 59) |
| * set debugexceptions: Cygwin Native. (line 70) |
| * set debugexec: Cygwin Native. (line 66) |
| * set debugmemory: Cygwin Native. (line 74) |
| * set demangle-style: Print Settings. (line 294) |
| * set detach-on-fork: Processes. (line 55) |
| * set disassembly-flavor: Machine Code. (line 67) |
| * 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-done-display: Debugging Output. (line 11) |
| * set extension-language: Show. (line 30) |
| * set follow-fork-mode: Processes. (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 34) |
| * set inferior controlling terminal: Input/Output. (line 44) |
| * set inferior-tty: Input/Output. (line 49) |
| * set input-radix: Numbers. (line 14) |
| * set language: Manually. (line 9) |
| * set listsize: List. (line 33) |
| * set logging: Logging Output. (line 9) |
| * set max-user-call-depth: Define. (line 73) |
| * 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 new-console: Cygwin Native. (line 42) |
| * set new-group: Cygwin Native. (line 51) |
| * set opaque-type-resolution: Symbols. (line 233) |
| * set osabi: ABI. (line 11) |
| * set output-radix: Numbers. (line 31) |
| * set overload-resolution: Debugging C Plus Plus. |
| (line 47) |
| * set pagination: Screen Size. (line 38) |
| * set powerpc: PowerPC Embedded. (line 8) |
| * set print: Print Settings. (line 11) |
| * set print thread-events: Threads. (line 155) |
| * 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 rdiheartbeat: ARM. (line 93) |
| * set rdiromatzero: ARM. (line 83) |
| * 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 14) |
| * set remoteflow: Remote Configuration. |
| (line 41) |
| * set retransmit-timeout: MIPS Embedded. (line 83) |
| * set rstack_high_address: A29K. (line 6) |
| * set sdstimeout: PowerPC Embedded. (line 38) |
| * set server-address: M32R/D. (line 27) |
| * set shell: Cygwin Native. (line 78) |
| * 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 369) |
| * set solib-search-path: Files. (line 390) |
| * set step-mode: Continuing and Stepping. |
| (line 92) |
| * set stop-on-solib-events: Files. (line 349) |
| * set stopped, Hurd command: Hurd Native. (line 32) |
| * set struct-convention: i386. (line 7) |
| * set substitute-path: Source Path. (line 114) |
| * set symbol-reloading: Symbols. (line 216) |
| * set syn-garbage-limit, MIPS remote: MIPS Embedded. (line 98) |
| * set sysroot: Files. (line 369) |
| * set target-charset: Character Sets. (line 28) |
| * set task, Hurd commands: Hurd Native. (line 49) |
| * 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 65) |
| * 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 unwindonsignal: Calling. (line 26) |
| * set variable: Assignment. (line 16) |
| * set verbose: Messages/Warnings. (line 15) |
| * set watchdog: Maintenance Commands. |
| (line 262) |
| * 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) |
| * 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 330) |
| * shared libraries: Files. (line 281) |
| * shared library events, remote reply: Stop Reply Packets. (line 52) |
| * sharedlibrary: Files. (line 330) |
| * shell: Shell Commands. (line 10) |
| * shell escape: Shell Commands. (line 10) |
| * show: Help. (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-solib-add: Files. (line 320) |
| * show backtrace: Backtrace. (line 105) |
| * show board-address: M32R/D. (line 24) |
| * show breakpoint auto-hw: Set Breaks. (line 279) |
| * show breakpoint pending: Set Breaks. (line 248) |
| * show can-use-hw-watchpoints: Set Watchpoints. (line 77) |
| * show case-sensitive: Symbols. (line 40) |
| * show charset: Character Sets. (line 53) |
| * show check range: Range Checking. (line 34) |
| * show check type: Type Checking. (line 42) |
| * 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 56) |
| * show convenience: Convenience Vars. (line 37) |
| * show copying: Help. (line 136) |
| * show cp-abi: ABI. (line 53) |
| * show cygwin-exceptions: Cygwin Native. (line 38) |
| * show debug: Debugging Output. (line 22) |
| * 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 72) |
| * show detach-on-fork: Processes. (line 71) |
| * show directories: Source Path. (line 111) |
| * show disassembly-flavor: Machine Code. (line 76) |
| * 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: Processes. (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 56) |
| * show inferior-tty: Input/Output. (line 52) |
| * show input-radix: Numbers. (line 36) |
| * show language: Show. (line 10) |
| * show last commands: Command History. (line 78) |
| * show listsize: List. (line 37) |
| * show logging: Logging Output. (line 26) |
| * show max-user-call-depth: Define. (line 73) |
| * 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 new-console: Cygwin Native. (line 47) |
| * show new-group: Cygwin Native. (line 56) |
| * show opaque-type-resolution: Symbols. (line 248) |
| * show osabi: ABI. (line 11) |
| * show output-radix: Numbers. (line 39) |
| * show overload-resolution: Debugging C Plus Plus. |
| (line 64) |
| * show pagination: Screen Size. (line 42) |
| * show paths: Environment. (line 29) |
| * show print: Print Settings. (line 39) |
| * show print thread-events: Threads. (line 165) |
| * 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 rdiheartbeat: ARM. (line 98) |
| * show rdiromatzero: ARM. (line 90) |
| * 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 19) |
| * show remoteflow: Remote Configuration. |
| (line 45) |
| * show retransmit-timeout: MIPS Embedded. (line 83) |
| * show rstack_high_address: A29K. (line 17) |
| * show sdstimeout: PowerPC Embedded. (line 42) |
| * show server-address: M32R/D. (line 31) |
| * show shell: Cygwin Native. (line 82) |
| * 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 401) |
| * show stop-on-solib-events: Files. (line 355) |
| * show stopped, Hurd command: Hurd Native. (line 37) |
| * show struct-convention: i386. (line 15) |
| * show substitute-path: Source Path. (line 151) |
| * show symbol-reloading: Symbols. (line 230) |
| * show syn-garbage-limit, MIPS remote: MIPS Embedded. (line 103) |
| * show sysroot: Files. (line 387) |
| * show target-charset: Character Sets. (line 59) |
| * show task, Hurd commands: Hurd Native. (line 57) |
| * show tdesc filename: Retrieving Descriptions. |
| (line 25) |
| * show thread, Hurd command: Hurd Native. (line 101) |
| * show timeout: MIPS Embedded. (line 83) |
| * show unwindonsignal: Calling. (line 33) |
| * show user: Define. (line 67) |
| * 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) |
| * si (stepi): Continuing and Stepping. |
| (line 189) |
| * 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 69) |
| * silent: Break Commands. (line 38) |
| * sim: Z8000. (line 15) |
| * sim, a command: Embedded Processors. (line 13) |
| * simulator, Z8000: Z8000. (line 6) |
| * size of remote memory accesses: Packets. (line 172) |
| * size of screen: Screen Size. (line 6) |
| * snapshot of a process: Checkpoint/Restart. (line 6) |
| * software watchpoints: Set Watchpoints. (line 22) |
| * source: Command Files. (line 14) |
| * 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: Starting. (line 70) |
| * 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 87) |
| * stat, file-i/o system call: stat/fstat. (line 6) |
| * static members of C++ objects: Print Settings. (line 340) |
| * static members of Pascal objects: Print Settings. (line 351) |
| * status of trace data collection: Starting and Stopping Trace Experiments. |
| (line 20) |
| * status output in GDB/MI: GDB/MI Output Syntax. |
| (line 92) |
| * step: Continuing and Stepping. |
| (line 46) |
| * stepi: Continuing and Stepping. |
| (line 189) |
| * 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 reply packets: Stop Reply Packets. (line 6) |
| * stop, a pseudo-command: Hooks. (line 21) |
| * stopped threads: Thread Stops. (line 32) |
| * stopping annotation: Annotations for Running. |
| (line 6) |
| * stream records in GDB/MI: GDB/MI Stream Records. |
| (line 6) |
| * 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) |
| * stub example, remote debugging: Remote Stub. (line 6) |
| * stupid questions: Messages/Warnings. (line 50) |
| * Super-H: Super-H. (line 6) |
| * supported packets, remote query: General Query Packets. |
| (line 228) |
| * switching threads: Threads. (line 6) |
| * switching threads automatically: Threads. (line 169) |
| * symbol decoding style, C++: Print Settings. (line 294) |
| * symbol dump: Symbols. (line 251) |
| * symbol from address: Symbols. (line 54) |
| * symbol lookup, remote request: General Query Packets. |
| (line 367) |
| * symbol names: Symbols. (line 14) |
| * symbol overloading: Breakpoint Menus. (line 6) |
| * symbol table: Files. (line 6) |
| * symbol tables, listing GDB's internal: Symbols. (line 270) |
| * symbol, source file and line: Print Settings. (line 51) |
| * symbol-file: Files. (line 45) |
| * symbols, reading from relocatable object files: Files. (line 132) |
| * symbols, reading immediately: Files. (line 90) |
| * synchronize with remote MIPS target: MIPS Embedded. (line 98) |
| * syscall DSO: Files. (line 162) |
| * sysinfo: DJGPP Native. (line 19) |
| * system calls and thread breakpoints: Thread Stops. (line 37) |
| * system root, alternate: Files. (line 369) |
| * system, file-i/o system call: system. (line 6) |
| * T packet: Packets. (line 260) |
| * t packet: Packets. (line 255) |
| * T packet reply: Stop Reply Packets. (line 22) |
| * tabset: TUI Commands. (line 78) |
| * 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 111) |
| * target descriptions: Target Descriptions. (line 6) |
| * target descriptions, ARM features: ARM Features. (line 6) |
| * target descriptions, inclusion: Target Description Format. |
| (line 51) |
| * 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 23) |
| * 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 op50n: PA. (line 6) |
| * target output in GDB/MI: GDB/MI Output Syntax. |
| (line 108) |
| * target pmon PORT: MIPS Embedded. (line 38) |
| * target ppcbug: PowerPC Embedded. (line 26) |
| * target ppcbug1: PowerPC Embedded. (line 27) |
| * target r3900: MIPS Embedded. (line 46) |
| * target rdi: ARM. (line 6) |
| * target rdp: ARM. (line 11) |
| * target remote: Connecting. (line 11) |
| * target sds: PowerPC Embedded. (line 31) |
| * target sim, with Z8000: Z8000. (line 15) |
| * target sparclite: Sparclite. (line 6) |
| * target stack description: Maintenance Commands. |
| (line 179) |
| * target vxworks: VxWorks. (line 6) |
| * target w89k: PA. (line 9) |
| * task attributes (GNU Hurd): Hurd Native. (line 49) |
| * task exception port, GNU Hurd: Hurd Native. (line 68) |
| * task suspend count: Hurd Native. (line 60) |
| * tbreak: Set Breaks. (line 50) |
| * TCP port, target remote: Connecting. (line 29) |
| * tdump: tdump. (line 6) |
| * terminal: Input/Output. (line 6) |
| * Text User Interface: TUI. (line 6) |
| * tfind: tfind. (line 6) |
| * thbreak: Set Breaks. (line 77) |
| * this, inside C++ member functions: C Plus Plus Expressions. |
| (line 22) |
| * thread apply: Threads. (line 146) |
| * thread attributes info, remote request: General Query Packets. |
| (line 403) |
| * thread breakpoints: Thread Stops. (line 10) |
| * thread breakpoints and system calls: Thread Stops. (line 37) |
| * thread default settings, GNU Hurd: Hurd Native. (line 131) |
| * thread identifier (GDB): Threads. (line 59) |
| * thread identifier (GDB), on HP-UX: Threads. (line 85) |
| * thread identifier (system): Threads. (line 47) |
| * thread identifier (system), on HP-UX: Threads. (line 89) |
| * thread info (Solaris): Threads. (line 129) |
| * thread information, remote request: General Query Packets. |
| (line 166) |
| * thread number: Threads. (line 59) |
| * thread properties, GNU Hurd: Hurd Native. (line 91) |
| * thread suspend count, GNU Hurd: Hurd Native. (line 110) |
| * thread THREADNO: Threads. (line 131) |
| * threads and watchpoints: Set Watchpoints. (line 149) |
| * threads of execution: Threads. (line 6) |
| * threads, automatic switching: Threads. (line 169) |
| * threads, continuing: Thread Stops. (line 70) |
| * threads, stopped: Thread Stops. (line 32) |
| * time of command execution: Maintenance Commands. |
| (line 242) |
| * timeout for commands: Maintenance Commands. |
| (line 262) |
| * timeout for serial communications: Remote Configuration. |
| (line 65) |
| * timeout, MIPS protocol: MIPS Embedded. (line 83) |
| * tload, M32R: M32R/D. (line 39) |
| * trace: Create and Delete Tracepoints. |
| (line 6) |
| * trace experiment, status of: Starting and Stopping Trace Experiments. |
| (line 20) |
| * traceback: Backtrace. (line 6) |
| * tracepoint actions: Tracepoint Actions. (line 6) |
| * tracepoint data, display: tdump. (line 6) |
| * tracepoint deletion: Create and Delete Tracepoints. |
| (line 34) |
| * tracepoint number: Create and Delete Tracepoints. |
| (line 31) |
| * tracepoint packets: Tracepoint Packets. (line 6) |
| * tracepoint pass count: Tracepoint Passcounts. |
| (line 6) |
| * tracepoint variables: Tracepoint Variables. |
| (line 6) |
| * tracepoints: Tracepoints. (line 6) |
| * 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) |
| * 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 55) |
| * TUI single key mode: TUI Single Key Mode. (line 6) |
| * type casting memory: Expressions. (line 42) |
| * type chain of a data type: Maintenance Commands. |
| (line 191) |
| * type checking: Checks. (line 31) |
| * type conversions in C++: C Plus Plus Expressions. |
| (line 27) |
| * u (SingleKey TUI key): TUI Single Key Mode. (line 31) |
| * u (until): Continuing and Stepping. |
| (line 117) |
| * UDP port, target remote: Connecting. (line 49) |
| * undisplay: Auto Display. (line 45) |
| * undo (C-_ or C-x C-u): Miscellaneous Commands. |
| (line 22) |
| * unions in structures, printing: Print Settings. (line 234) |
| * 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 339) |
| * unmap an overlay: Overlay Commands. (line 39) |
| * unmapped overlays: How Overlays Work. (line 6) |
| * unset environment: Environment. (line 55) |
| * unset substitute-path: Source Path. (line 143) |
| * unset tdesc filename: Retrieving Descriptions. |
| (line 21) |
| * unsupported languages: Unsupported Languages. |
| (line 6) |
| * until: Continuing and Stepping. |
| (line 117) |
| * unwind stack in called functions: Calling. (line 26) |
| * Up: TUI Keys. (line 53) |
| * up: Selection. (line 35) |
| * up-silently: Selection. (line 64) |
| * upcase-word (M-u): Commands For Text. (line 41) |
| * update: TUI Commands. (line 70) |
| * upload, M32R: M32R/D. (line 34) |
| * use only software watchpoints: Set Watchpoints. (line 66) |
| * 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 54) |
| * user-defined variables: Convenience Vars. (line 6) |
| * v (SingleKey TUI key): TUI Single Key Mode. (line 34) |
| * value history: Value History. (line 6) |
| * value optimized out, in backtrace: Backtrace. (line 65) |
| * variable name conflict: Variables. (line 36) |
| * variable object debugging info: Debugging Output. (line 122) |
| * 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 274) |
| * vCont packet: Packets. (line 289) |
| * vCont? packet: Packets. (line 315) |
| * vector unit: Vector Unit. (line 6) |
| * vector, auxiliary: OS Information. (line 21) |
| * verbose operation: Messages/Warnings. (line 6) |
| * verify remote memory image: Memory. (line 105) |
| * vFile packet: Packets. (line 326) |
| * vFlashDone packet: Packets. (line 369) |
| * vFlashErase packet: Packets. (line 330) |
| * vFlashWrite packet: Packets. (line 347) |
| * virtual functions (C++) display: Print Settings. (line 362) |
| * visible-stats: Readline Init File Syntax. |
| (line 179) |
| * vRun packet: Packets. (line 377) |
| * VTBL display: Print Settings. (line 362) |
| * VxWorks: VxWorks. (line 6) |
| * vxworks-timeout: VxWorks. (line 23) |
| * w (SingleKey TUI key): TUI Single Key Mode. (line 37) |
| * watch: Set Watchpoints. (line 33) |
| * watchdog timer: Maintenance Commands. |
| (line 262) |
| * watchpoint annotation: Annotations for Running. |
| (line 50) |
| * watchpoints: Breakpoints. (line 20) |
| * watchpoints and threads: Set Watchpoints. (line 149) |
| * weak alias functions: Calling. (line 36) |
| * whatis: Symbols. (line 66) |
| * where: Backtrace. (line 34) |
| * where to look for shared libraries: Files. (line 364) |
| * while: Command Files. (line 67) |
| * while-stepping (tracepoints): Tracepoint Actions. (line 67) |
| * wild pointer, interpreting: Print Settings. (line 79) |
| * winheight: TUI Commands. (line 74) |
| * word completion: Completion. (line 6) |
| * working directory: Source Path. (line 99) |
| * working directory (of your program): Working Directory. (line 6) |
| * working language: Languages. (line 13) |
| * write data into object, remote request: General Query Packets. |
| (line 520) |
| * write, file-i/o system call: write. (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 29) |
| * X packet: Packets. (line 394) |
| * x(examine), and info line: Machine Code. (line 29) |
| * x86 hardware debug registers: Maintenance Commands. |
| (line 228) |
| * XInclude: Target Description Format. |
| (line 51) |
| * XML parser debugging: Debugging Output. (line 130) |
| * 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 407) |
| * Z packets: Packets. (line 407) |
| * Z0 packet: Packets. (line 422) |
| * z0 packet: Packets. (line 422) |
| * Z1 packet: Packets. (line 448) |
| * z1 packet: Packets. (line 448) |
| * Z2 packet: Packets. (line 469) |
| * z2 packet: Packets. (line 469) |
| * Z3 packet: Packets. (line 483) |
| * z3 packet: Packets. (line 483) |
| * Z4 packet: Packets. (line 497) |
| * z4 packet: Packets. (line 497) |
| * Z8000: Z8000. (line 6) |
| * Zilog Z8000 simulator: Z8000. (line 6) |
| * {TYPE}: Expressions. (line 42) |
| |
| |
| |
| Tag Table: |
| Node: Top1115 |
| Node: Summary3821 |
| Node: Free Software5457 |
| Node: Contributors11025 |
| Node: Sample Session19009 |
| Node: Invocation25845 |
| Node: Invoking GDB26389 |
| Node: File Options28702 |
| Node: Mode Options31359 |
| Node: Startup37771 |
| Ref: Startup-Footnote-139676 |
| Node: Quitting GDB39785 |
| Node: Shell Commands40682 |
| Node: Logging Output41524 |
| Node: Commands42370 |
| Node: Command Syntax43008 |
| Node: Completion45174 |
| Node: Help49509 |
| Node: Running54748 |
| Node: Compilation55930 |
| Node: Starting58569 |
| Node: Arguments63458 |
| Node: Environment64728 |
| Node: Working Directory67996 |
| Node: Input/Output69104 |
| Node: Attach71075 |
| Node: Kill Process73542 |
| Node: Threads74508 |
| Node: Processes81344 |
| Node: Checkpoint/Restart86563 |
| Ref: Checkpoint/Restart-Footnote-191096 |
| Node: Stopping91131 |
| Node: Breakpoints92278 |
| Node: Set Breaks95697 |
| Node: Set Watchpoints109835 |
| Node: Set Catchpoints117642 |
| Node: Delete Breaks121681 |
| Node: Disabling123617 |
| Node: Conditions126482 |
| Node: Break Commands131430 |
| Node: Breakpoint Menus134315 |
| Node: Error in Breakpoints136041 |
| Node: Breakpoint-related Warnings137619 |
| Node: Continuing and Stepping139946 |
| Node: Signals149258 |
| Node: Thread Stops153530 |
| Node: Stack158167 |
| Node: Frames159643 |
| Node: Backtrace162395 |
| Ref: Backtrace-Footnote-1167286 |
| Node: Selection167474 |
| Node: Frame Info170338 |
| Node: Source172669 |
| Node: List173735 |
| Node: Specify Location176348 |
| Node: Edit179598 |
| Ref: Edit-Footnote-1181073 |
| Node: Search181308 |
| Node: Source Path182116 |
| Ref: set substitute-path187871 |
| Node: Machine Code190092 |
| Node: Data193466 |
| Node: Expressions195847 |
| Node: Variables197815 |
| Node: Arrays202306 |
| Node: Output Formats204835 |
| Ref: Output Formats-Footnote-1207708 |
| Node: Memory207865 |
| Node: Auto Display213112 |
| Node: Print Settings216825 |
| Node: Value History230296 |
| Node: Convenience Vars232712 |
| Node: Registers236236 |
| Ref: Registers-Footnote-1240911 |
| Node: Floating Point Hardware241306 |
| Node: Vector Unit241836 |
| Node: OS Information242221 |
| Node: Memory Region Attributes244219 |
| Node: Dump/Restore Files248877 |
| Node: Core File Generation251180 |
| Node: Character Sets252412 |
| Node: Caching Remote Data259237 |
| Node: Macros260385 |
| Node: Tracepoints267336 |
| Node: Set Tracepoints269178 |
| Node: Create and Delete Tracepoints270378 |
| Node: Enable and Disable Tracepoints272022 |
| Node: Tracepoint Passcounts272721 |
| Node: Tracepoint Actions274145 |
| Node: Listing Tracepoints277145 |
| Node: Starting and Stopping Trace Experiments278267 |
| Node: Analyze Collected Data279448 |
| Node: tfind280753 |
| Node: tdump285146 |
| Node: save-tracepoints286805 |
| Node: Tracepoint Variables287224 |
| Node: Overlays288239 |
| Node: How Overlays Work288959 |
| Ref: A code overlay291519 |
| Node: Overlay Commands294957 |
| Node: Automatic Overlay Debugging299147 |
| Node: Overlay Sample Program301288 |
| Node: Languages303048 |
| Node: Setting304211 |
| Node: Filenames305913 |
| Node: Manually306699 |
| Node: Automatically307908 |
| Node: Show308969 |
| Node: Checks310291 |
| Node: Type Checking311681 |
| Node: Range Checking314414 |
| Node: Supported Languages316815 |
| Node: C317988 |
| Node: C Operators319289 |
| Node: C Constants323608 |
| Node: C Plus Plus Expressions326012 |
| Node: C Defaults329555 |
| Node: C Checks330238 |
| Node: Debugging C330961 |
| Node: Debugging C Plus Plus331445 |
| Node: Decimal Floating Point334562 |
| Node: Objective-C335820 |
| Node: Method Names in Commands336281 |
| Node: The Print Command with Objective-C337976 |
| Node: Fortran338627 |
| Node: Fortran Operators339352 |
| Node: Fortran Defaults339942 |
| Node: Special Fortran Commands340327 |
| Node: Pascal340833 |
| Node: Modula-2341348 |
| Node: M2 Operators342323 |
| Node: Built-In Func/Proc345321 |
| Node: M2 Constants348182 |
| Node: M2 Types349783 |
| Node: M2 Defaults353002 |
| Node: Deviations353602 |
| Node: M2 Checks354703 |
| Node: M2 Scope355521 |
| Node: GDB/M2356545 |
| Node: Ada357457 |
| Node: Ada Mode Intro358256 |
| Node: Omissions from Ada360128 |
| Node: Additions to Ada364089 |
| Node: Stopping Before Main Program367987 |
| Node: Ada Glitches368519 |
| Node: Unsupported Languages370497 |
| Node: Symbols371187 |
| Node: Altering384686 |
| Node: Assignment385655 |
| Node: Jumping388760 |
| Node: Signaling390895 |
| Node: Returning392026 |
| Node: Calling393228 |
| Node: Patching395121 |
| Node: GDB Files396198 |
| Node: Files396739 |
| Ref: Shared Libraries409574 |
| Node: Separate Debug Files414970 |
| Node: Symbol Errors425593 |
| Node: Targets429196 |
| Node: Active Targets430676 |
| Node: Target Commands432255 |
| Node: Byte Order437495 |
| Node: Remote Debugging438472 |
| Node: Connecting439734 |
| Node: File Transfer444609 |
| Node: Server445549 |
| Ref: Monitor Commands for gdbserver452180 |
| Ref: Server-Footnote-1453039 |
| Node: Remote Configuration453159 |
| Ref: set remotebreak454183 |
| Ref: set remote hardware-watchpoint-limit455647 |
| Ref: set remote hardware-breakpoint-limit455647 |
| Ref: set remote exec-file455929 |
| Node: Remote Stub459207 |
| Node: Stub Contents462104 |
| Node: Bootstrapping464215 |
| Node: Debug Session468024 |
| Node: Configurations469584 |
| Node: Native470353 |
| Node: HP-UX470947 |
| Node: BSD libkvm Interface471236 |
| Node: SVR4 Process Information472307 |
| Node: DJGPP Native475737 |
| Node: Cygwin Native482317 |
| Node: Non-debug DLL Symbols485698 |
| Node: Hurd Native490244 |
| Node: Neutrino495507 |
| Node: Embedded OS495882 |
| Node: VxWorks496358 |
| Node: VxWorks Connection498575 |
| Node: VxWorks Download499509 |
| Node: VxWorks Attach501244 |
| Node: Embedded Processors501642 |
| Node: ARM502786 |
| Node: M32R/D505740 |
| Node: M68K507442 |
| Node: MIPS Embedded507738 |
| Node: OpenRISC 1000512683 |
| Node: PowerPC Embedded515538 |
| Node: PA517004 |
| Node: Sparclet517293 |
| Node: Sparclet File518777 |
| Node: Sparclet Connection519657 |
| Node: Sparclet Download520135 |
| Node: Sparclet Execution521184 |
| Node: Sparclite521775 |
| Node: Z8000522148 |
| Node: AVR523532 |
| Node: CRIS523895 |
| Node: Super-H524873 |
| Node: Architectures525115 |
| Node: i386525537 |
| Node: A29K526219 |
| Node: Alpha527058 |
| Node: MIPS527191 |
| Node: HPPA529815 |
| Node: SPU530334 |
| Node: PowerPC531578 |
| Node: Controlling GDB532156 |
| Node: Prompt532917 |
| Node: Editing533696 |
| Node: Command History534639 |
| Node: Screen Size538043 |
| Node: Numbers539748 |
| Node: ABI541725 |
| Node: Messages/Warnings544654 |
| Node: Debugging Output547147 |
| Node: Sequences551514 |
| Node: Define552125 |
| Node: Hooks555476 |
| Node: Command Files557667 |
| Node: Output561520 |
| Node: Interpreters566287 |
| Node: TUI568382 |
| Node: TUI Overview569349 |
| Node: TUI Keys571782 |
| Node: TUI Single Key Mode574086 |
| Node: TUI Commands574961 |
| Node: TUI Configuration577049 |
| Node: Emacs578345 |
| Node: GDB/MI583822 |
| Node: GDB/MI Command Syntax585644 |
| Node: GDB/MI Input Syntax585857 |
| Node: GDB/MI Output Syntax587411 |
| Node: GDB/MI Compatibility with CLI590829 |
| Node: GDB/MI Development and Front Ends591566 |
| Node: GDB/MI Output Records593487 |
| Node: GDB/MI Result Records593769 |
| Node: GDB/MI Stream Records594496 |
| Node: GDB/MI Out-of-band Records595767 |
| Node: GDB/MI Simple Examples597204 |
| Node: GDB/MI Command Description Format599013 |
| Node: GDB/MI Breakpoint Commands599893 |
| Node: GDB/MI Program Context616398 |
| Node: GDB/MI Thread Commands620880 |
| Node: GDB/MI Program Execution622956 |
| Node: GDB/MI Stack Manipulation631565 |
| Node: GDB/MI Variable Objects641196 |
| Ref: -var-list-children648208 |
| Ref: -var-update653163 |
| Ref: -var-set-frozen653977 |
| Node: GDB/MI Data Manipulation654700 |
| Node: GDB/MI Tracepoint Commands669062 |
| Node: GDB/MI Symbol Query669306 |
| Node: GDB/MI File Commands672594 |
| Node: GDB/MI Target Manipulation676847 |
| Node: GDB/MI File Transfer Commands684026 |
| Node: GDB/MI Miscellaneous Commands685348 |
| Ref: -interpreter-exec688492 |
| Node: Annotations690789 |
| Node: Annotations Overview691703 |
| Node: Server Prefix694166 |
| Node: Prompting694806 |
| Node: Errors696323 |
| Node: Invalidation697219 |
| Node: Annotations for Running697696 |
| Node: Source Annotations699216 |
| Node: GDB Bugs700141 |
| Node: Bug Criteria700868 |
| Node: Bug Reporting701745 |
| Node: Command Line Editing709368 |
| Node: Introduction and Notation710020 |
| Node: Readline Interaction711640 |
| Node: Readline Bare Essentials712829 |
| Node: Readline Movement Commands714616 |
| Node: Readline Killing Commands715579 |
| Node: Readline Arguments717497 |
| Node: Searching718539 |
| Node: Readline Init File720688 |
| Node: Readline Init File Syntax721751 |
| Node: Conditional Init Constructs733683 |
| Node: Sample Init File736214 |
| Node: Bindable Readline Commands739329 |
| Node: Commands For Moving740384 |
| Node: Commands For History741243 |
| Node: Commands For Text744365 |
| Node: Commands For Killing747089 |
| Node: Numeric Arguments749229 |
| Node: Commands For Completion750366 |
| Node: Keyboard Macros751908 |
| Node: Miscellaneous Commands752477 |
| Node: Readline vi Mode755836 |
| Node: Using History Interactively756753 |
| Node: History Interaction757268 |
| Node: Event Designators758690 |
| Node: Word Designators759623 |
| Node: Modifiers761260 |
| Node: Formatting Documentation762485 |
| Ref: Formatting Documentation-Footnote-1765814 |
| Node: Installing GDB765878 |
| Node: Requirements766387 |
| Ref: Expat766956 |
| Node: Running Configure767667 |
| Node: Separate Objdir771206 |
| Node: Config Names774090 |
| Node: Configure Options775535 |
| Node: Maintenance Commands777871 |
| Ref: maint info breakpoints778530 |
| Node: Remote Protocol788830 |
| Node: Overview789282 |
| Ref: Binary Data791469 |
| Node: Packets793728 |
| Ref: extended mode794810 |
| Ref: read registers packet797334 |
| Ref: cycle step packet798500 |
| Ref: write register packet800376 |
| Ref: step with signal packet801283 |
| Ref: X packet805989 |
| Ref: insert breakpoint or watchpoint packet806279 |
| Node: Stop Reply Packets808725 |
| Node: General Query Packets812284 |
| Ref: QPassSignals819327 |
| Ref: qSupported821402 |
| Ref: qXfer read829994 |
| Ref: qXfer auxiliary vector read830488 |
| Ref: qXfer target description read830837 |
| Ref: qXfer library list read831281 |
| Ref: qXfer memory map read831927 |
| Ref: qXfer spu read832316 |
| Ref: qXfer spu write834446 |
| Ref: General Query Packets-Footnote-1835736 |
| Node: Register Packet Format836063 |
| Node: Tracepoint Packets836981 |
| Node: Host I/O Packets843076 |
| Node: Interrupts847218 |
| Node: Examples848679 |
| Node: File-I/O Remote Protocol Extension849292 |
| Node: File-I/O Overview849754 |
| Node: Protocol Basics851903 |
| Node: The F Request Packet854135 |
| Node: The F Reply Packet855036 |
| Node: The Ctrl-C Message855954 |
| Node: Console I/O857583 |
| Node: List of Supported Calls858800 |
| Node: open859162 |
| Node: close861656 |
| Node: read862038 |
| Node: write862645 |
| Node: lseek863412 |
| Node: rename864290 |
| Node: unlink865686 |
| Node: stat/fstat866625 |
| Node: gettimeofday867512 |
| Node: isatty867947 |
| Node: system868543 |
| Node: Protocol-specific Representation of Datatypes870085 |
| Node: Integral Datatypes870462 |
| Node: Pointer Values871269 |
| Node: Memory Transfer871977 |
| Node: struct stat872597 |
| Node: struct timeval874799 |
| Node: Constants875316 |
| Node: Open Flags875765 |
| Node: mode_t Values876106 |
| Node: Errno Values876598 |
| Node: Lseek Flags877409 |
| Node: Limits877594 |
| Node: File-I/O Examples877954 |
| Node: Library List Format879070 |
| Node: Memory Map Format880938 |
| Node: Agent Expressions883471 |
| Node: General Bytecode Design886404 |
| Node: Bytecode Descriptions891204 |
| Node: Using Agent Expressions901890 |
| Node: Varying Target Capabilities903423 |
| Node: Tracing on Symmetrix904596 |
| Node: Rationale910418 |
| Node: Target Descriptions917797 |
| Node: Retrieving Descriptions919836 |
| Node: Target Description Format920921 |
| Node: Predefined Target Types927468 |
| Node: Standard Target Features928667 |
| Node: ARM Features930420 |
| Node: MIPS Features931039 |
| Node: M68K Features931983 |
| Node: PowerPC Features932646 |
| Node: Copying933586 |
| Node: GNU Free Documentation License952804 |
| Node: Index975239 |
| |
| End Tag Table |