gdb: Set Breaks
5.1.1 Setting Breakpoints
-------------------------
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
Convenience Vars, for a discussion of what you can do with convenience
variables.
'break LOCATION'
Set a breakpoint at the given LOCATION, which can specify a
function name, a line number, or an address of an instruction.
(Specify Location, for a list of all the possible ways to
specify a LOCATION.) The breakpoint will stop your program just
before it executes any of the code in the specified LOCATION.
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. Ambiguous Expressions Ambiguous
Expressions, for a discussion of that situation.
It is also possible to insert a breakpoint that will stop the
Breakpoints::) or a specific task (Ada Tasks) hits that
breakpoint.
'break'
When called without any arguments, 'break' sets a breakpoint at the
next instruction to be executed in the selected stack frame (
Examining the Stack Stack.). In any selected frame but the
innermost, this makes your program stop as soon as control returns
to that frame. This is similar to the effect of a 'finish' command
in the frame inside the selected frame--except that 'finish' does
not leave an active breakpoint. If you use 'break' without an
argument in the innermost frame, GDB stops the next time it reaches
the current location; this may be useful inside loops.
GDB normally ignores breakpoints when it resumes execution, until
at least one instruction has been executed. If it did not do this,
you would be unable to proceed past a breakpoint without first
disabling the breakpoint. This rule applies whether or not the
breakpoint already existed when your program stopped.
'break ... if COND'
Set a breakpoint with condition COND; evaluate the expression COND
each time the breakpoint is reached, and stop only if the value is
nonzero--that is, if COND evaluates as true. '...' stands for one
of the possible arguments described above (or no argument)
specifying where to break. Break Conditions Conditions, for
more information on breakpoint conditions.
'tbreak ARGS'
Set a breakpoint enabled only for one stop. The ARGS are the same
as for the 'break' command, and the breakpoint is set in the same
way, but the breakpoint is automatically deleted after the first
time your program stops there. Disabling Breakpoints
Disabling.
'hbreak ARGS'
Set a hardware-assisted breakpoint. The ARGS are the same as for
the 'break' command and the breakpoint is set in the same way, but
the breakpoint requires hardware support and some target hardware
may not have this support. The main purpose of this is EPROM/ROM
code debugging, so you can set a breakpoint at an instruction
without changing the instruction. This can be used with the new
trap-generation provided by SPARClite DSU 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 (Disabling
Breakpoints Disabling.). Break Conditions Conditions. For
remote targets, you can restrict the number of hardware breakpoints
GDB will use, see set remote hardware-breakpoint-limit.
'thbreak ARGS'
Set a hardware-assisted breakpoint enabled only for one stop. The
ARGS are the same as for the 'hbreak' command and the breakpoint is
set in the same way. However, like the 'tbreak' command, the
breakpoint is automatically deleted after the first time your
program stops there. Also, like the 'hbreak' command, the
breakpoint requires hardware support and some target hardware may
not have this support. Disabling Breakpoints Disabling.
See also Break Conditions Conditions.
'rbreak REGEX'
Set breakpoints on all functions matching the regular expression
REGEX. This command sets an unconditional breakpoint on all
matches, printing a list of all breakpoints it set. Once these
breakpoints are set, they are treated just like the breakpoints set
with the 'break' command. You can delete them, disable them, or
make them conditional the same way as any other breakpoint.
In programs using different languages, GDB chooses the syntax to
print the list of all breakpoints it sets according to the 'set
language' value: using 'set language auto' (see Set Language
Automatically Automatically.) means to use the language of the
breakpoint's function, other values mean to use the manually
specified language (see Set Language Manually Manually.).
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 an 'fo' followed by zero or more 'o's. There is an
implicit '.*' leading and trailing the regular expression you
supply, so to match only functions that begin with 'foo', use
'^foo'.
When debugging C++ programs, 'rbreak' is useful for setting
breakpoints on overloaded functions that are not members of any
special classes.
The 'rbreak' command can be used to set breakpoints in *all* the
functions in a program, like this:
(gdb) rbreak .
'rbreak FILE:REGEX'
If 'rbreak' is 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.
'info breakpoints [LIST...]'
'info break [LIST...]'
Print a table of all breakpoints, watchpoints, and catchpoints set
and not deleted. Optional argument N means print information only
about the specified breakpoint(s) (or watchpoint(s) or
catchpoint(s)). For each breakpoint, following columns are
printed:
_Breakpoint Numbers_
_Type_
Breakpoint, watchpoint, or catchpoint.
_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.
For a pending breakpoint whose address is not yet known, this
field will contain '<PENDING>'. Such breakpoint won't fire
until a shared library that has the symbol or line referred by
breakpoint is loaded. See below for details. A breakpoint
with several locations will have '<MULTIPLE>' in this
field--see below for details.
_What_
Where the breakpoint is in the source for your program, as a
file and line number. For a pending breakpoint, the original
string passed to the breakpoint command will be listed as it
cannot be resolved until the appropriate shared library is
loaded in the future.
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 convenience variable '$_' and the default
examining-address for the 'x' command are set to the address of the
last breakpoint listed (Examining Memory 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 (Break
Conditions Conditions.).
It is possible that a breakpoint corresponds to several locations in
your program. Examples of this situation are:
* Multiple functions in the program may have the same name.
* For a C++ constructor, the GCC compiler generates several instances
of the function body, used in different cases.
* For a C++ template function, a given line in the function can
correspond to any number of instantiations.
* For an inlined function, a given source line can correspond to
several places where that function is inlined.
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.
For example:
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
You cannot delete the individual locations from a breakpoint.
However, each location can be individually enabled or disabled by
passing BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the 'enable'
and 'disable' commands. It's also possible to 'enable' and 'disable' a
range of LOCATION-NUMBER locations using a BREAKPOINT-NUMBER and two
LOCATION-NUMBERs, in increasing order, separated by a hyphen, like
'BREAKPOINT-NUMBER.LOCATION-NUMBER1-LOCATION-NUMBER2', in which case GDB
acts on all the locations in the range (inclusive). Disabling or
enabling the parent breakpoint (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'
This is the default behavior. When GDB cannot find the breakpoint
location, it queries you whether a pending breakpoint should be
created.
'set breakpoint pending on'
This indicates that an unrecognized breakpoint location should
automatically result in a pending breakpoint being created.
'set breakpoint pending off'
This indicates that pending breakpoints are not to be created. Any
unrecognized breakpoint location results in an error. This setting
does not affect any pending breakpoints previously created.
'show breakpoint pending'
Show the current behavior setting for creating pending breakpoints.
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 'next' and 'finish'. For breakpoints set with 'hbreak',
GDB will always use hardware breakpoints.
You can control this automatic behaviour with the following commands:
'set breakpoint auto-hw on'
This is the default behavior. When GDB sets a breakpoint, it will
try to use the target memory map to decide if software or hardware
breakpoint must be used.
'set breakpoint auto-hw off'
This indicates GDB should not automatically select breakpoint type.
If the target provides a memory map, GDB will warn when trying to
set software breakpoint at a read-only address.
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'
All breakpoints, including newly added by the user, are inserted in
the target only when the target is resumed. All breakpoints are
removed from the target when it stops. This is the default mode.
'set breakpoint always-inserted on'
Causes all breakpoints to be inserted in the target at all times.
If the user adds a new breakpoint, or changes an existing
breakpoint, the breakpoints in the target are updated immediately.
A breakpoint is removed from the target only when breakpoint itself
is deleted.
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'
This option commands GDB to evaluate the breakpoint conditions on
the host's side. Unconditional breakpoints are sent to the target
which in turn receives the triggers and reports them back to GDB
for condition evaluation. This is the standard evaluation mode.
'set breakpoint condition-evaluation target'
This option commands GDB to download breakpoint conditions to the
target at the moment of their insertion. The target is responsible
for evaluating the conditional expression and reporting breakpoint
stop events back to GDB whenever the condition is true. Due to
limitations of target-side evaluation, some conditions cannot be
evaluated there, e.g., conditions that depend on local data that is
only known to the host. Examples include conditional expressions
involving convenience variables, complex types that cannot be
handled by the agent expression parser and expressions that are too
long to be sent over to the target, specially when the target is a
remote system. In these cases, the conditions will be evaluated by
GDB.
'set breakpoint condition-evaluation auto'
This is the default mode. If the target supports evaluating
breakpoint conditions on its end, GDB will download breakpoint
conditions to the target (limitations mentioned previously apply).
If the target does not support breakpoint condition evaluation,
then GDB will fallback to evaluating all these conditions on the
host's side.
GDB itself sometimes sets breakpoints in your program for special
purposes, such as proper handling of 'longjmp' (in C programs). These
internal breakpoints are assigned negative numbers, starting with '-1';
'info breakpoints' does not display them. You can see these breakpoints
with the GDB maintenance command 'maint info breakpoints' (maint
info breakpoints).
Info Catalog
gdb: Breakpoints
gdb: Set Watchpoints