Appendix: Using GDB

Neutrino-specific extensions

The Neutrino implementation of GDB includes some extensions:

target qnx
Set the target; see Setting the target.”
set nto-inherit-env
Set where the remote process inherits its environment from; see Your program's environment.”
set nto-cwd
Set the working directory for the remote process; see Starting your program.”
set nto-timeout
Set the timeout for remote reads; see Setting the target.”
upload local_path remote_path
Send a file to a remote target system.
download remote_path local_path
Retrieve a file from a remote target system.
info pidlist
Display a list of processes and their process IDs on the remote system
info meminfo
Display a list of memory-region mappings (shared objects) for the current process being debugged.

A quick overview of starting the debugger

To debug an application, do the following:

  1. Start GDB, but don't specify the application as an argument:
    gdb
      
  2. Load the symbol information for the application:
    file my_application
      
  3. If you're debugging remotely, set the target:
    target qnx com_port_specifier | host:port | pty
      
  4. If you're debugging remotely, send the application to the target:
    upload my_application /tmp/my_application
      
  5. Set any breakpoints. For example, to set a breakpoint in main():
    set break main
      
  6. Start the application:
    run
      

GDB commands

This section includes:

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 Enter. 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's more than one possibility).

You may also place GDB commands in an initialization file and these commands will be run before any that have been entered via the command line. For more information, see:

Command syntax

A GDB command is a single line of input. There's 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 that is the number of times to step, as in step 5. You can also use the step command with no arguments. Some command names don't 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 specifically 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 Enter) means to repeat the previous command. Certain commands (for example, run) don't repeat this way; these are commands whose unintentional repetition might cause trouble and which you're unlikely to want to repeat.

When you repeat the list and x commands with Enter, they construct new arguments rather than repeat exactly as typed. This permits easy scanning of source or memory.

GDB can also use Enter in another way: to partition lengthy output, in a way similar to the common utility more. Since it's easy to press one Enter 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. This is useful mainly in command files.

Command completion

