Appendix: Using GDB

GDB commands
Running programs under GDB
Stopping and continuing
Examining the stack
Examining source files
Examining data
Examining the symbol table
Altering execution

The Neutrino implementation of GDB includes some extensions:

target qnx: Set the target; see "Setting the target."
set qnxinheritenv: Set where the remote process inherits its environment from; see "Your program's environment."
set qnxremotecwd: Set the working directory for the remote process; see "Starting your program."
set qnxtimeout: 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.

To debug an application on a remote target, do the following:

Start GDB, but don't specify the application as an argument:
```
gdb
  
```
Load the symbol information for the application:
```
sym my_application
  
```

Set the target:

target qnx com_port_specifier | host:port | pty

Send the application to the target:

upload my_application /tmp/my_application

Start the application:
```
run /tmp/my_application
  
```

GDB commands

This section includes:

Command syntax
Command completion
Getting help

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:

gdb in the Utilities Reference
the GNU documentation for GDB

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:

Compiling for debugging
Setting the target
Starting your program
Your program's arguments
Your program's environment
Your program's input and output
Debugging an already-running process
Killing the child process
Debugging programs with multiple threads
Debugging programs with multiple processes

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 a child process.

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

When you start the debugger, you need to specify the target to use because the default target isn't supported:

target qnx com_port_specifier | host:port | pty

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

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

Here's a sample:

(gdb) target qnx 10.109:8000
Remote debugging using 10.109:8000
0x0 in ?? ()
(gdb) sym hello
Reading symbols from hello...done.
(gdb) run /local/src/test/hello
Starting program:  /local/src/test/hello
(gdb)

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

set qnxtimeout time

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

Starting your program

set qnxremotecwd 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."

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.

When you issue the run command, your program is loaded but doesn't execute immediately. Use the continue command to start your program. For more information, see "Stopping and continuing." While your program is stopped, you may call functions in your program, using the print or call commands. See "Examining data."

If the modification time of your symbol file has changed since the last time GDB read its symbols, GDB discards its symbol table and reads it again. When it does this, GDB tries to retain your current breakpoints.

Your program's arguments

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

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 qnxinheritenv 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; for more information, see the Utilities Reference.
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 child process

kill: Kill the child process in which your program is running under GDB.

This command is useful if you wish to debug a core dump instead of a running process. GDB ignores any core dump file while your program is running.

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 child 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:

thread threadno, a command to switch between threads
info threads, a command to inquire about existing threads
thread apply [threadno] [all] args, a command to apply a command to a list of threads
thread-specific breakpoints

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):

Thread number assigned by GDB
Target system's thread identifier (systag)
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:

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.
While the child is sleeping, use the pidin utility to get its process ID (for more information, see the Utilities Reference).
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:

Breakpoints, watchpoints, and exceptions
Continuing and stepping
Signals
Stopping and starting multithreaded programs

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:

Setting breakpoints
Setting watchpoints
Breakpoints and exceptions
Deleting breakpoints
Disabling breakpoints
Break conditions
Breakpoint command lists
Breakpoint menus

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:

Breakpoint Numbers.
Type -- breakpoint or watchpoint.
Disposition -- whether the breakpoint is marked to be disabled or deleted when hit.
Enabled or Disabled -- enabled breakpoints are marked with y, disabled with n.
Address -- where the breakpoint is in your program, as a memory address.
What -- where the breakpoint is in the source for your program, as a file and line number.

If a breakpoint is conditional, info break shows the condition on the line following the affected breakpoint; breakpoint commands, if any, are listed after that.

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:

breakpoint -- normal, explicitly set breakpoint.
watchpoint -- normal, explicitly set watchpoint.
longjmp -- internal breakpoint, used to handle correctly stepping through longjmp calls.
longjmp resume -- internal breakpoint at the target of a longjmp.
until -- temporary internal breakpoint used by the GDB until command.
finish -- temporary internal breakpoint used by the GDB finish command.

Setting watchpoints

You can use a watchpoint to stop execution whenever the value of an expression changes, without having to predict a particular place where this may happen.

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.

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:

If you call a function interactively, GDB normally returns control to you when the function has finished executing. If the call raises an exception, however, the call may bypass the mechanism that returns control to you and cause your program to continue running until it hits a breakpoint, catches a signal that GDB is listening for, or exits.
You can't raise an exception interactively.
You can't install an exception handler interactively.

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.

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:

Ignore signals like SIGALRM that don't indicate an error so as not to interfere with their role in the functioning of your program.
Stop your program immediately whenever an error signal happens.

You can change these settings with the handle command.

info signals info handle: Print a table of all the kinds of signals and how GDB has been told to handle each one. You can use this to see the signal numbers of all the defined types of signals.
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:

Stack frames
Backtraces
Selecting a frame
Information about a frame
MIPS machines and the function stack

When your program has stopped, the first thing you need to know is where it stopped and how it got there.

Each time your program performs a function call, information about the call is generated. That information includes the location of the call in your program, the arguments of the call, and the local variables of the function being called. The information is saved in a block of data called a stack frame. The stack frames are allocated in a region of memory called the call stack.

When your program stops, the GDB commands for examining the stack allow you to see all of this information.

One of the stack frames is selected by GDB, and many GDB commands refer implicitly to the selected frame. In particular, whenever you ask GDB for the value of a variable in your program, the value is found in the selected frame. There are special GDB commands to select whichever frame you'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 address of the frame
the address of the next frame down (called by this frame)
the address of the next frame up (caller of this frame)
the language in which the source code corresponding to this frame is written
the address of the frame's arguments
the program counter saved in it (the address of execution in the caller frame)
which registers were saved in the frame

The verbose description is useful when something has gone wrong that has made the stack format fail to fit the usual conventions.

info frame addr info f addr

Print a verbose description of the frame at address addr, without selecting that frame. The selected frame remains unchanged by this command. This requires the same kind of address (more than one for some architectures) that you specify in the frame command. 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:

Printing source lines
Searching source files
Specifying source directories
Source and machine code
Shared libraries

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.

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:

Use directory with no argument to reset the source path to empty.
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:

If value is nonzero, symbols from all shared object libraries are loaded automatically when the inferior process (i.e. the one being debugged) begins execution, or when the dynamic linker informs GDB that a new library has been loaded.
If value is zero, symbols must be loaded manually with the sharedlibrary command.

You can query the settings of these parameters with the show solib

Middleware, development tools, realtime operating systemsoftware and services for superior embedded design

Using GDB

Middleware, development tools, realtime operating system
software and services for superior embedded design