Breakpoints are set with the
break command (abbreviated
b). The debugger convenience variable ‘$bpnum’ records the
number of the breakpoint you've set most recently; see Convenience Variables, for a discussion of what you can do with
When using source languages that permit overloading of symbols, such as C++, a function name may refer to more than one possible place to break. See Ambiguous Expressions, for a discussion of that situation.
It is also possible to insert a breakpoint that will stop the program
only if a specific thread (see Thread-Specific Breakpoints)
or a specific task (see Ada Tasks) hits that breakpoint.
breaksets 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
finishcommand in the frame inside the selected frame—except that
finishdoes not leave an active breakpoint. If you use
breakwithout an argument in the innermost frame, gdb stops the next time it reaches the current location; this may be useful inside loops.
gdb normally ignores breakpoints when it resumes execution, until at
least one instruction has been executed. If it did not do this, you
would be unable to proceed past a breakpoint without first disabling the
breakpoint. This rule applies whether or not the breakpoint already
existed when your program stopped.
break ... ifcond
breakcommand, and the breakpoint is set in the same way, but the breakpoint is automatically deleted after the first time your program stops there. See Disabling Breakpoints.
breakcommand and the breakpoint is set in the same way, but the breakpoint requires hardware support and some target hardware may not have this support. The main purpose of this is EPROM/ROM code debugging, so you can set a breakpoint at an instruction without changing the instruction. This can be used with the new trap-generation provided by SPARClite DSU and most x86-based targets. These targets will generate traps when a program accesses some data or instruction address that is assigned to the debug registers. However the hardware breakpoint registers can take a limited number of breakpoints. For example, on the DSU, only two data breakpoints can be set at a time, and gdb will reject this command if more than two are used. Delete or disable unused hardware breakpoints before setting new ones (see Disabling Breakpoints). See Break Conditions. For remote targets, you can restrict the number of hardware breakpoints gdb will use, see set remote hardware-breakpoint-limit.
hbreakcommand and the breakpoint is set in the same way. However, like the
tbreakcommand, the breakpoint is automatically deleted after the first time your program stops there. Also, like the
hbreakcommand, the breakpoint requires hardware support and some target hardware may not have this support. See Disabling Breakpoints. See also Break Conditions.
breakcommand. You can delete them, disable them, or make them conditional the same way as any other breakpoint.
The syntax of the regular expression is the standard one used with tools
like grep. Note that this is different from the syntax used by
shells, so for instance
foo* matches all functions that include
fo followed by zero or more
os. There is an implicit
.* leading and trailing the regular expression you supply, so to
match only functions that begin with
When debugging C++ programs,
rbreak is useful for setting
breakpoints on overloaded functions that are not members of any special
rbreak command can be used to set breakpoints in
all the functions in a program, like this:
(gdb) rbreak .
rbreakis called with a filename qualification, it limits the search for functions matching the given regular expression to the specified file. This can be used, for example, to set breakpoints on every function in a given file:
(gdb) rbreak file.c:.
The colon separating the filename qualifier from the regex may optionally be surrounded by spaces.
If a breakpoint is conditional, there are two evaluation modes: “host” and
“target”. If mode is “host”, breakpoint condition evaluation is done by
gdb on the host's side. If it is “target”, then the condition
is evaluated by the target. The
info break command shows
the condition on the line following the affected breakpoint, together with
its condition evaluation mode in between parentheses.
Breakpoint commands, if any, are listed after that. A pending breakpoint is allowed to have a condition specified for it. The condition is not parsed for validity until a shared library is loaded that allows the pending breakpoint to resolve to a valid location.
info break with a breakpoint
number n as argument lists only that breakpoint. The
$_ and the default examining-address for
x command are set to the address of the last breakpoint
listed (see Examining Memory).
info break displays a count of the number of times the breakpoint
has been hit. This is especially useful in conjunction with the
ignore command. You can ignore a large number of breakpoint
hits, look at the breakpoint info to see how many times the breakpoint
was hit, and then run again, ignoring one less than that number. This
will get you quickly to the last hit of that breakpoint.
For a breakpoints with an enable count (xref) greater than 1,
info break also displays that count.
gdb allows you to set any number of breakpoints at the same place in your program. There is nothing silly or meaningless about this. When the breakpoints are conditional, this is even useful (see Break Conditions).
It is possible that a breakpoint corresponds to several locations in your program. Examples of this situation are:
In all those cases, gdb will insert a breakpoint at all the relevant locations.
A breakpoint with multiple locations is displayed in the breakpoint table using several rows—one header row, followed by one row for each breakpoint location. The header row has ‘<MULTIPLE>’ in the address column. The rows for individual locations contain the actual addresses for locations, and show the functions to which those locations belong. The number column for a location is of the form breakpoint-number.location-number.
Num Type Disp Enb Address What 1 breakpoint keep y <MULTIPLE> stop only if i==1 breakpoint already hit 1 time 1.1 y 0x080486a2 in void foo<int>() at t.cc:8 1.2 y 0x080486ca in void foo<double>() at t.cc:8
Each location can be individually enabled or disabled by passing
breakpoint-number.location-number as argument to the
disable commands. Note that you cannot
delete the individual locations from the list, you can only delete the
entire list of locations that belong to their parent breakpoint (with
the delete num command, where num is the number of
the parent breakpoint, 1 in the above example). Disabling or enabling
the parent breakpoint (see Disabling) affects all of the locations
that belong to that breakpoint.
It's quite common to have a breakpoint inside a shared library. Shared libraries can be loaded and unloaded explicitly, and possibly repeatedly, as the program is executed. To support this use case, gdb updates breakpoint locations whenever any shared library is loaded or unloaded. Typically, you would set a breakpoint in a shared library at the beginning of your debugging session, when the library is not loaded, and when the symbols from the library are not available. When you try to set breakpoint, gdb will ask you if you want to set a so called pending breakpoint—breakpoint whose address is not yet resolved.
After the program is run, whenever a new shared library is loaded, gdb reevaluates all the breakpoints. When a newly loaded shared library contains the symbol or line referred to by some pending breakpoint, that breakpoint is resolved and becomes an ordinary breakpoint. When a library is unloaded, all breakpoints that refer to its symbols or source lines become pending again.
This logic works for breakpoints with multiple locations, too. For example, if you have a breakpoint in a C++ template function, and a newly loaded shared library has an instantiation of that template, a new location is added to the list of locations for the breakpoint.
Except for having unresolved address, pending breakpoints do not differ from regular breakpoints. You can set conditions or commands, enable and disable them and perform other breakpoint operations.
gdb provides some additional commands for controlling what happens when the ‘break’ command cannot resolve breakpoint address specification to an address:
set breakpoint pending auto
set breakpoint pending on
set breakpoint pending off
show breakpoint pending
The settings above only affect the
break command and its
variants. Once breakpoint is set, it will be automatically updated
as shared libraries are loaded and unloaded.
For some targets, gdb can automatically decide if hardware or
software breakpoints should be used, depending on whether the
breakpoint address is read-only or read-write. This applies to
breakpoints set with the
break command as well as to internal
breakpoints set by commands like
breakpoints set with
hbreak, gdb will always use hardware
You can control this automatic behaviour with the following commands::
set breakpoint auto-hw on
set breakpoint auto-hw off
gdb normally implements breakpoints by replacing the program code at the breakpoint address with a special instruction, which, when executed, given control to the debugger. By default, the program code is so modified only when the program is resumed. As soon as the program stops, gdb restores the original instructions. This behaviour guards against leaving breakpoints inserted in the target should gdb abrubptly disconnect. However, with slow remote targets, inserting and removing breakpoint can reduce the performance. This behavior can be controlled with the following commands::
set breakpoint always-inserted off
set breakpoint always-inserted on
gdb handles conditional breakpoints by evaluating these conditions when a breakpoint breaks. If the condition is true, then the process being debugged stops, otherwise the process is resumed.
If the target supports evaluating conditions on its end, gdb may download the breakpoint, together with its conditions, to it.
This feature can be controlled via the following commands:
set breakpoint condition-evaluation host
set breakpoint condition-evaluation target
set breakpoint condition-evaluation auto
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,
-1; ‘info breakpoints’ does not display them.
You can see these breakpoints with the gdb maintenance command
‘maint info breakpoints’ (see maint info breakpoints).