GDB can fill in the rest of a word in a command for you if there's 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's only one possibility, GDB fills in the word, and waits for you to finish the command (or press Enter 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 Enter at this point, to run the info breakpoints command, or backspace and enter something else, if breakpoints doesn't look like the command you expected. (If you were sure you wanted info breakpoints in the first place, you might as well just type Enter immediately after info bre, to exploit command abbreviations rather than command completion).

If there's 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:

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 Esc followed by ? (rather than press Tab twice).

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 Esc followed by ?, to request word completion:

(gdb) b 'bubble(Esc?
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 don't 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 haven't 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 (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's 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 show in the index point to all the sub-commands.

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've 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 occasionally want to determine which version of GDB you're 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

This section includes:

To 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 the process being debugged.

Compiling for debugging

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.

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's 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. Don't be too surprised when the execution path doesn't 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 don't 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 — and include a test case.

Setting the target

If you're debugging locally, you don't need to specify the target (or you can specify target procfs).

If you're debugging remotely, you need to specify the target to use:

target qnx com_port_specifier | host:port | pty

The pty option spawns a pdebug server on the local machine and connects via a pty.


Note: The devc-pty manager must be running on the machine that's running pdebug, and a ptyp/ttyp pair must be available.

Starting your program

set nto-cwd path
Specify the remote process's working directory. You should do this before starting your program.
run
r
Use the run command to start your program under GDB. You must first specify the program name with an argument to GDB (see the description of the gdb utility).

The run creates an inferior process and makes that process run 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 affect your program the next time you start it.) This information may be divided into the following categories:

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 Your program's arguments/”
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 Your program's environment.”

Note: While input and output redirection work, you can't use pipes to pass the output of the program you're debugging to another program; if you attempt this, GDB is likely to wind up debugging the wrong program.

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.

Here's an example of starting a program for local debugging:

(gdb) file /tmp/helloworld
Reading symbols from /tmp/helloworld...done.
(gdb) b main
Breakpoint 1 at 0x804860c: file ./main.c, line 5.
(gdb) r
Starting program:
Remote: /tmp/helloworld

Breakpoint 1, main () at ./main.c:5
5       {
(gdb)

Here's an example of starting the program for remote debugging:

(gdb) target qnx mytst:8000
Remote debugging using mytst:8000
Remote target is little-endian
(gdb) file /tmp/helloworld
Reading symbols from /tmp/helloworld...done.
(gdb) upload /tmp/helloworld /tmp/helloworld
(gdb) b main
Breakpoint 1 at 0x804860c: file ./main.c, line 5.
(gdb) r
Starting program:
Remote: /tmp/helloworld

Breakpoint 1, main () at ./main.c:5
5       {
(gdb)

If your communication line is slow, you might need to set the timeout for remote reads:

set nto-timeout time

where time is the timeout, in seconds. The default is 10 seconds.

Your program's arguments

The arguments to your program can be specified by the arguments of the run command.

A run command 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've 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's 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're 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.

set nto-inherit-env value
If value is 0, the process inherits its environment from GDB. If value is 1 (the default), the process inherits its environment from pdebug.
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 a colon (:) or whitespace. If directory is already in the path, it's moved to the front, so it's searched sooner.

You can use the string $cwd to refer to the current working directory at the time GDB searches the path. A period (.) refers to the directory where you executed the path command. GDB replaces the period in the directory argument by 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 don't 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. The value may be any string; the values of environment variables are just strings, and any interpretation is supplied by your program itself. The value parameter is optional; if it's 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.
unset environment varname
Remove variable varname from the environment to be passed to your program. This is different from set env varname =, in that unset environment removes the variable from the environment, rather than assign it an empty value.

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.

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.

Debugging an already-running process

attach process-id
This command attaches to a running process—one that was started outside GDB. (The info files command shows your active targets.) The command takes as its argument a process ID. To find out a process ID, use the pidin utility (see the Utilities Reference), or use GDB's info pidlist command.

The attach command doesn't repeat if you press Enter a second time after executing the command.

To use attach, you must 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.

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 want the process to continue running, use the continue command after attaching GDB to the process.

detach
When you've 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're ready to attach another process or start one with run. The detach command doesn't repeat if you press Enter 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.

Killing the process being debugged

kill
Kill the process being debugged.

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.

The kill command is also useful if you wish to recompile and relink your program. With Neutrino, it's possible to modify an executable file while it's running in a process. If you want to run the new version, kill the current process; 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).

Debugging programs with multiple threads

In Neutrino, a single program may have more than one thread of execution. Each thread has its own registers and execution stack, and perhaps private memory.

GDB provides these facilities for debugging multithreaded programs:

The GDB thread debugging facility lets you 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.

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. Thread number assigned by GDB
  2. Target system's thread identifier (systag)
  3. 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 ()
thread apply [threadno] [all] args
The thread apply command lets you apply a command to one or more threads. Specify the numbers of the threads that you want affected with the command argument threadno. To apply a command to all threads, use thread apply all args.

Whenever GDB stops your program because of 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 Stopping and starting multithreaded programs for more information about how GDB behaves when you stop and start programs with multiple threads.

See Setting watchpoints for information about watchpoints in programs with multiple threads.

Debugging programs with multiple processes

GDB has no special support for debugging programs that create additional processes using the fork() function. When a program forks, GDB continues to debug the parent process, and the child process runs unimpeded. If you've set a breakpoint in any code that the child then executes, the child gets a SIGTRAP signal, which (unless it catches the signal) causes it to terminate.

However, if you want to debug the child process, there's a workaround that isn't too painful:

  1. Put a call to sleep() in the code that 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 doesn't occur when you don't want to run GDB on the child.
  2. While the child is sleeping, get its process ID by using the pidin utility (see the Utilities Reference) or by using GDB's info pidlist command.
  3. Tell GDB (a new invocation of GDB if you're also debugging the parent process) to attach to the child process (see Debugging an already-running process). From that point on you can debug the child process just like any other process that you've attached to.

Stopping and continuing

This section includes:

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's running or not, what process it is, and why it stopped.

Breakpoints, watchpoints, and exceptions

This section includes:

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 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 Breakpoints and exceptions).

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 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 Automatic display.”

GDB assigns a number to each breakpoint or watchpoint when you create it; these numbers are successive integers starting with 1. 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

Use the break (b) command to set breakpoints. The debugger convenience variable $bpnum records the number of the breakpoints you've set most recently; see 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. When using source languages such as C++ that permit overloading of symbols, function may refer to more than one possible place to break. See 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 found in file filename. Specifying a filename 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 that don't 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 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 doesn't 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 didn't do this, you wouldn't be able 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. The ellipsis (...) stands for one of the possible arguments described above (or no argument) specifying where to break. For more information on breakpoint conditions, see Break conditions.”

There are several variations on the break command, all using the same syntax as above:

tbreak
Set a breakpoint enabled only for one stop. The breakpoint is set in the same way as for the break command, except that it's automatically deleted after the first time your program stops there. See Disabling breakpoints.”
hbreak
Set a hardware-assisted breakpoint. The breakpoint is set in the same way as for the break command, except that it 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.

thbreak
Set a hardware-assisted breakpoint enabled only for one stop. The breakpoint is set in the same way as for the break command. 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, which some target hardware may not have. See Disabling breakpoints and 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're 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 aren't members of any special classes.

The following commands display information about breakpoints and watchpoints:

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:

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.

An info break command 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 Examining memory).

The info break command displays 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 information to see how many times the breakpoint was hit, and then run again, ignoring one less than that number. This gets you quickly to the last hit of that breakpoint.

GDB lets you set any number of breakpoints at the same place in your program. There's nothing silly or meaningless about this. When the breakpoints are conditional, this is even useful (see 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 doesn't 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. The type column identifies what kind of breakpoint is shown:

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.

Although watchpoints currently execute two orders of magnitude more slowly than other breakpoints, they can help catch errors where in cases where you have no clue what part of your program is the culprit.

watch expr
Set a watchpoint for an expression. GDB breaks when expr is written into by the program and its value changes.
rwatch arg
Set a watchpoint that breaks when watch arg is read by the program. If you use both watchpoints, both must be set with the rwatch command.
awatch arg
Set a watchpoint that breaks when arg 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's the same as info break.

Note: In multithreaded programs, watchpoints have only limited usefulness. With the current watchpoint implementation, GDB can watch the value of an expression in a single thread only. If you're confident that the expression can change due only to the current thread's activity (and if you're also confident that no other thread can become current), then you can use watchpoints as usual. However, GDB may not notice when a noncurrent 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. The exceptions argument is a list of names of exceptions to catch.

You can use info catch to list active exception handlers. See Information about a frame.”

There are currently some limitations to exception handling in GDB:

Sometimes catch isn't the best way to debug exception handling: if you need to know exactly where an exception is raised, it's 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:

void __raise_exception (void **addr, void *id);

/* addr is where the exception identifier is stored.
   id is the exception identifier.  */

To make the debugger catch all exceptions before any stack unwinding takes place, set a breakpoint on __raise_exception(). See Breakpoints, watchpoints, and exceptions.”

With a conditional breakpoint (see 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

You often need to eliminate a breakpoint or watchpoint once it's 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 and 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.

You don't have 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 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 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 for confirmation, unless you've set confirm off). You can abbreviate this command as d.

Disabling breakpoints

Rather than delete 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 don't know which numbers to use.

A breakpoint or watchpoint can have any of the following states:

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 afterwards it's 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 is listed. A disabled breakpoint has no effect but isn't 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 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 doesn't change the state of your other breakpoints; see 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 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's 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 Breakpoint command lists).

Break conditions can be specified when a breakpoint is set, by using if in the arguments to the break command. See Setting breakpoints.” They can also be changed at any time with the condition command. The watch command doesn't 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 doesn't actually evaluate expression at the time the condition command is given, however. See 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's 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 doesn't 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 doesn't stop; other than to decrement the ignore count, GDB takes no action.

To make the breakpoint stop the next time it's 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 use ignore. See Continuing and stepping.”

If a breakpoint has a positive ignore count and a condition, the condition isn't 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's decremented each time. See Convenience variables.”

Breakpoint command lists

You can give any breakpoint (or watchpoint) 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 or watchpoint set (not to the breakpoint most recently encountered).

Pressing Enter 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. Just use the continue command, or step, or any other command that resumes execution.

Commands in command-list that follow 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 isn't 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. The silent command 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.

For example, here's 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 doesn't stop, and start with the silent command so that no output is produced. Here's an example:

break 403
commands
silent
set x = y + 4
cont
end

Breakpoint menus

Some programming languages (notably 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 isn't 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)

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 due to a signal, you may want to use handle, or use signal 0 to resume execution. See 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 lets you specify a further number of times to ignore a breakpoint at this location; its effect is like that of ignore (see Break 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 are provided purely for convenience, and have exactly the same behavior as continue.

To resume execution at a different place, you can use return (see Returning from a function) to go back to the calling function; or jump (see Continuing at a different address) to go to an arbitrary location in your program.

A typical technique for using stepping is to set a breakpoint (see Breakpoints, watchpoints, and exceptions) 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.

Note: 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 doesn't step into a function that is compiled without debugging information. To step through functions without debugging information, use the stepi command, described below.

The step command stops only at the first instruction of a source line. This prevents multiple stops in switch statements, for loops, etc. The step command stops if a function that has debugging information is called within the line.

Also, the step command enters a subroutine only if there's line number information for the subroutine. Otherwise it acts like the next command. This avoids problems when using cc -gl on MIPS machines.

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.

The count argument is a repeat count, as for step.

The next command stops only at the first instruction of a source line. This prevents the multiple stops in switch statements, for loops, etc.

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 (see Returning from a function).

u
until
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's 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.

The until command always stops your program if it attempts to exit the current stack frame.

The until command may produce somewhat counterintuitive results if the order of machine code doesn't 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 hasn't really gone to an earlier statement—not in terms of the actual machine code.

An until command with no argument works by means of single instruction stepping, and hence is slower than until with an argument.

until location
u location
Continue running your program until either the specified location is reached, or the current stack frame returns. The location is any of the forms of argument acceptable to break (see Setting breakpoints). This form of the command uses breakpoints, and hence is quicker than until without an argument.
stepi [count]
si [count]
Execute one machine instruction, then stop and return to the debugger.

It's 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. See Automatic display.”

The count argument is a repeat count, as in step.

nexti [count]
ni [count]
Execute one machine instruction, but if it's a function call, proceed until the function returns.

The count argument is a repeat count, as in next.

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. The table below gives several examples of signals:

Signal: Received when:
SIGINT You type an interrupt, Ctrl-C
SIGSEGV The program references a place in memory far away from all the areas in use.
SIGALRM 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 (killing your program immediately) if the program hasn't specified in advance some other way to handle the signal. SIGINT doesn't indicate an error in your program, but it's 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, it's set up to:

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.
handle signal keywords...
Change the way GDB handles signal signal. The signal can be the number of a signal or its name (with or without the SIG at the beginning). The keywords say what change to make.

The keywords allowed by the handle command can be abbreviated. Their full names are:

nostop
GDB shouldn't 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 shouldn't mention the occurrence of the signal at all. This implies the nostop keyword as well.
pass
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.
nopass
GDB shouldn't allow your program to see this signal.

When a signal stops your program, the signal isn't visible 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.

You can also use the signal command to prevent your program from seeing a signal, or cause it to see a signal it normally doesn't 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. See Giving your program a signal.”

Stopping and starting multithreaded programs

When your program has multiple threads (see Debugging programs with multiple 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 ...
The 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 want GDB to stop the program only when a particular thread reaches this breakpoint. The threadno is one of the numeric thread identifiers assigned by GDB, shown in the first column of the info threads display.

If you don't 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 lets you examine the overall state of the program, including switching between threads, without worrying that things may change underfoot.

Conversely, whenever you restart the program, all threads start executing. This is true even when single-stepping with commands like step or next.

In particular, GDB can't single-step all threads in lockstep. Since thread scheduling is up to the Neutrino microkernel (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.

Examining the stack

This section includes:

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're interested in. See Selecting a frame.”

When your program stops, GDB automatically selects the currently executing frame and describes it briefly, similar to the frame command (see Information about a frame).

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 0 for the innermost frame, 1 for the frame that called it, and so on upward. These numbers don't really exist in your program; they're 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 reduce the time required to set up the frame. 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 0 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 lets you move from one stack frame to another, and to print the stack frame you select. The 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 lets you move from one stack frame to another without printing the frame. This is the silent version of frame.

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 0), followed by its caller (frame 1), and on up the stack.

backtrace
bt
Print a backtrace of the entire stack, with one line per frame, for all frames in the stack.

You can stop the backtrace at any time by typing the system interrupt character, normally Ctrl-C.

backtrace n
bt n
Similar, but print only the innermost n frames.
backtrace -n
bt -n
Similar, but print only the outermost n frames.

The names where and info stack ( 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 filename and line number, as well as the arguments to the function. The program counter value is omitted if it's at the beginning of the code for that line number.

Here's 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 0 doesn't begin with a program counter value, indicating that your program has stopped at the beginning of the code for line 993 of builtin.c.

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 0 is the innermost (currently executing) frame, frame 1 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 MIPS architecture, frame needs two addresses: a stack pointer and a program counter.

up n
Move n frames up the stack. For positive numbers, this advances toward the outermost frame, to higher frame numbers, to frames that have existed longer. The default for n is 1.
down n
Move n frames down the stack. For positive numbers, this advances toward the innermost frame, to lower frame numbers, to frames that were created more recently. The default for n is 1. 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. See Printing source lines.”

up-silently n
down-silently n
These two commands are variants of up and down; they differ in that they do their work silently, without causing display of the new frame. They're intended primarily for use in GDB command scripts, where the output might be unnecessary and distracting.

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 doesn't 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. See Selecting a frame.”
info frame
info f
This command prints a verbose description of the selected stack frame, including:

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. See Selecting a frame.”
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. See Breakpoints and exceptions.”

MIPS machines and the function stack

MIPS-based computers use an unusual stack frame, which sometimes requires GDB to search backward in the object code to find the beginning of a function.

To improve response time — especially for embedded applications, where GDB may be restricted to a slow serial line for this search — you may want to limit the size of this search, using one of these commands:

set heuristic-fence-post limit
Restrict GDB to examining at most limit bytes in its search for the beginning of a function. A value of 0 (the default) means there's no limit. However, except for 0, the larger the limit the more bytes heuristic-fence-post must search and therefore the longer it takes to run.
show heuristic-fence-post
Display the current limit.

These commands are available only when GDB is configured for debugging programs on MIPS processors.

Examining source files

This section includes:

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 (see Selecting a frame), GDB prints the line where execution in that frame has stopped. You can print other portions of source files by explicit command.

Printing source lines

To print lines from a source file, use the list (l) command. 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 (see Examining the 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 Enter discards the argument, so it's 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's 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 function in the file filename. You need the filename with a function name only to avoid ambiguity when there are identically named functions in different source files.
*address
Specifies the line containing the program address address. The address may be any expression.

Searching source files

The commands for searching through the current source file for a regular expression are:

forward-search regexp
search regexp
fo regexp
Check each line, starting with the one following the last line listed, for a match for regexp, listing the line found.
reverse-search regexp
rev regexp
Check each line, starting with the one before the last line listed and going backward, for a match for regexp, listing the line found.

Specifying source directories

Executable programs sometimes don't 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're present in the list, until it finds a file with the desired name.


Note: The executable search path isn't used for this purpose. Neither is the current working directory, unless it happens to be in the source path.

If GDB can't 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's 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 is empty. 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 colons (:) 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. Note that $cwd isn't the same as a period (.); 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.

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 (see Printing source lines).

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_changecom
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 (see Examining memory). Also, this address is saved as the value of the convenience variable $_ (see Convenience variables).

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.

We can use disassemble to inspect the object code range shown in the last info line example (the example shows SPARC machine instructions):

(gdb) disas 0x63e4 0x6404
Dump of assembler code from 0x63e4 to 0x6404:
0x63e4 <builtin_init+5340>:     ble 0x63f8 <builtin_init+5360>
0x63e8 <builtin_init+5344>:     sethi %hi(0x4c00), %o0
0x63ec <builtin_init+5348>:     ld [%i1+4], %o0
0x63f0 <builtin_init+5352>:     b 0x63fc <builtin_init+5364>
0x63f4 <builtin_init+5356>:     ld [%o0+4], %o0
0x63f8 <builtin_init+5360>:     or %o0, 0x1a4, %o0
0x63fc <builtin_init+5364>:     call 0x9288 <path_search>
0x6400 <builtin_init+5368>:     nop
End of assembler dump.
set assembly-language instruction-set
This command selects the instruction set to use when disassembling the program via the disassemble or x/i commands. It's useful for architectures that have more than one native instruction set.

Currently it's defined only for the Intel x86 family. You can set instruction-set to either i386 or i8086. The default is i386.

Shared libraries

You can use the following commands when working with shared libraries:

sharedlibrary [regexp]
Load shared object library symbols for files matching the given regular expression, regexp. If regexp is omitted, GDB tries to load symbols for all loaded shared libraries.
info sharedlibrary
Display the status of the loaded shared object libraries.

The following parameters apply to shared libraries:

set solib-search-path dir[:dir...]
Set the search path for loading shared library symbols files that don't have an absolute path. This path overrides the PATH and LD_LIBRARY_PATH environment variables.
set solib-absolute-prefix prefix
Set the prefix for loading absolute shared library symbol files.
set auto-solib-add value
Make the loading of shared library symbols automatic or manual:

You can query the settings of these parameters with the show solib-search-path, show solib-absolute-prefix, and show auto-solib-add commands.

Examining data

This section includes:

The usual way to examine data in your program is with the print (p) command or its synonym inspect. It evaluates and prints the value of an expression of the language your program is written in.

print exp
print /f exp
exp is an expression (in the source language). By default, the value of exp 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 Output formats.”
print
print /f
If you omit exp, GDB displays the last value again (from the value history; see Value history). This lets you conveniently inspect the same value in an alternative format.

A lower-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. See Examining memory.”

If you're interested in information about types, or about how the fields of a structure or class are declared, use the ptype exp command rather than print. See Examining the symbol table.”

Expressions

The print command 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're using is valid in an expression in GDB. This includes conditional expressions, function calls, casts and string constants. It unfortunately doesn't include symbols defined by preprocessor #define commands.

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'd in the target program.

Because C is so widespread, most of the expressions shown in examples in this manual are in C. 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's 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:

@
Binary operator for treating parts of memory as arrays. See Artificial arrays, for more information.
::
Lets you specify a variable in terms of the file or function where it's defined. See Program variables.”
{type} addr
Refers to an object of type type stored at address addr in memory. The 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.

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 (see Selecting a frame); they must be either:

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 use or examine the variable b only while your program is executing inside the block where b is declared.

There's an exception: you can refer to a variable or function whose scope is a single source file even if the current execution point isn't in this file. But it's 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 filenames, you can use quotes to make sure GDB parses the filename 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.


Note: Occasionally, a local variable may appear to have the wrong value at certain points in a function, such as just after entry to a new scope, and just before exit.

You may see this problem when you're 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're 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.


Artificial arrays

It's 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 operand. The first element is actually the left operand; the second element comes from bytes of memory immediately following those that hold the first element, and so on. For 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 (see Value history), after printing one out.

Another way to create an artificial array is to use a cast. This reinterprets 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). For example:

(gdb) p/x (short[])0x12345678
$2 = {0x1234, 0x5678}

Sometimes the artificial array mechanism isn't quite enough; in moderately complex data structures, the elements of interest may not actually be adjacent—for example, if you're interested in the values of pointers in an array. One useful workaround in this situation is to use a convenience variable (see Convenience variables) as a counter in an expression that prints the first interesting value, and then repeat that expression via Enter. For instance, suppose you have an array dtab of pointers to structures, and you're interested in the values of a field fv in each structure. Here's an example of what you might type:

set $i = 0
p dtab[$i++]->fv
Enter
Enter
...

Output formats

By default, GDB prints a value according to its data type. Sometimes this isn't 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. (The letter b can't be used because these format letters are also used with the x command, where b stands for byte. See Examining memory.”)
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>
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 (see Registers), type:

p/x $pc

Note: No space is required before the slash; this is because command names in GDB can't 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.

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.

The 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 is a decimal integer; the default is 1. It specifies how much memory (counting by units u) to display.
f
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 is any of:

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 isn't normally written.)

addr
The address where you want GDB to begin displaying memory. The expression need not have a pointer value (though it may); it's always interpreted as an integer address of a byte of memory. See 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. The x/4xw $sp command prints the four words (w) of memory above the stack pointer (here, $sp; see Registers) in hexadecimal (x).

Since the letters indicating unit sizes are all distinct from the letters specifying output formats, you don't 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 doesn't 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 Source and 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've inspected three machine instructions with x/3i addr, you can inspect the next seven with just x/7. If you use Enter 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 aren't saved in the value history because there's 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 isn't the same as the last address printed if several units were printed on the last line of output.

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 supported only by x; otherwise it uses print.

display exp
Add the expression exp to the list of expressions to display each time your program stops. See Expressions.” The display command doesn't repeat if you press Enter again after using it.
display/fmt exp
For fmt specifying only a display format and not a size or count, add the expression exp to the auto-display list but arrange to display it each time in the specified format fmt. See 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. See Examining 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; see Registers).

undisplay dnums...
delete display dnums...
Remove item numbers dnums from the list of expressions to display.

The undisplay command doesn't repeat if you press Enter after using it. (Otherwise you'd just get the error No display number ....)

disable display dnums...
Disable the display of item numbers dnums. A disabled display item isn't printed automatically, but isn't forgotten; it may be enabled again later.
enable display dnums...
Enable the 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 that wouldn't be displayed right now because they refer to automatic variables not currently available.

If a display expression refers to local variables, it doesn't 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 isn't 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 where there's 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.

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
Don't 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 doesn't uniquely identify the address (for example, it's 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 filename and line number of a symbol in the symbolic form of an address.
set print symbol-filename off
Don't print source filename and line number of a symbol. This is the default.
show print symbol-filename
Show whether or not GDB prints the source filename and line number of a symbol in the symbolic form of an address.

Another situation where it's helpful to show symbol filenames and line numbers is when disassembling code; GDB shows you the line number and source file that correspond 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 display the symbolic form of an address only 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 aren't 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>

Note: For pointers that point to a local variable, p/a doesn't 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 prints. 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. 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 prints. If the number is 0, 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.
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're 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 lets you use 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 that are contained in structures. This is the default setting.
set print union off
Tell GDB not to print unions that are contained in structures.
show print union
Ask GDB whether or not it prints unions that 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 prints:

$1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}}

