doc/gdb/Set-Watchpoints.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs
Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom." -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Debugging with GDB: Set Watchpoints</title>

<meta name="description" content="Debugging with GDB: Set Watchpoints">
<meta name="keywords" content="Debugging with GDB: Set Watchpoints">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Breakpoints.html#Breakpoints" rel="up" title="Breakpoints">
<link href="Set-Catchpoints.html#Set-Catchpoints" rel="next" title="Set Catchpoints">
<link href="Set-Breaks.html#Set-Breaks" rel="previous" title="Set Breaks">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Set-Watchpoints"></a>
<div class="header">
<p>
Next: <a href="Set-Catchpoints.html#Set-Catchpoints" accesskey="n" rel="next">Set Catchpoints</a>, Previous: <a href="Set-Breaks.html#Set-Breaks" accesskey="p" rel="previous">Set Breaks</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Setting-Watchpoints"></a>
<h4 class="subsection">5.1.2 Setting Watchpoints</h4>

<a name="index-setting-watchpoints"></a>
<p>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 <em>data breakpoint</em>.)
The expression may be as simple as the value of a single variable, or
as complex as many variables combined by operators.  Examples include:
</p>
<ul>
<li> A reference to the value of a single variable.

</li><li> An address cast to an appropriate data type.  For example,
&lsquo;<samp>*(int *)0x12345678</samp>&rsquo; will watch a 4-byte region at the specified
address (assuming an <code>int</code> occupies 4 bytes).

</li><li> An arbitrarily complex expression, such as &lsquo;<samp>a*b + c/d</samp>&rsquo;.  The
expression can use any operators valid in the program&rsquo;s native
language (see <a href="Languages.html#Languages">Languages</a>).
</li></ul>

<p>You can set a watchpoint on an expression even if the expression can
not be evaluated yet.  For instance, you can set a watchpoint on
&lsquo;<samp>*global_ptr</samp>&rsquo; before &lsquo;<samp>global_ptr</samp>&rsquo; is initialized.
<small>GDB</small> will stop when your program sets &lsquo;<samp>global_ptr</samp>&rsquo; and
the expression produces a valid value.  If the expression becomes
valid in some other way than changing a variable (e.g. if the memory
pointed to by &lsquo;<samp>*global_ptr</samp>&rsquo; becomes readable as the result of a
<code>malloc</code> call), <small>GDB</small> may not stop until the next time
the expression changes.
</p>
<a name="index-software-watchpoints"></a>
<a name="index-hardware-watchpoints"></a>
<p>Depending on your system, watchpoints may be implemented in software or
hardware.  <small>GDB</small> does software watchpointing by single-stepping your
program and testing the variable&rsquo;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.)
</p>
<p>On some systems, such as most PowerPC or x86-based targets,
<small>GDB</small> includes support for hardware watchpoints, which do not
slow down the running of your program.
</p>
<dl compact="compact">
<dd><a name="index-watch"></a>
</dd>
<dt><code>watch <span class="roman">[</span>-l<span class="roman">|</span>-location<span class="roman">]</span> <var>expr</var> <span class="roman">[</span>thread <var>thread-id</var><span class="roman">]</span> <span class="roman">[</span>mask <var>maskvalue</var><span class="roman">]</span></code></dt>
<dd><p>Set a watchpoint for an expression.  <small>GDB</small> will break when the
expression <var>expr</var> 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:
</p>
<div class="smallexample">
<pre class="smallexample">(gdb) watch foo
</pre></div>

