5.1.2 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. (This is sometimes called a data breakpoint.) The expression may be as simple as the value of a single variable, or as complex as many variables combined by operators. Examples include:

• A reference to the value of a single variable.
• An address cast to an appropriate data type. For example, ‘*(int *)0x12345678’ will watch a 4-byte region at the specified address (assuming an int occupies 4 bytes).
• An arbitrarily complex expression, such as ‘a*b + c/d’. The expression can use any operators valid in the program's native language (see section Using No value for GDBN with Different Languages).

Depending on your system, watchpoints may be implemented in software or hardware. No value for GDBN 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 most other x86-based targets, No value for GDBN includes support for hardware watchpoints, which do not slow down the running of your program.

watch expr

Set a watchpoint for an expression. No value for GDBN will break when the expression expr is written into by the program and its value changes. The simplest (and the most popular) use of this command is to watch the value of a single variable:

(No value for GDBP) watch foo

rwatch expr

Set a watchpoint that will break when the value of expr is read by the program.

awatch expr

Set a watchpoint that will break when expr is either read from 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 (see section Setting Breakpoints).

No value for GDBN 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 No value for GDBN 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.

You can force No value for GDBN to use only software watchpoints with the set can-use-hw-watchpoints 0 command. With this variable set to zero, No value for GDBN will never try to use hardware watchpoints, even if the underlying system supports them. (Note that hardware-assisted watchpoints that were set before setting can-use-hw-watchpoints to zero will still use the hardware mechanism of watching expression values.)

set can-use-hw-watchpoints

Set whether or not to use hardware watchpoints.

show can-use-hw-watchpoints

Show the current mode of using hardware watchpoints.

For remote targets, you can restrict the number of hardware watchpoints No value for GDBN will use, see set remote hardware-breakpoint-limit.

When you issue the watch command, No value for GDBN 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 No value for GDBN does not do that currently. If No value for GDBN 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, No value for GDBN 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, No value for GDBN 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, No value for GDBN 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.

Watching complex expressions that reference many variables can also exhaust the resources available for hardware-assisted watchpoints. That's because No value for GDBN needs to watch every variable in the expression with separately allocated resources.

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. No value for GDBN 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 No value for GDBN reaches another kind of breakpoint or the call completes.

No value for GDBN 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, No value for GDBN 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, No value for GDBN 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 No value for GDBN 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, No value for GDBN may not notice when a non-current thread's activity changes the expression. (Hardware watchpoints, in contrast, watch an expression in all threads.)

See set remote hardware-watchpoint-limit.