and with set print union off in effect, it prints:

$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:
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.
lucid
Decode based on the Lucid C++ compiler (lcc) encoding algorithm.
arm
Decode using the algorithm in the C++ Annotated Reference Manual.

This setting alone isn't sufficient to allow debugging cfront-generated executables. GDB would require further enhancement to permit that.

foo
Show the list of 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
Don't 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.
set print vtbl off
Don't pretty print C++ virtual function tables.
show print vtbl
Show whether C++ virtual function tables are pretty printed, or not.

Value history

Values printed by the print command are saved in the GDB value history. This lets you refer to them in other expressions. Values are kept until the symbol table is reread 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, which you can use to refer to them. These are successive integers starting with 1. The print command 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 Enter.


Note: 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 doesn't 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 Enter to repeat show values n has exactly the same effect as show values +.

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 aren't part of your program, and setting a convenience variable has no direct effect on further execution of your program. That's why you can use them freely.

Convenience variables are prefixed with $. Any name preceded by $ can be used for a convenience variable, unless it's one of the predefined machine-specific register names (see Registers). Value history references, in contrast, are numbers preceded by $. See Value history.”

You can save a value in a convenience variable with an assignment expression, just as you'd set a variable in your program. For example:

set $foo = *object_ptr

saves 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 to 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 con.

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 pressing Enter.

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 (see Examining memory). Other commands that 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's 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.

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 registers (in the selected stack frame).
info all-registers
Print the names and values of all registers, including floating-point registers.
info registers regname ...
Print the value of each specified register regname. As discussed in detail below, register values are normally relative to the selected stack frame. The regname may be any register name valid on the machine you're using, with or without the initial $.

