gdb.info: Set Watchpoints

Go forward to Set Catchpoints
Go backward to Set Breaks
Go up to Breakpoints
Go to the top op gdb

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.
   Depending on your system, watchpoints may be implemented in software
or hardware.  GDB does software watchpointing by single-stepping your
program and testing the variable's value each time, which is hundreds of
times slower than normal execution.  (But this may still be worth it, to
catch errors where you have no clue what part of your program is the
culprit.)
   On some systems, such as HP-UX, GNU/Linux and some other x86-based
targets, GDB includes support for hardware watchpoints, which do not
slow down the running of your program.
`watch EXPR'
     Set a watchpoint for an expression.  GDB will break when EXPR is
     written into by the program and its value changes.
`rwatch EXPR'
     Set a watchpoint that will break when watch EXPR is read by the
     program.
`awatch EXPR'
     Set a watchpoint that will break when EXPR is either read or
     written into by the program.
`info watchpoints'
     This command prints a list of watchpoints, breakpoints, and
     catchpoints; it is the same as `info break'.
   GDB sets a "hardware watchpoint" if possible.  Hardware watchpoints
execute very quickly, and the debugger reports a change in value at the
exact instruction where the change occurs.  If GDB cannot set a
hardware watchpoint, it sets a software watchpoint, which executes more
slowly and reports the change in value at the next statement, not the
instruction, after the change occurs.
   When you issue the `watch' command, GDB reports
     Hardware watchpoint NUM: EXPR
if it was able to set a hardware watchpoint.
   Currently, the `awatch' and `rwatch' commands can only set hardware
watchpoints, because accesses to data that don't change the value of
the watched expression cannot be detected without examining every
instruction as it is being executed, and GDB does not do that
currently.  If GDB finds that it is unable to set a hardware breakpoint
with the `awatch' or `rwatch' command, it will print a message like
this:
     Expression cannot be implemented with read/access watchpoint.
   Sometimes, GDB cannot set a hardware watchpoint because the data
type of the watched expression is wider than what a hardware watchpoint
on the target machine can handle.  For example, some systems can only
watch regions that are up to 4 bytes wide; on such systems you cannot
set hardware watchpoints for an expression that yields a
double-precision floating-point number (which is typically 8 bytes
wide).  As a work-around, it might be possible to break the large region
into a series of smaller ones and watch them with separate watchpoints.
   If you set too many hardware watchpoints, GDB might be unable to
insert all of them when you resume the execution of your program.
Since the precise number of active watchpoints is unknown until such
time as the program is about to be resumed, GDB might not be able to
warn you about this when you set the watchpoints, and the warning will
be printed only when the program is resumed:
     Hardware watchpoint NUM: Could not insert watchpoint
If this happens, delete or disable some of the watchpoints.
   The SPARClite DSU will generate traps when a program accesses some
data or instruction address that is assigned to the debug registers.
For the data addresses, DSU facilitates the `watch' command.  However
the hardware breakpoint registers can only take two data watchpoints,
and both watchpoints must be the same kind.  For example, you can set
two watchpoints with `watch' commands, two with `rwatch' commands, *or*
two with `awatch' commands, but you cannot set one watchpoint with one
command and the other with a different command.  GDB will reject the
command if you try to mix watchpoints.  Delete or disable unused
watchpoint commands before setting new ones.
   If you call a function interactively using `print' or `call', any
watchpoints you have set will be inactive until GDB reaches another
kind of breakpoint or the call completes.
   GDB automatically deletes watchpoints that watch local (automatic)
variables, or expressions that involve such variables, when they go out
of scope, that is, when the execution leaves the block in which these
variables were defined.  In particular, when the program being debugged
terminates, _all_ local variables go out of scope, and so only
watchpoints that watch global variables remain set.  If you rerun the
program, you will need to set all such watchpoints again.  One way of
doing that would be to set a code breakpoint at the entry to the `main'
function and when it breaks, set all the watchpoints.
     _Warning:_ In multi-thread programs, watchpoints have only limited
     usefulness.  With the current watchpoint implementation, GDB can
     only watch the value of an expression _in a single thread_.  If
     you are confident that the expression can only change due to the
     current thread's activity (and if you are also confident that no
     other thread can become current), then you can use watchpoints as
     usual.  However, GDB may not notice when a non-current thread's
     activity changes the expression.
     _HP-UX Warning:_ In multi-thread programs, software watchpoints
     have only limited usefulness.  If GDB creates a software
     watchpoint, it can only watch the value of an expression _in a
     single thread_.  If you are confident that the expression can only
     change due to the current thread's activity (and if you are also
     confident that no other thread can become current), then you can
     use software watchpoints as usual.  However, GDB may not notice
     when a non-current thread's activity changes the expression.
     (Hardware watchpoints, in contrast, watch an expression in all
     threads.)
   *Note set remote hardware-watchpoint-limit::.