This is G o o g l e's cache of http://www.math.arizona.edu/computing/texinfo/gdb.html.
G o o g l e's cache is the snapshot that we took of the page as we crawled the web.
The page may have changed since that time. Click here for the current page without highlighting.
To link to or bookmark this page, use the following url: http://www.google.com/u/azmath?q=cache:1mFfc8aBInAJ:www.math.arizona.edu/computing/texinfo/gdb.html+gdb&hl=en&ie=UTF-8
Google is not affiliated with the authors of this page nor responsible for its content.
These search terms have been highlighted: gdb
Debugging with GDB
The GNU Source-Level Debugger
Edition 4.12, for GDB version 4.16
January 1994
Richard M. Stallman and Cygnus Support
Table of Contents
* Summary of GDB
o Free software
o Contributors to GDB
* A Sample GDB Session
* Getting In and Out of GDB
o Invoking GDB
+ Choosing files
+ Choosing modes
o Quitting GDB
o Shell commands
* GDB Commands
o Command syntax
o Command completion
o Getting help
* Running Programs Under GDB
o Compiling for debugging
o Starting your program
o Your program's arguments
o Your program's environment
o Your program's working directory
o Your program's input and output
o Debugging an already-running process
o Killing the child process
o Additional process information
o Debugging programs with multiple threads
o Debugging programs with multiple processes
* Stopping and Continuing
o Breakpoints, watchpoints, and exceptions
+ Setting breakpoints
+ Setting watchpoints
+ Breakpoints and exceptions
+ Deleting breakpoints
+ Disabling breakpoints
+ Break conditions
+ Breakpoint command lists
+ Breakpoint menus
o Continuing and stepping
o Signals
o Stopping and starting multi-thread programs
* Examining the Stack
o Stack frames
o Backtraces
o Selecting a frame
o Information about a frame
o MIPS machines and the function stack
* Examining Source Files
o Printing source lines
o Searching source files
o Specifying source directories
o Source and machine code
* Examining Data
o Expressions
o Program variables
o Artificial arrays
o Output formats
o Examining memory
o Automatic display
o Print settings
o Value history
o Convenience variables
o Registers
o Floating point hardware
* Using GDB with Different Languages
o Switching between source languages
+ List of filename extensions and languages
+ Setting the working language
+ Having GDB infer the source language
o Displaying the language
o Type and range checking
+ An overview of type checking
+ An overview of range checking
o Supported languages
+ C and C++
# C and C++ operators
# C and C++ constants
# C++ expressions
# C and C++ defaults
# C and C++ type and range checks
# GDB and C
# GDB features for C++
+ Modula-2
# Operators
# Built-in functions and procedures
# Constants
# Modula-2 defaults
# Deviations from standard Modula-2
# Modula-2 type and range checks
# The scope operators :: and .
# GDB and Modula-2
* Examining the Symbol Table
* Altering Execution
o Assignment to variables
o Continuing at a different address
o Giving your program a signal
o Returning from a function
o Calling program functions
o Patching programs
* GDB Files
o Commands to specify files
o Errors reading symbol files
* Specifying a Debugging Target
o Active targets
o Commands for managing targets
o Choosing target byte order
o Remote debugging
+ The GDB remote serial protocol
# What the stub can do for you
# What you must do for the stub
# Putting it all together
# Communication protocol
# Using the gdbserver program
# Using the gdbserve.nlm program
+ GDB with a remote i960 (Nindy)
# Startup with Nindy
# Options for Nindy
# Nindy reset command
+ The UDI protocol for AMD29K
+ The EBMON protocol for AMD29K
# Communications setup
# EB29K cross-debugging
# Remote log
+ GDB with a Tandem ST2000
+ GDB and VxWorks
# Connecting to VxWorks
# VxWorks download
# Running tasks
+ GDB and Hitachi microprocessors
# Connecting to Hitachi boards
# Using the E7000 in-circuit emulator
# Special GDB commands for Hitachi micros
+ GDB and remote MIPS boards
+ Simulated CPU target
* Controlling GDB
o Prompt
o Command editing
o Command history
o Screen size
o Numbers
o Optional warnings and messages
* Canned Sequences of Commands
o User-defined commands
o User-defined command hooks
o Command files
o Commands for controlled output
* Using GDB under GNU Emacs
* Reporting Bugs in GDB
o Have you found a bug?
o How to report bugs
* Command Line Editing
o Introduction to Line Editing
o Readline Interaction
+ Readline Bare Essentials
+ Readline Movement Commands
+ Readline Killing Commands
+ Readline Arguments
o Readline Init File
+ Readline Init Syntax
# Commands For Moving
# Commands For Manipulating The History
# Commands For Changing Text
# Killing And Yanking
# Specifying Numeric Arguments
# Letting Readline Type For You
# Some Miscellaneous Commands
+ Readline vi Mode
* Using History Interactively
o History Interaction
+ Event Designators
+ Word Designators
+ Modifiers
* Formatting Documentation
* Installing GDB
o Compiling GDB in another directory
o Specifying names for hosts and targets
o configure options
* Index
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
Published by the Free Software Foundation
59 Temple Place - Suite 330,
Boston, MA 02111-1307 USA
Printed copies are available for $20 each.
ISBN 1-882114-11-6
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.
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 or C++. For more information, see section C and C++.
Support for Modula-2 and Chill is partial. For information on Modula-2, see section Modula-2. There is no further documentation on Chill yet.
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 does not yet support entering expressions, printing values, or similar features using Fortran syntax. It may be necessary to refer to some variables with a trailing underscore.
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.
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 long labor as thankless, we particularly thank those who shepherded GDB through major releases: Stan Shebs (release 4.14), Fred Fish (releases 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). As major maintainer of GDB for some period, each contributed significantly to the structure, stability, and capabilities of the entire debugger.
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. 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 4 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.
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.
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 and Wind River Systems contributed remote debugging modules for their products.
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, Ltd. sponsored the support for Hitachi microprocessors.
Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware watchpoints.
Stu Grossman wrote gdbserver.
Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly innumerable bug fixes and cleanups throughout GDB.
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.
In this sample session, we emphasize user input like this: input, to make it easier to pick out from the surrounding output.
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 4.16, Copyright 1995 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
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.
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.
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.
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' 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' option followed by that argument.)
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
Connect to process ID number, as with the attach command (unless there is a file in core-dump format named number, in which case `-c' specifies that file as a core dump to read).
-command file
-x file
Execute GDB commands from file file. See section 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 `./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.
The -mapped and -readnow options are typically combined in order to build a `.syms' file that contains complete symbol information. (See section Commands to specify files, for information
a `.syms' file for future use is:
gdb -batch -nx -mapped -readnow programname
Choosing modes
You can run GDB in various alternative modes--for example, in batch mode or quiet mode.
-nx
-n
Do not execute commands from any initialization files (normally called `.gdbinit'). Normally, the commands in these files are executed after all the command options and arguments have been processed. See section Command files.
-quiet
-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.
-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.
-b bps
Set the line speed (baud rate or bits per second) of any serial interface used by GDB for remote debugging.
-tty device
Run using device for your program's standard input and output.
Quitting GDB
quit
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 (see section Debugging an already-running process).
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 the standard shell to execute command string. If it exists, the environment variable SHELL determines which shell to run. Otherwise GDB uses /bin/sh.
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'.
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).
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 command names 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 (see section 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 (see section Command files).
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.
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:
running -- Running the program
stack -- Examining the stack
data -- Examining data
breakpoints -- Making program stop at certain points
files -- Specifying and examining files
status -- Status inquiries
support -- Support facilities
user-defined -- User-defined commands
aliases -- Aliases of other commands
obscure -- Obscure features
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:
show -- Generic command for showing things set
with "set"
info -- Generic command for printing status
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.
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:
info
inspect
ignore
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. See section 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 expresson 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 occasionally want to determine which version of GDB you are running; as GDB evolves, new commands are introduced, and old ones may wither away. The version number is also announced when you start GDB.
show copying
Display information about permission for copying GDB.
show warranty
Display the GNU "NO WARRANTY" statement.
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. You may redirect your program's input and output, debug an already running process, or kill a child process.
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.
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.
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 (see section Getting In and Out of GDB), or by using the file or exec-file command (see section Commands to specify 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. See section Your program's 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. See section Your program's 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. See section Your program's 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. See section Your program's input and 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. See section Stopping and Continuing, 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. See section Examining 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.
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 /bin/sh.
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.
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), for both GDB and your program. You may specify several directory names, separated by `:' or whitespace. 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 a Unix 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: 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'.
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. See section Commands to specify files.
cd directory
Set the GDB working directory to directory.
pwd
Print the GDB working directory.
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.
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 using attach, you should first use the file command to specify the program running in the process and load its symbol table. See section Commands to specify 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 (see section Optional warnings and messages).
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).
Additional process information
Some operating systems provide a facility called `/proc' that can be used to examine the image of a running process using file-system subroutines. If GDB is configured for an operating system with this facility, the command info proc is available to report on several kinds of information about the process running your program. info proc works only on SVR4 systems that support procfs.
info proc
Summarize available information about the process.
info proc mappings
Report on the address ranges accessible in the program, with information on whether your program may read, write, or execute each range.
info proc times
Starting time, user CPU time, and system CPU time for your program and its children.
info proc id
Report on the process IDs related to your program: its own process ID, the ID of its parent, the process group ID, and the session ID.
info proc status
General information on the state of the process. If the process is stopped, this report includes the reason for stopping, and any signal received.
info proc all
Show all the above information about the process.
Debugging programs with multiple threads
In some operating systems, 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
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.
See section Stopping and starting multi-thread programs, for more information about how GDB behaves when you stop and start programs with multiple threads.
See section Setting watchpoints, for information about watchpoints in programs with multiple threads.
Debugging programs with multiple processes
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 (see section Debugging an already-running process). From that point on you can debug the child process just like any other process which you attached to.
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.
Breakpoints, watchpoints, and exceptions
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 (see section Setting breakpoints), to specify the place where your program should stop by line number, function name or exact address in the program. In languages with exception handling (such as GNU C++), you can also set breakpoints where an exception is raised (see section Breakpoints and exceptions).
In SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can now set breakpoints in shared libraries before the executable is run.
A watchpoint is a special breakpoint that stops your program when the value of an expression changes. You must use a different command to set watchpoints (see section Setting 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. See section Automatic display.
GDB assigns a number to each breakpoint or watchpoint 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.
Setting breakpoints
Breakpoints are set with the break command (abbreviated b). The debugger convenience variable `$bpnum' records the number of the breakpoints you've set most recently; see section Convenience variables, 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. See section 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 frame.
break linenum
Set a breakpoint at line linenum in the current source file. That file is the last file whose source text was printed. This breakpoint stops 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 (see section Examining the 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. See section Break 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. See section Disabling breakpoints.
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. DSU will generate traps when a program accesses some date or instruction address that is assigned to the debug registers. However the hardware breakpoint registers can only take two data breakpoints, and GDB will reject this command if more than two are used. Delete or disable usused hardware breakpoints before setting new ones. See section Break conditions.
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. See section Disabling breakpoints. Also See section Break 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. 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 and watchpoints set and not deleted, with the following columns for each breakpoint:
Breakpoint Numbers
Type
Breakpoint or watchpoint.
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
What
Where the breakpoint is in the source for your program, as a file and line number.
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. 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 (see section Examining memory). info break now 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 (see section Break conditions).
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'.
maint info breakpoints
Using the same format as `info breakpoints', display both the breakpoints you've set explicitly, and those GDB is using for internal purposes. Internal breakpoints are shown with negative breakpoint numbers. The type column identifies what kind of breakpoint is shown:
breakpoint
Normal, explicitly set breakpoint.
watchpoint
Normal, explicitly set watchpoint.
longjmp
Internal breakpoint, used to handle correctly stepping through longjmp calls.
longjmp resume
Internal breakpoint at the target of a longjmp.
until
Temporary internal breakpoint used by the GDB until command.
finish
Temporary internal breakpoint used by the GDB finish command.
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.
Watchpoints currently execute two orders of magnitude more slowly than other breakpoints, but this can be well worth it to catch errors where you have no clue what part of your program is the culprit.
watch expr
Set a watchpoint for an expression. GDB will break when expr is written into by the program and its value changes. This can be used with the new trap-generation provided by SPARClite DSU. DSU will generate traps when a program accesses some date 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. will reject the command if you try to mix watchpoints. Delete or disable unused watchpoint commands before setting new ones.
rwatch expr
Set a watchpoint that will break when watch args is read by the program. If you use both watchpoints, both must be set with the rwatch command.
awatch expr
Set a watchpoint that will break when args is read and written into by the program. If you use both watchpoints, both must be set with the awatch command.
info watchpoints
This command prints a list of watchpoints and breakpoints; it is the same as info break.
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.
Breakpoints and exceptions
Some languages, such as GNU C++, implement exception handling. You can use GDB to examine what caused your program to raise an exception, and to list the exceptions your program is prepared to handle at a given point in time.
catch exceptions
You can set breakpoints at active exception handlers by using the catch command. exceptions is a list of names of exceptions to catch.
You can use info catch to list active exception handlers. See section Information about a frame.
There are currently some limitations to exception handling 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 to simply continue running until it hits a breakpoint, catches a signal that GDB is listening for, or exits.
* 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 (see section Breakpoints, watchpoints, and exceptions).
With a conditional breakpoint (see section Break 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.
Deleting breakpoints
It is often necessary to eliminate a breakpoint or watchpoint 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 or watchpoints 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 (see section Selecting a frame). 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] [bnums...]
Delete the breakpoints or watchpoints of the numbers 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.
Disabling breakpoints
Rather than deleting a breakpoint or watchpoint, 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 and watchpoints 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 or watchpoints if you do not know which numbers to use.
A breakpoint or watchpoint 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. A breakpoint set with the tbreak command starts out in this state.
* Enabled for deletion. The breakpoint stops your program, but immediately after it does so it is deleted permanently.
You can use the following commands to enable or disable breakpoints and watchpoints:
disable [breakpoints] [bnums...]
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] [bnums...]
Enable the specified breakpoints (or all defined breakpoints). They become effective once again in stopping your program.
enable [breakpoints] once bnums...
Enable the specified breakpoints temporarily. GDB disables any of these breakpoints immediately after stopping your program.
enable [breakpoints] delete bnums...
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 (see section Setting breakpoints), 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 section Continuing and stepping.)
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 (see section 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 for the purpose of performing side effects when a breakpoint is reached (see section Breakpoint command lists).
Break conditions can be specified when a breakpoint is set, by using `if' in the arguments to the break command. See section Setting breakpoints. They can also be changed at any time with the condition command. The watch command does not recognize the if keyword; condition is the only way to impose a further condition on a watchpoint.
condition bnum expression
Specify expression as the break condition for breakpoint or watchpoint 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. GDB does not actually evaluate expression at the time the condition command is given, however. See section Expressions.
condition bnum
Remove the condition from breakpoint number bnum. It becomes an ordinary unconditional breakpoint. 