GDB has four “standard” register names that are available (in expressions) on most machines—whenever they don't conflict with an architecture's canonical mnemonics for registers:

$pc
Program counter.
$sp
Stack pointer.
$fp
A register that contains a pointer to the current stack frame.
$ps
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 with:

set $sp += 4

Note: 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 isn't allowed when other stack frames are selected. To pop entire frames off the stack, regardless of machine architecture, use the Enter key.

Whenever possible, these four standard register names are available on your machine even though the machine has different canonical mnemonics, so long as there's no conflict. The info registers command shows the canonical names.

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 that can hold nothing but floating point; these registers are considered to have floating point values. There's 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 isn't 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 (see Selecting a frame). 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 aren't saved, or if GDB is unable to locate the saved registers, the selected stack frame makes no difference.

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 x86 machines.

Examining the symbol table

The commands described in this section allow you to inquire about the symbols (names of variables, functions and types) defined in your program. This information is inherent in the text of your program and doesn't change as your program executes. GDB finds it in your program's symbol table, in the file indicated when you started GDB (see the description of the gdb utility).

Occasionally, you may need to refer to symbols that contain unusual characters, which GDB ordinarily treats as word delimiters. The most frequent case is in referring to static variables in other source files (see Program variables). Filenames are recorded in object files as debugging symbols, but GDB ordinarily parses a typical filename, like foo.c, as the three words foo, ., and c. To allow GDB to recognize foo.c as a single symbol, enclose it in single quotes. For example:

