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