diff options
Diffstat (limited to 'contrib/gdb/gdb/doc/gdb.info-1')
| -rw-r--r-- | contrib/gdb/gdb/doc/gdb.info-1 | 7636 |
1 files changed, 7636 insertions, 0 deletions
diff --git a/contrib/gdb/gdb/doc/gdb.info-1 b/contrib/gdb/gdb/doc/gdb.info-1 new file mode 100644 index 0000000..decf454 --- /dev/null +++ b/contrib/gdb/gdb/doc/gdb.info-1 @@ -0,0 +1,7636 @@ +This is gdb.info, produced by makeinfo version 4.6 from ./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.1.1. + + Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, +1998, +1999, 2000, 2001, 2002, 2003, 2004 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 Free Software Foundation's Back-Cover Text is: "You have +freedom to copy and modify this GNU Manual, like GNU software. Copies +published by the Free Software Foundation raise funds for GNU +development." + + +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.1.1. + + Copyright (C) 1988-2004 Free Software Foundation, Inc. + +* 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 +* TUI:: GDB Text User Interface +* Interpreters:: Command Interpreters +* Emacs:: Using GDB under GNU Emacs +* Annotations:: GDB's annotation interface. +* GDB/MI:: GDB's Machine Interface. + +* GDB Bugs:: Reporting bugs in GDB +* Formatting Documentation:: How to format and print GDB documentation + +* Command Line Editing:: Command Line Editing +* Using History Interactively:: Using History Interactively +* Installing GDB:: Installing GDB +* Maintenance Commands:: Maintenance Commands +* Remote Protocol:: GDB Remote Serial Protocol +* Agent Expressions:: The GDB Agent Expression Mechanism +* 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: Support. 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.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. + + Jim Blandy added support for preprocessor macros, while working for +Red Hat. + + +File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top + +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 + C-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.1.1, 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: + + C-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 + +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 `C-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 + +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 + + +File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB + +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 `./', eg. `./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. + +`-c NUMBER' + +`-pid NUMBER' +`-p NUMBER' + Connect to process ID NUMBER, as with the `attach' command. If + there is no such process, GDB will attempt to open a core file + named NUMBER. + +`-command FILE' +`-x FILE' + Execute GDB commands from file FILE. *Note Command files: Command + Files. + +`-directory DIRECTORY' +`-d DIRECTORY' + Add DIRECTORY to the path to search for source files. + +`-m' +`-mapped' + _Warning: this option depends on operating system facilities that + are not supported on all systems._ + If memory-mapped files are available on your system through the + `mmap' system call, you can use this option to have GDB write the + symbols from your program into a reusable file in the current + directory. If the program you are debugging is called + `/tmp/fred', the mapped symbol file is `/tmp/fred.syms'. Future + GDB debugging sessions notice the presence of this file, and can + quickly map in symbol information from it, rather than reading the + symbol table from the executable program. + + The `.syms' file is specific to the host machine where GDB is run. + It holds an exact image of the internal GDB symbol table. It + cannot be shared across multiple host platforms. + +`-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. + + + You typically combine the `-mapped' and `-readnow' options in order +to build a `.syms' file that contains complete symbol information. +(*Note Commands to specify files: Files, for information on `.syms' +files.) A simple GDB invocation to do nothing but build a `.syms' file +for future use is: + + gdb -batch -nx -mapped -readnow programname + + +File: gdb.info, Node: Mode Options, Prev: File Options, Up: Invoking GDB + +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. + +`-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 superseeded by GDB/MI + (*note GDB/MI::). + +`-async' + Use the asynchronous event loop for the command-line interface. + GDB processes all events, such as user keyboard input, via a + special event loop. This allows GDB to accept and process user + commands in parallel with the debugged process being run(1), so + you don't need to wait for control to return to GDB before you + type the next command. (_Note:_ as of version 5.1, the target + side of the asynchronous operation is not yet in place, so + `-async' does not work fully yet.) + + When the standard input is connected to a terminal device, GDB + uses the asynchronous event loop by default, unless disabled by the + `-noasync' option. + +`-noasync' + Disable the asynchronous event loop for the command-line interface. + +`--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. + +`-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 GDBN 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. + + + ---------- Footnotes ---------- + + (1) GDB built with DJGPP tools for MS-DOS/MS-Windows supports this +mode of operation, but the event loop is suspended when the debuggee +runs. + + +File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation + +Quitting GDB +============ + +`quit [EXPRESSION]' +`q' + To exit GDB, use the `quit' command (abbreviated `q'), or type an + end-of-file character (usually `C-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 `C-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 + +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 + +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 + +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 + +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. + + 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 `C-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 + +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 + +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 ARGS' 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 list the arguments given to your + program 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' + Display information about permission for copying GDB. + +`show 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 + +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 + + +File: gdb.info, Node: Compilation, Next: Starting, Up: Running + +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. + + 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 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. + + Many C 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 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!). + + 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. + + +File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running + +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. + + +File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running + +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 + +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 + +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. + + +File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running + +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. + + +File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running + +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 or use the `run' command while you have an attached +process, 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 + +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 + +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 + + _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 LynxOS, you might +see + + [New process 35 thread 27] + +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 + +`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] ARGS' + The `thread apply' command allows you to apply a command to one or + more threads. Specify the numbers of the threads that you want + affected with the command argument THREADNO. THREADNO is the + internal GDB thread number, as shown in the first field of the + `info threads' display. To apply a command to all threads, use + `thread apply all' ARGS. + + 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, Prev: Threads, Up: Running + +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 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. + + 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: Stopping, Next: Stack, Prev: Running, Up: Top + +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 + +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. + + In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, 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. 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 breakpoint +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 + +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. + + You have several ways to say where the breakpoint should go. + +`break FUNCTION' + Set a breakpoint at entry to function FUNCTION. When using source + languages that permit overloading of symbols, such as C++, + FUNCTION may refer to more than one possible place to break. + *Note Breakpoint menus: Breakpoint Menus, for a discussion of that + situation. + +`break +OFFSET' +`break -OFFSET' + Set a breakpoint some number of lines forward or back from the + position at which execution stopped in the currently selected + "stack frame". (*Note Frames: Frames, for a description of stack + frames.) + +`break LINENUM' + Set a breakpoint at line LINENUM in the current source file. The + current source file is the last file whose source text was printed. + The breakpoint will stop your program just before it executes any + of the code on that line. + +`break FILENAME:LINENUM' + Set a breakpoint at line LINENUM in source file FILENAME. + +`break FILENAME:FUNCTION' + Set a breakpoint at entry to function FUNCTION found in file + FILENAME. Specifying a file name as well as a function name is + superfluous except when multiple files contain similarly named + functions. + +`break *ADDRESS' + Set a breakpoint at address ADDRESS. You can use this to set + breakpoints in parts of your program which do not have debugging + information or source files. + +`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 some 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: Disabling.). *Note Break conditions: Conditions. + *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. + +`info breakpoints [N]' +`info break [N]' +`info watchpoints [N]' + Print a table of all breakpoints, watchpoints, and catchpoints set + and not deleted, with the following columns for each breakpoint: + + _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. + If the breakpoint is pending (see below for details) on a + future load of a shared library, the address will be listed + as `<PENDING>'. + + _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.). + + If a specified breakpoint location cannot be found, it may be due to +the fact that the location is in a shared library that is yet to be +loaded. In such a case, you may want GDB to create a special +breakpoint (known as a "pending breakpoint") that attempts to resolve +itself in the future when an appropriate shared library gets loaded. + + Pending breakpoints are useful to set at the start of your GDB +session for locations that you know will be dynamically loaded later by +the program being debugged. When shared libraries are loaded, a check +is made to see if the load resolves any pending breakpoint locations. +If a pending breakpoint location gets resolved, a regular breakpoint is +created and the original pending breakpoint is removed. + + GDB provides some additional commands for controlling pending +breakpoint support: + +`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. + + Normal breakpoint operations apply to pending breakpoints as well. +You may specify a condition for a pending breakpoint and/or commands to +run when the breakpoint is reached. You can also enable or disable the +pending breakpoint. When you specify a condition for a pending +breakpoint, the parsing of the condition will be deferred until the +point where the pending breakpoint location is resolved. Disabling a +pending breakpoint tells GDB to not attempt to resolve the breakpoint +on any subsequent shared library load. When a pending breakpoint is +re-enabled, GDB checks to see if the location is already resolved. +This is done because any number of shared library loads could have +occurred since the time the breakpoint was disabled and one or more of +these loads could resolve the location. + + 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 + +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. + + 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, GNU/Linux and some other x86-based +targets, GDB includes support for hardware watchpoints, which do not +slow down the running of your program. + +`watch EXPR' + Set a watchpoint for an expression. GDB will break when EXPR is + written into by the program and its value changes. + +`rwatch EXPR' + Set a watchpoint that will break when watch EXPR is read by the + program. + +`awatch EXPR' + Set a watchpoint that will break when EXPR is either read 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'. + + 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. + + 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. + + 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. + + _Warning:_ In multi-thread programs, watchpoints have only limited + usefulness. With the current watchpoint implementation, GDB 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 watchpoints as + usual. However, GDB may not notice when a non-current thread's + activity changes the expression. + + _HP-UX Warning:_ In multi-thread 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 + +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. + + `exec' + A call to `exec'. This is currently only available for HP-UX. + + `fork' + A call to `fork'. This is currently only available for HP-UX. + + `vfork' + A call to `vfork'. This is currently only available for + HP-UX. + + `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 + +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 FUNCTION' +`clear FILENAME:FUNCTION' + Delete any breakpoints set at entry to the function FUNCTION. + +`clear LINENUM' +`clear FILENAME:LINENUM' + Delete any breakpoints set at or within the code of the specified + line. + +`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 + +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. + + 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. + + 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 + +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 + +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 + +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. If you realize this is a problem, you can use +something like `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 + +"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 + +"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 + +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. + +`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 of argument acceptable to `break' (*note Setting + breakpoints: Set Breaks.). This form of the command uses + 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, anything of the same form as arguments for + the `break' command. 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 + +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 `C-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 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. The KEYWORDS 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 + +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, 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 + +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 + +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" 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 + +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 `C-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. + + The names `where' and `info stack' (abbreviated `info s') are +additional aliases for `backtrace'. + + 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'. + + 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'. 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 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. + + +File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack + +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 + +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 + +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 +* 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: Edit, Up: Source + +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. + + 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, 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. + +`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. + + Here are the ways of specifying a single source line--all the kinds +of linespec. + +`NUMBER' + Specifies line NUMBER of the current source file. When a `list' + command has two linespecs, this refers to the same source file as + the first linespec. + +`+OFFSET' + Specifies the line OFFSET lines after the last line printed. When + used as the second linespec in a `list' command that has two, this + specifies the line OFFSET lines down from the first linespec. + +`-OFFSET' + Specifies the line OFFSET lines before the last line printed. + +`FILENAME:NUMBER' + Specifies line NUMBER 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 of the open-brace 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 line containing the program address ADDRESS. + ADDRESS may be any expression. + + +File: gdb.info, Node: Edit, Next: Search, Prev: List, Up: Source + +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. + + Here are the forms of the `edit' command most commonly used: + +`edit' + Edit the current source file at the active line number in the + program. + +`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. + +`edit FILENAME:NUMBER' + Specifies line NUMBER in the source file FILENAME. + +`edit 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. + +`edit *ADDRESS' + Specifies the line containing the program address ADDRESS. + ADDRESS may be any expression. + +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 designates the active line in the +file. + + +File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source + +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 + +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. Note that the executable search path is _not_ used for this +purpose. Neither is the current working directory, unless it happens +to be in the source path. + + If GDB cannot find a source file in the source path, and the object +program records a directory, GDB tries that directory too. If the +source path is empty, and there is no record of the compilation +directory, GDB looks in the current directory as a last resort. + + 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. + +`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 empty again. This requires confirmation. + +`show directories' + Print the source path: show which directories it contains. + + 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 empty. + + 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 + +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 understood by the `list' command (*note Printing source + lines: List.). + + 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. + +`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. + + +File: gdb.info, Node: Data, Next: Macros, Prev: Source, Up: Top + +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 +* Auxiliary Vector:: Auxiliary data provided by operating system +* Memory Region Attributes:: Memory region attributes +* Dump/Restore Files:: Copy between memory and a file +* Character Sets:: Debugging programs that use a different + character set than GDB does + + +File: gdb.info, Node: Expressions, Next: Variables, Up: Data + +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 + +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 GNU CC: (gcc.info)Debugging +Options. + + +File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data + +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 + +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. + +`f' + Regard the bits of the value as a floating point number and print + using typical floating point syntax. + + 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 + +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', `s' + (null-terminated string), or `i' (machine instruction). 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. +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. + + +File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data + +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 on how elaborate your format +specification is--it uses `x' if you specify a unit size, or one of the +two formats (`i' and `s') that are only supported by `x'; 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 + +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 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 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. + +`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. This + is the default setting. + +`set print union off' + Tell GDB not to print unions which are contained in structures. + +`show print union' + Ask GDB whether or not it will print unions which are contained in + structures. + + 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 = {...}} + +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 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 + +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 + +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'. + + 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 + +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. + + 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 + +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: Auxiliary Vector, Prev: Floating Point Hardware, Up: Data + +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: Auxiliary Vector, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data + +Operating system auxiliary vector +================================= + +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. + +`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: Auxiliary Vector, Up: Data + +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. + + 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 memory region bounded by LOWER and UPPER with attributes + ATTRIBUTES.... Note that UPPER == 0 is a special case: it is + treated as the the target's maximum memory address. (0xffff on 16 + bit targets, 0xffffffff on 32 bit targets, etc.) + +`delete mem NUMS...' + Remove memory regions NUMS.... + +`disable mem NUMS...' + Disable memory regions NUMS.... A disabled memory region is not + forgotten. It may be enabled again later. + +`enable mem NUMS...' + Enable 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. + +Attributes +---------- + +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. + +Memory Access Size +.................. + +The acccess size attributes 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. + +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. + + +File: gdb.info, Node: Dump/Restore Files, Next: Character Sets, Prev: Memory Region Attributes, Up: Data + +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 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: Character Sets, Prev: Dump/Restore Files, Up: Data + +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: Remote.) 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: Macros, Next: Tracepoints, Prev: Data, Up: Top + +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. + + + 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 + +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. + + 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 + +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 Experiment:: + + +File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints + +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 + +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 + +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 + +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 Experiment, Prev: Tracepoint Actions, Up: Set Tracepoints + +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 Experiment, Prev: Listing Tracepoints, Up: Set Tracepoints + +Starting and Stopping Trace Experiment +-------------------------------------- + +`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 + +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 + +`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 + +`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 + +`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 + +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 + +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 + +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 + +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 + +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 + +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 + +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 +* Support:: Supported languages +* Unsupported languages:: Unsupported languages + + +File: gdb.info, Node: Setting, Next: Show, Up: Languages + +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 + +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. + +`.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 + +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 + +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 + +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' + Set source files with extension .EXT to be assumed to be in the + source language LANGUAGE. + +`info extensions' + List all the filename extensions and the associated languages. + + +File: gdb.info, Node: Checks, Next: Support, Prev: Show, Up: Languages + +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: Support, 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 + +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: Support, 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: Support, 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 + +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: Support, 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: Support, 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: Support, Next: Unsupported languages, Prev: Checks, Up: Languages + +Supported languages +=================== + +GDB supports C, C++, Objective-C, Fortran, Java, assembly, and Modula-2. +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 +* Modula-2:: Modula-2 + + +File: gdb.info, Node: C, Next: Objective-C, Up: Support + +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 GNU CC: (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++ + + +File: gdb.info, Node: C Operators, Next: C Constants, Up: C + +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)' (or, if + you prefer, simply `&&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. + +* Menu: + +* C Constants:: + + +File: gdb.info, Node: C Constants, Next: C plus plus expressions, Prev: C Operators, Up: C + +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. + +* Menu: + +* C plus plus expressions:: +* C Defaults:: +* C Checks:: + +* Debugging C:: + + +File: gdb.info, Node: C plus plus expressions, Next: C Defaults, Prev: C Constants, Up: C + +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 + +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 + +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 + +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. + +* Menu: + +* Debugging C plus plus:: + + +File: gdb.info, Node: Debugging C plus plus, Prev: Debugging C, Up: C + +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. + +`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: Objective-C, Next: Modula-2, Prev: C, Up: Support + +Objective-C +----------- + +This section provides information about some commands and command +options that are useful for debugging Objective-C code. + +* 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, Prev: Objective-C, Up: Objective-C + +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 + +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: Modula-2, Prev: Objective-C, Up: Support + +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 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 + +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:_ Sets 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 + +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. + +`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. + |