p 'foo.c'::x

looks up the value of x in the scope of the file foo.c.

info address symbol
Describe where the data for symbol is stored. For a register variable, this says which register it's kept in. For a nonregister local variable, this prints the stack-frame offset at which the variable is always stored.

Note the contrast with print &symbol, which doesn't work at all for a register variable, and for a stack local variable prints the exact address of the current instantiation of the variable.

whatis exp
Print the data type of expression exp. The exp expression isn't actually evaluated, and any side-effecting operations (such as assignments or function calls) inside it don't take place. See Expressions.”
whatis
Print the data type of $, the last value in the value history.
ptype typename
Print a description of data type typename, which may be the name of a type, or for C code it may have the form:
ptype exp
ptype
Print a description of the type of expression exp. The ptype command differs from whatis by printing a detailed description, instead of just the name of the type. For example, for this variable declaration:
struct complex {double real; double imag;} v;

the two commands give this output:

(gdb) whatis v
type = struct complex
(gdb) ptype v
type = struct complex {
    double real;
    double imag;
}

As with whatis, using ptype without an argument refers to the type of $, the last value in the value history.

info types regexp
info types
Print a brief description of all types whose name matches regexp (or all types in your program, if you supply no argument). Each complete typename is matched as though it were a complete line; thus, i type value gives information on all types in your program whose name includes the string value, but i type ^value$ gives information only on types whose complete name is value.