<p>If the command includes a <code><span class="roman">[</span>thread <var>thread-id</var><span class="roman">]</span></code>
argument, <small>GDB</small> breaks only when the thread identified by
<var>thread-id</var> changes the value of <var>expr</var>.  If any other threads
change the value of <var>expr</var>, <small>GDB</small> will not break.  Note
that watchpoints restricted to a single thread in this way only work
with Hardware Watchpoints.
</p>
<p>Ordinarily a watchpoint respects the scope of variables in <var>expr</var>
(see below).  The <code>-location</code> argument tells <small>GDB</small> to
instead watch the memory referred to by <var>expr</var>.  In this case,
<small>GDB</small> will evaluate <var>expr</var>, take the address of the result,
and watch the memory at that address.  The type of the result is used
to determine the size of the watched memory.  If the expression&rsquo;s
result does not have an address, then <small>GDB</small> will print an
error.
</p>
<p>The <code><span class="roman">[</span>mask <var>maskvalue</var><span class="roman">]</span></code> argument allows creation
of masked watchpoints, if the current architecture supports this
feature (e.g., PowerPC Embedded architecture, see <a href="PowerPC-Embedded.html#PowerPC-Embedded">PowerPC Embedded</a>.)  A <em>masked watchpoint</em> specifies a mask in addition
to an address to watch.  The mask specifies that some bits of an address
(the bits which are reset in the mask) should be ignored when matching
the address accessed by the inferior against the watchpoint address.
Thus, a masked watchpoint watches many addresses simultaneously&mdash;those
addresses whose unmasked bits are identical to the unmasked bits in the
watchpoint address.  The <code>mask</code> argument implies <code>-location</code>.
Examples:
</p>
<div class="smallexample">
<pre class="smallexample">(gdb) watch foo mask 0xffff00ff
(gdb) watch *0xdeadbeef mask 0xffffff00
</pre></div>

<a name="index-rwatch"></a>
</dd>
<dt><code>rwatch <span class="roman">[</span>-l<span class="roman">|</span>-location<span class="roman">]</span> <var>expr</var> <span class="roman">[</span>thread <var>thread-id</var><span class="roman">]</span> <span class="roman">[</span>mask <var>maskvalue</var><span class="roman">]</span></code></dt>
<dd><p>Set a watchpoint that will break when the value of <var>expr</var> is read
by the program.
</p>
<a name="index-awatch"></a>
</dd>
<dt><code>awatch <span class="roman">[</span>-l<span class="roman">|</span>-location<span class="roman">]</span> <var>expr</var> <span class="roman">[</span>thread <var>thread-id</var><span class="roman">]</span> <span class="roman">[</span>mask <var>maskvalue</var><span class="roman">]</span></code></dt>
<dd><p>Set a watchpoint that will break when <var>expr</var> is either read from
or written into by the program.
</p>
<a name="index-info-watchpoints-_005blist_2026_005d"></a>
</dd>
<dt><code>info watchpoints <span class="roman">[</span><var>list</var>&hellip;<span class="roman">]</span></code></dt>
<dd><p>This command prints a list of watchpoints, using the same format as
<code>info break</code> (see <a href="Set-Breaks.html#Set-Breaks">Set Breaks</a>).
</p></dd>
</dl>

<p>If you watch for a change in a numerically entered address you need to
dereference it, as the address itself is just a constant number which will
never change.  <small>GDB</small> refuses to create a watchpoint that watches
a never-changing value:
</p>
<div class="smallexample">
<pre class="smallexample">(gdb) watch 0x600850
Cannot watch constant value 0x600850.
(gdb) watch *(int *) 0x600850
Watchpoint 1: *(int *) 6293584
</pre></div>

<p><small>GDB</small> sets a <em>hardware watchpoint</em> if possible.  Hardware
watchpoints execute very quickly, and the debugger reports a change in
value at the exact instruction where the change occurs.  If <small>GDB</small>
cannot set a hardware watchpoint, it sets a software watchpoint, which
executes more slowly and reports the change in value at the next
<em>statement</em>, not the instruction, after the change occurs.
</p>
<a name="index-use-only-software-watchpoints"></a>
<p>You can force <small>GDB</small> to use only software watchpoints with the
<kbd>set can-use-hw-watchpoints 0</kbd> command.  With this variable set to
zero, <small>GDB</small> will never try to use hardware watchpoints, even if
the underlying system supports them.  (Note that hardware-assisted
watchpoints that were set <em>before</em> setting
<code>can-use-hw-watchpoints</code> to zero will still use the hardware
mechanism of watching expression values.)
</p>
<dl compact="compact">
<dt><code>set can-use-hw-watchpoints</code></dt>
<dd><a name="index-set-can_002duse_002dhw_002dwatchpoints"></a>
<p>Set whether or not to use hardware watchpoints.
</p>
</dd>
<dt><code>show can-use-hw-watchpoints</code></dt>
<dd><a name="index-show-can_002duse_002dhw_002dwatchpoints"></a>
<p>Show the current mode of using hardware watchpoints.
</p></dd>
</dl>

