Go to the previous, next section.

Stopping and Continuing

The principal purpose of using a debugger is so that you can stop your program before it terminates; or so that, if your program runs into trouble, you can investigate and find out why.

Inside _GDBN__, your program may stop for any of several reasons, such as a signal, a breakpoint, or reaching a new line after a _GDBN__ 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 _GDBN__ provide ample explanation of the status of your program--but you can also explicitly request this information at any time.

info program

Display information about the status of your program: whether it is running or not, what process it is, and why it stopped.

_if__(!_CONLY__)

Breakpoints, Watchpoints, and Exceptions

Breakpoints and Watchpoints

A breakpoint makes your program stop whenever a certain point in the program is reached. For each breakpoint, you can add various conditions to control in finer detail whether your program will stop. You can set breakpoints with the break command and its variants (see section Setting Breakpoints), to specify the place where your program should stop by line number, function name or exact address in the program. _if__(!_CONLY__) In languages with exception handling (such as GNU C++), you can also set breakpoints where an exception is raised (see section Breakpoints and Exceptions). _fi__(!_CONLY__)

A watchpoint is a special breakpoint that stops your program when the value of an expression changes. You must use a different command to set watchpoints (see section Setting Watchpoints), but aside from that, you can manage a watchpoint like any other breakpoint: you enable, disable, and delete both breakpoints and watchpoints using the same commands.

_GDBN__ assigns a number to each breakpoint or watchpoint when you create it; these numbers are successive integers starting with one. In many of the commands for controlling various features of breakpoints you use the breakpoint number to say which breakpoint you want to change. Each breakpoint may be enabled or disabled; if disabled, it has no effect on your program until you enable it again.

Setting Breakpoints

Breakpoints are set with the break command (abbreviated b). The debugger convenience variable `$bpnum' records the number of the beakpoint you've set most recently; see section Convenience Variables, for a discussion of what you can do with convenience variables.

You have several ways to say where the breakpoint should go.

break function

Set a breakpoint at entry to function function. _if__(!_CONLY__) When using source languages that permit overloading of symbols, such as C++, function may refer to more than one possible place to break. See section Breakpoint Menus, for a discussion of that situation. _fi__(!_CONLY__)

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 will stop your program just before it executes any of the code on that line.

break filename:linenum

Set a breakpoint at line linenum in source file filename.

break filename:function

Set a breakpoint at entry to function function found in file filename. Specifying a file name as well as a function name is superfluous except when multiple files contain similarly named functions.

break *address

Set a breakpoint at address address. You can use this to set breakpoints in parts of your program which do not have debugging information or source files.

break

When called without any arguments, break sets a breakpoint at the next instruction to be executed in the selected stack frame (see section Examining the Stack). In any selected frame but the innermost, this will cause your program to stop as soon as control returns to that frame. This is similar to the effect of a finish command in the frame inside the selected frame--except that finish does not leave an active breakpoint. If you use break without an argument in the innermost frame, _GDBN__ will stop the next time it reaches the current location; this may be useful inside loops.

_GDBN__ normally ignores breakpoints when it resumes execution, until at least one instruction has been executed. If it did not do this, you would be unable to proceed past a breakpoint without first disabling the breakpoint. This rule applies whether or not the breakpoint already existed when your program stopped.

break ... if cond

Set a breakpoint with condition cond; evaluate the expression cond each time the breakpoint is reached, and stop only if the value is nonzero--that is, if cond evaluates as true. `...' stands for one of the possible arguments described above (or no argument) specifying where to break. See section Break Conditions, for more information on breakpoint conditions.

tbreak args

Set a breakpoint enabled only for one stop. args are the same as for the break command, and the breakpoint is set in the same way, but the breakpoint is automatically disabled after the first time your program stops there. See section Disabling Breakpoints.

rbreak regex

Set breakpoints on all functions matching the regular expression regex. This command sets an unconditional breakpoint on all matches, printing a list of all breakpoints it set. Once these breakpoints are set, they are treated just like the breakpoints set with the break command. They can be deleted, disabled, made conditional, etc., in the standard ways.

_if__(!_CONLY__) When debugging C++ programs, rbreak is useful for setting breakpoints on overloaded functions that are not members of any special classes. _fi__(!_CONLY__)

info breakpoints [n]

info break [n]

info watchpoints [n]

Print a table of all breakpoints and watchpoints set and not deleted, with the following columns for each breakpoint:

Breakpoint Numbers

Type

Breakpoint or watchpoint.

Disposition

Whether the breakpoint is marked to be disabled or deleted when hit.

Enabled or Disabled

Enabled breakpoints are marked with `y'. `n' marks breakpoints that are not enabled.

Address

Where the breakpoint is in your program, as a memory address

What

Where the breakpoint is in the source for your program, as a file and line number.

Breakpoint commands, if any, are listed after the line for the corresponding breakpoint.

info break with a breakpoint number n as argument lists only that breakpoint. The convenience variable $_ and the default examining-address for the x command are set to the address of the last breakpoint listed (see section Examining Memory).

_GDBN__ allows you to set any number of breakpoints at the same place in your program. There is nothing silly or meaningless about this. When the breakpoints are conditional, this is even useful (see section Break Conditions).

_GDBN__ itself sometimes sets breakpoints in your program for special purposes, such as proper handling of longjmp (in C programs). These internal breakpoints are assigned negative numbers, starting with -1; `info breakpoints' does not display them.

You can see these breakpoints with the _GDBN__ 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 _GDBN__ is using for internal purposes. Internal breakpoints are shown with negative breakpoint numbers. The type column identifies what kind of breakpoint is shown:

breakpoint

Normal, explicitly set breakpoint.

watchpoint

Normal, explicitly set watchpoint.

longjmp

Internal breakpoint, used to handle correctly stepping through longjmp calls.

longjmp resume

Internal breakpoint at the target of a longjmp.

until

Temporary internal breakpoint used by the _GDBN__ until command.

finish

Temporary internal breakpoint used by the _GDBN__ finish command.

Setting Watchpoints

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

Watchpoints currently execute two orders of magnitude more slowly than other breakpoints, but this can well be worth it to catch errors where you have no clue what part of your program is the culprit. Some processors provide special hardware to support watchpoint evaluation; future releases of _GDBN__ will use such hardware if it is available.

watch expr

Set a watchpoint for an expression.

info watchpoints

This command prints a list of watchpoints and breakpoints; it is the same as info break.

Breakpoints and Exceptions

Some languages, such as GNU C++, implement exception handling. You can use _GDBN__ to examine what caused your program to raise an exception, and to list the exceptions your program is prepared to handle at a given point in time.

catch exceptions

You can set breakpoints at active exception handlers by using the catch command. exceptions is a list of names of exceptions to catch.

You can use info catch to list active exception handlers. See section Information About a Frame.

There are currently some limitations to exception handling in _GDBN__. These will be corrected in a future release.

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

Sometimes catch is not the best way to debug exception handling: if you need to know exactly where an exception is raised, it is better to