This command differs from ptype in two ways: first, like whatis, it doesn't print a detailed description; second, it lists all source files where a type is defined.

info source
Show the name of the current source file—that is, the source file for the function containing the current point of execution—and the language it was written in.
info sources
Print the names of all source files in your program for which there is debugging information, organized into two lists: files whose symbols have already been read, and files whose symbols are read when needed.
info functions
Print the names and data types of all defined functions.
info functions regexp
Print the names and data types of all defined functions whose names contain a match for regular expression regexp. Thus, info fun step finds all functions whose names include step; info fun ^step finds those whose names start with step.
info variables
Print the names and data types of all variables that are declared outside of functions (i.e. excluding local variables).
info variables regexp
Print the names and data types of all variables (except for local variables) whose names contain a match for regular expression regexp.

Some systems allow individual object files that make up your program to be replaced without stopping and restarting your program. If you're running on one of these systems, you can allow GDB to reload the symbols for automatically relinked modules:

maint print symbols filename
maint print psymbols filename
maint print msymbols filename
Write a dump of debugging symbol data into the file filename. These commands are used to debug the GDB symbol-reading code. Only symbols with debugging data are included.

Altering execution

This section includes:

Once you think you've found an error in your program, you might want to find out for certain whether correcting the apparent error would lead to correct results in the rest of the run. You can find the answer by experimenting, using the GDB features for altering execution of the program.

