1<html lang="en"> 2<head> 3<title>Set Watchpoints - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Breakpoints.html#Breakpoints" title="Breakpoints"> 9<link rel="prev" href="Set-Breaks.html#Set-Breaks" title="Set Breaks"> 10<link rel="next" href="Set-Catchpoints.html#Set-Catchpoints" title="Set Catchpoints"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988-2013 Free Software Foundation, Inc. 14 15Permission is granted to copy, distribute and/or modify this document 16under the terms of the GNU Free Documentation License, Version 1.3 or 17any later version published by the Free Software Foundation; with the 18Invariant Sections being ``Free Software'' and ``Free Software Needs 19Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 20and with the Back-Cover Texts as in (a) below. 21 22(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 23this GNU Manual. Buying copies from GNU Press supports the FSF in 24developing GNU and promoting software freedom.'' 25--> 26<meta http-equiv="Content-Style-Type" content="text/css"> 27<style type="text/css"><!-- 28 pre.display { font-family:inherit } 29 pre.format { font-family:inherit } 30 pre.smalldisplay { font-family:inherit; font-size:smaller } 31 pre.smallformat { font-family:inherit; font-size:smaller } 32 pre.smallexample { font-size:smaller } 33 pre.smalllisp { font-size:smaller } 34 span.sc { font-variant:small-caps } 35 span.roman { font-family:serif; font-weight:normal; } 36 span.sansserif { font-family:sans-serif; font-weight:normal; } 37--></style> 38<link rel="stylesheet" type="text/css" href="../cs.css"> 39</head> 40<body> 41<div class="node"> 42<a name="Set-Watchpoints"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Set-Catchpoints.html#Set-Catchpoints">Set Catchpoints</a>, 45Previous: <a rel="previous" accesskey="p" href="Set-Breaks.html#Set-Breaks">Set Breaks</a>, 46Up: <a rel="up" accesskey="u" href="Breakpoints.html#Breakpoints">Breakpoints</a> 47<hr> 48</div> 49 50<h4 class="subsection">5.1.2 Setting Watchpoints</h4> 51 52<p><a name="index-setting-watchpoints-249"></a>You can use a watchpoint to stop execution whenever the value of an 53expression changes, without having to predict a particular place where 54this may happen. (This is sometimes called a <dfn>data breakpoint</dfn>.) 55The expression may be as simple as the value of a single variable, or 56as complex as many variables combined by operators. Examples include: 57 58 <ul> 59<li>A reference to the value of a single variable. 60 61 <li>An address cast to an appropriate data type. For example, 62‘<samp><span class="samp">*(int *)0x12345678</span></samp>’ will watch a 4-byte region at the specified 63address (assuming an <code>int</code> occupies 4 bytes). 64 65 <li>An arbitrarily complex expression, such as ‘<samp><span class="samp">a*b + c/d</span></samp>’. The 66expression can use any operators valid in the program's native 67language (see <a href="Languages.html#Languages">Languages</a>). 68</ul> 69 70 <p>You can set a watchpoint on an expression even if the expression can 71not be evaluated yet. For instance, you can set a watchpoint on 72‘<samp><span class="samp">*global_ptr</span></samp>’ before ‘<samp><span class="samp">global_ptr</span></samp>’ is initialized. 73<span class="sc">gdb</span> will stop when your program sets ‘<samp><span class="samp">global_ptr</span></samp>’ and 74the expression produces a valid value. If the expression becomes 75valid in some other way than changing a variable (e.g. if the memory 76pointed to by ‘<samp><span class="samp">*global_ptr</span></samp>’ becomes readable as the result of a 77<code>malloc</code> call), <span class="sc">gdb</span> may not stop until the next time 78the expression changes. 79 80 <p><a name="index-software-watchpoints-250"></a><a name="index-hardware-watchpoints-251"></a>Depending on your system, watchpoints may be implemented in software or 81hardware. <span class="sc">gdb</span> does software watchpointing by single-stepping your 82program and testing the variable's value each time, which is hundreds of 83times slower than normal execution. (But this may still be worth it, to 84catch errors where you have no clue what part of your program is the 85culprit.) 86 87 <p>On some systems, such as HP-UX, PowerPC, <span class="sc">gnu</span>/Linux and most other 88x86-based targets, <span class="sc">gdb</span> includes support for hardware 89watchpoints, which do not slow down the running of your program. 90 91 92<a name="index-watch-252"></a> 93<dl><dt><code>watch </code><span class="roman">[</span><code>-l</code><span class="roman">|</span><code>-location</code><span class="roman">]</span> <var>expr</var> <span class="roman">[</span><code>thread </code><var>threadnum</var><span class="roman">]</span> <span class="roman">[</span><code>mask </code><var>maskvalue</var><span class="roman">]</span><dd>Set a watchpoint for an expression. <span class="sc">gdb</span> will break when the 94expression <var>expr</var> is written into by the program and its value 95changes. The simplest (and the most popular) use of this command is 96to watch the value of a single variable: 97 98 <pre class="smallexample"> (gdb) watch foo 99</pre> 100 <p>If the command includes a <span class="roman">[</span><code>thread </code><var>threadnum</var><span class="roman">]</span> 101argument, <span class="sc">gdb</span> breaks only when the thread identified by 102<var>threadnum</var> changes the value of <var>expr</var>. If any other threads 103change the value of <var>expr</var>, <span class="sc">gdb</span> will not break. Note 104that watchpoints restricted to a single thread in this way only work 105with Hardware Watchpoints. 106 107 <p>Ordinarily a watchpoint respects the scope of variables in <var>expr</var> 108(see below). The <code>-location</code> argument tells <span class="sc">gdb</span> to 109instead watch the memory referred to by <var>expr</var>. In this case, 110<span class="sc">gdb</span> will evaluate <var>expr</var>, take the address of the result, 111and watch the memory at that address. The type of the result is used 112to determine the size of the watched memory. If the expression's 113result does not have an address, then <span class="sc">gdb</span> will print an 114error. 115 116 <p>The <span class="roman">[</span><code>mask </code><var>maskvalue</var><span class="roman">]</span> argument allows creation 117of masked watchpoints, if the current architecture supports this 118feature (e.g., PowerPC Embedded architecture, see <a href="PowerPC-Embedded.html#PowerPC-Embedded">PowerPC Embedded</a>.) A <dfn>masked watchpoint</dfn> specifies a mask in addition 119to an address to watch. The mask specifies that some bits of an address 120(the bits which are reset in the mask) should be ignored when matching 121the address accessed by the inferior against the watchpoint address. 122Thus, a masked watchpoint watches many addresses simultaneously—those 123addresses whose unmasked bits are identical to the unmasked bits in the 124watchpoint address. The <code>mask</code> argument implies <code>-location</code>. 125Examples: 126 127 <pre class="smallexample"> (gdb) watch foo mask 0xffff00ff 128 (gdb) watch *0xdeadbeef mask 0xffffff00 129</pre> 130 <p><a name="index-rwatch-253"></a><br><dt><code>rwatch </code><span class="roman">[</span><code>-l</code><span class="roman">|</span><code>-location</code><span class="roman">]</span> <var>expr</var> <span class="roman">[</span><code>thread </code><var>threadnum</var><span class="roman">]</span> <span class="roman">[</span><code>mask </code><var>maskvalue</var><span class="roman">]</span><dd>Set a watchpoint that will break when the value of <var>expr</var> is read 131by the program. 132 133 <p><a name="index-awatch-254"></a><br><dt><code>awatch </code><span class="roman">[</span><code>-l</code><span class="roman">|</span><code>-location</code><span class="roman">]</span> <var>expr</var> <span class="roman">[</span><code>thread </code><var>threadnum</var><span class="roman">]</span> <span class="roman">[</span><code>mask </code><var>maskvalue</var><span class="roman">]</span><dd>Set a watchpoint that will break when <var>expr</var> is either read from 134or written into by the program. 135 136 <p><a name="index-info-watchpoints-_0040r_007b_005b_007d_0040var_007bn_007d_0040dots_007b_007d_0040r_007b_005d_007d-255"></a><br><dt><code>info watchpoints </code><span class="roman">[</span><var>n</var><code>...</code><span class="roman">]</span><dd>This command prints a list of watchpoints, using the same format as 137<code>info break</code> (see <a href="Set-Breaks.html#Set-Breaks">Set Breaks</a>). 138</dl> 139 140 <p>If you watch for a change in a numerically entered address you need to 141dereference it, as the address itself is just a constant number which will 142never change. <span class="sc">gdb</span> refuses to create a watchpoint that watches 143a never-changing value: 144 145<pre class="smallexample"> (gdb) watch 0x600850 146 Cannot watch constant value 0x600850. 147 (gdb) watch *(int *) 0x600850 148 Watchpoint 1: *(int *) 6293584 149</pre> 150 <p><span class="sc">gdb</span> sets a <dfn>hardware watchpoint</dfn> if possible. Hardware 151watchpoints execute very quickly, and the debugger reports a change in 152value at the exact instruction where the change occurs. If <span class="sc">gdb</span> 153cannot set a hardware watchpoint, it sets a software watchpoint, which 154executes more slowly and reports the change in value at the next 155<em>statement</em>, not the instruction, after the change occurs. 156 157 <p><a name="index-use-only-software-watchpoints-256"></a>You can force <span class="sc">gdb</span> to use only software watchpoints with the 158<kbd>set can-use-hw-watchpoints 0</kbd> command. With this variable set to 159zero, <span class="sc">gdb</span> will never try to use hardware watchpoints, even if 160the underlying system supports them. (Note that hardware-assisted 161watchpoints that were set <em>before</em> setting 162<code>can-use-hw-watchpoints</code> to zero will still use the hardware 163mechanism of watching expression values.) 164 165 <dl> 166<dt><code>set can-use-hw-watchpoints</code><dd><a name="index-set-can_002duse_002dhw_002dwatchpoints-257"></a>Set whether or not to use hardware watchpoints. 167 168 <br><dt><code>show can-use-hw-watchpoints</code><dd><a name="index-show-can_002duse_002dhw_002dwatchpoints-258"></a>Show the current mode of using hardware watchpoints. 169</dl> 170 171 <p>For remote targets, you can restrict the number of hardware 172watchpoints <span class="sc">gdb</span> will use, see <a href="set-remote-hardware_002dbreakpoint_002dlimit.html#set-remote-hardware_002dbreakpoint_002dlimit">set remote hardware-breakpoint-limit</a>. 173 174 <p>When you issue the <code>watch</code> command, <span class="sc">gdb</span> reports 175 176<pre class="smallexample"> Hardware watchpoint <var>num</var>: <var>expr</var> 177</pre> 178 <p class="noindent">if it was able to set a hardware watchpoint. 179 180 <p>Currently, the <code>awatch</code> and <code>rwatch</code> commands can only set 181hardware watchpoints, because accesses to data that don't change the 182value of the watched expression cannot be detected without examining 183every instruction as it is being executed, and <span class="sc">gdb</span> does not do 184that currently. If <span class="sc">gdb</span> finds that it is unable to set a 185hardware breakpoint with the <code>awatch</code> or <code>rwatch</code> command, it 186will print a message like this: 187 188<pre class="smallexample"> Expression cannot be implemented with read/access watchpoint. 189</pre> 190 <p>Sometimes, <span class="sc">gdb</span> cannot set a hardware watchpoint because the 191data type of the watched expression is wider than what a hardware 192watchpoint on the target machine can handle. For example, some systems 193can only watch regions that are up to 4 bytes wide; on such systems you 194cannot set hardware watchpoints for an expression that yields a 195double-precision floating-point number (which is typically 8 bytes 196wide). As a work-around, it might be possible to break the large region 197into a series of smaller ones and watch them with separate watchpoints. 198 199 <p>If you set too many hardware watchpoints, <span class="sc">gdb</span> might be unable 200to insert all of them when you resume the execution of your program. 201Since the precise number of active watchpoints is unknown until such 202time as the program is about to be resumed, <span class="sc">gdb</span> might not be 203able to warn you about this when you set the watchpoints, and the 204warning will be printed only when the program is resumed: 205 206<pre class="smallexample"> Hardware watchpoint <var>num</var>: Could not insert watchpoint 207</pre> 208 <p class="noindent">If this happens, delete or disable some of the watchpoints. 209 210 <p>Watching complex expressions that reference many variables can also 211exhaust the resources available for hardware-assisted watchpoints. 212That's because <span class="sc">gdb</span> needs to watch every variable in the 213expression with separately allocated resources. 214 215 <p>If you call a function interactively using <code>print</code> or <code>call</code>, 216any watchpoints you have set will be inactive until <span class="sc">gdb</span> reaches another 217kind of breakpoint or the call completes. 218 219 <p><span class="sc">gdb</span> automatically deletes watchpoints that watch local 220(automatic) variables, or expressions that involve such variables, when 221they go out of scope, that is, when the execution leaves the block in 222which these variables were defined. In particular, when the program 223being debugged terminates, <em>all</em> local variables go out of scope, 224and so only watchpoints that watch global variables remain set. If you 225rerun the program, you will need to set all such watchpoints again. One 226way of doing that would be to set a code breakpoint at the entry to the 227<code>main</code> function and when it breaks, set all the watchpoints. 228 229 <p><a name="index-watchpoints-and-threads-259"></a><a name="index-threads-and-watchpoints-260"></a>In multi-threaded programs, watchpoints will detect changes to the 230watched expression from every thread. 231 232 <blockquote> 233<em>Warning:</em> In multi-threaded programs, software watchpoints 234have only limited usefulness. If <span class="sc">gdb</span> creates a software 235watchpoint, it can only watch the value of an expression <em>in a 236single thread</em>. If you are confident that the expression can only 237change due to the current thread's activity (and if you are also 238confident that no other thread can become current), then you can use 239software watchpoints as usual. However, <span class="sc">gdb</span> may not notice 240when a non-current thread's activity changes the expression. (Hardware 241watchpoints, in contrast, watch an expression in all threads.) 242</blockquote> 243 244 <p>See <a href="set-remote-hardware_002dwatchpoint_002dlimit.html#set-remote-hardware_002dwatchpoint_002dlimit">set remote hardware-watchpoint-limit</a>. 245 246 </body></html> 247 248