You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
312 lines
16 KiB
HTML
312 lines
16 KiB
HTML
4 years ago
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- Copyright (C) 1988-2019 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 6.4, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>Set Watchpoints (Debugging with GDB)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Set Watchpoints (Debugging with GDB)">
|
||
|
|
<meta name="keywords" content="Set Watchpoints (Debugging with GDB)">
|
||
|
|
<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="prev" title="Set Breaks">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.summary-letter {text-decoration: none}
|
||
|
|
blockquote.indentedblock {margin-right: 0em}
|
||
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
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.nolinebreak {white-space: nowrap}
|
||
|
|
span.roman {font-family: initial; font-weight: normal}
|
||
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<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="prev">Set Breaks</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> [<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,
|
||
|
|
‘<samp>*(int *)0x12345678</samp>’ 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 ‘<samp>a*b + c/d</samp>’. The
|
||
|
|
expression can use any operators valid in the program’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
|
||
|
|
‘<samp>*global_ptr</samp>’ before ‘<samp>global_ptr</samp>’ is initialized.
|
||
|
|
<small>GDB</small> will stop when your program sets ‘<samp>global_ptr</samp>’ 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 ‘<samp>*global_ptr</samp>’ 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’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’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—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>…<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’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’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’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’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="prev">Set Breaks</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> [<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>
|