For example, you can store new values in variables or memory locations, give your program a signal, restart it at a different address, or even return prematurely from a function.

Assignment to variables

To alter the value of a variable, evaluate an assignment expression. See Expressions. For example,

print x=4

stores the value 4 in the variable x and then prints the value of the assignment expression (which is 4).

If you aren't interested in seeing the value of the assignment, use the set command instead of the print command. The set command is really the same as print except that the expression's value isn't printed and isn't put in the value history (see Value history). The expression is evaluated only for its effects.

If the beginning of the argument string of the set command appears identical to a set subcommand, use the set variable command instead of just set. This command is identical to set except for its lack of subcommands. For example, if your program has a variable width, you get an error if you try to set a new value with just set width=13, because GDB has the command set width:

(gdb) whatis width
type = double
(gdb) p width
$4 = 13
(gdb) set width=47
Invalid syntax in expression.

The invalid expression, of course, is =47. In order to actually set the program's variable width, use:

(gdb) set var width=47

GDB allows more implicit conversions in assignments than C; you can freely store an integer value into a pointer variable or vice versa, and you can convert any structure to any other structure that is the same length or shorter.

To store values into arbitrary places in memory, use the {...} construct to generate a value of specified type at a specified address (see Expressions). For example, {int}0x83040 refers to memory location 0x83040 as an integer (which implies a certain size and representation in memory), and:

set {int}0x83040 = 4

stores the value 4 in that memory location.

Continuing at a different address

Ordinarily, when you continue your program, you do so at the place where it stopped, with the continue command. You can instead continue at an address of your own choosing, with the following commands:

jump linespec
Resume execution at line linespec. Execution stops again immediately if there's a breakpoint there. See Printing source lines for a description of the different forms of linespec.

The jump command doesn't change the current stack frame, or the stack pointer, or the contents of any memory location or any register other than the program counter. If line linespec is in a different function from the one currently executing, the results may be bizarre if the two functions expect different patterns of arguments or of local variables. For this reason, the jump command requests confirmation if the specified line isn't in the function currently executing. However, even bizarre results are predictable if you're well acquainted with the machine-language code of your program.

jump *address
Resume execution at the instruction at address.

You can get much the same effect as the jump command by storing a new value in the register $pc. The difference is that this doesn't start your program running; it only changes the address of where it will run when you continue. For example:

set $pc = 0x485

makes the next continue command or stepping command execute at address 0x485, rather than at the address where your program stopped. See Continuing and stepping.”

The most common occasion to use the jump command is to back up — perhaps with more breakpoints set — over a portion of a program that has already executed, in order to examine its execution in more detail.

Giving your program a signal

signal signal
Resume execution where your program stopped, but immediately give it the given signal. The signal can be the name or number of a signal. For example, on many systems signal 2 and signal SIGINT are both ways of sending an interrupt signal.

Alternatively, if signal is zero, continue execution without giving a signal. This is useful when your program stopped on account of a signal and would ordinary see the signal when resumed with the continue command; signal 0 causes it to resume without a signal.

The signal command doesn't repeat when you press Enter a second time after executing the command.

Invoking the signal command isn't the same as invoking the kill utility from the shell. Sending a signal with kill causes GDB to decide what to do with the signal depending on the signal handling tables (see Signals). The signal command passes the signal directly to your program.

Returning from a function

return
return expression
You can cancel the execution of a function call with the return command. If you give an expression argument, its value is used as the function's return value.

When you use return, GDB discards the selected stack frame (and all frames within it). You can think of this as making the discarded frame return prematurely. If you wish to specify a value to be returned, give that value as the argument to return.

This pops the selected stack frame (see Selecting a frame) and any other frames inside it, leaving its caller as the innermost remaining frame. That frame becomes selected. The specified value is stored in the registers used for returning values of functions.

The return command doesn't resume execution; it leaves the program stopped in the state that would exist if the function had just returned. In contrast, the finish command (see Continuing and stepping) resumes execution until the selected stack frame returns naturally.

Calling program functions

call expr
Evaluate the expression expr without displaying void returned values.

You can use this variant of the print command if you want to execute a function from your program, but without cluttering the output with void returned values. If the result isn't void, it's printed and saved in the value history.

A user-controlled variable, call_scratch_address, specifies the location of a scratch area to be used when GDB calls a function in the target. This is necessary because the usual method of putting the scratch area on the stack doesn't work in systems that have separate instruction and data spaces.

Patching programs

By default, GDB opens the file containing your program's executable code (or the core file) read-only. This prevents accidental alterations to machine code; but it also prevents you from intentionally patching your program's binary.

If you'd like to be able to patch the binary, you can specify that explicitly with the set write command. For example, you might want to turn on internal debugging flags, or even to make emergency repairs.

set write on
set write off
If you specify set write on, GDB opens executable and core files for both reading and writing; if you specify set write off (the default), GDB opens them read-only.

If you've already loaded a file, you must load it again (using the exec-file or core-file command) after changing set write for your new setting to take effect.

show write
Display whether executable files and core files are opened for writing as well as reading.