<p>For remote targets, you can restrict the number of hardware
watchpoints <small>GDB</small> will use, see <a href="Remote-Configuration.html#set-remote-hardware_002dbreakpoint_002dlimit">set remote hardware-breakpoint-limit</a>.
</p>
<p>When you issue the <code>watch</code> command, <small>GDB</small> reports
</p>
<div class="smallexample">
<pre class="smallexample">Hardware watchpoint <var>num</var>: <var>expr</var>
</pre></div>

<p>if it was able to set a hardware watchpoint.
</p>
<p>Currently, the <code>awatch</code> and <code>rwatch</code> commands can only set
hardware watchpoints, because accesses to data that don&rsquo;t change the
value of the watched expression cannot be detected without examining
every instruction as it is being executed, and <small>GDB</small> does not do
that currently.  If <small>GDB</small> finds that it is unable to set a
hardware breakpoint with the <code>awatch</code> or <code>rwatch</code> command, it
will print a message like this:
</p>
<div class="smallexample">
<pre class="smallexample">Expression cannot be implemented with read/access watchpoint.
</pre></div>

<p>Sometimes, <small>GDB</small> 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.
</p>
<p>If you set too many hardware watchpoints, <small>GDB</small> 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, <small>GDB</small> 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:
</p>
<div class="smallexample">
<pre class="smallexample">Hardware watchpoint <var>num</var>: Could not insert watchpoint
</pre></div>

<p>If this happens, delete or disable some of the watchpoints.
</p>
<p>Watching complex expressions that reference many variables can also
exhaust the resources available for hardware-assisted watchpoints.
That&rsquo;s because <small>GDB</small> needs to watch every variable in the
expression with separately allocated resources.
</p>
<p>If you call a function interactively using <code>print</code> or <code>call</code>,
any watchpoints you have set will be inactive until <small>GDB</small> reaches another
kind of breakpoint or the call completes.
</p>
<p><small>GDB</small> 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, <em>all</em> 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
<code>main</code> function and when it breaks, set all the watchpoints.
</p>
<a name="index-watchpoints-and-threads"></a>
<a name="index-threads-and-watchpoints"></a>
<p>In multi-threaded programs, watchpoints will detect changes to the
watched expression from every thread.
</p>
<blockquote>
<p><em>Warning:</em> In multi-threaded programs, software watchpoints
have only limited usefulness.  If <small>GDB</small> creates a software
watchpoint, it can only watch the value of an expression <em>in a
single thread</em>.  If you are confident that the expression can only
change due to the current thread&rsquo;s activity (and if you are also
confident that no other thread can become current), then you can use
software watchpoints as usual.  However, <small>GDB</small> may not notice
when a non-current thread&rsquo;s activity changes the expression.  (Hardware
watchpoints, in contrast, watch an expression in all threads.)
</p></blockquote>

<p>See <a href="Remote-Configuration.html#set-remote-hardware_002dwatchpoint_002dlimit">set remote hardware-watchpoint-limit</a>.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Set-Catchpoints.html#Set-Catchpoints" accesskey="n" rel="next">Set Catchpoints</a>, Previous: <a href="Set-Breaks.html#Set-Breaks" accesskey="p" rel="previous">Set Breaks</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>


</body>
</html>