mingw/info/gdb/Set-Watchpoints.html

   1 <html lang="en">
   2 <head>
   3 <title>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.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="Set%20Watchpoints">Set Watchpoints</a>,
  13 Next:<a rel="next" accesskey="n" href="Set-Catchpoints.html#Set%20Catchpoints">Set Catchpoints</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Set-Breaks.html#Set%20Breaks">Set Breaks</a>,
  15 Up:<a rel="up" accesskey="u" href="Breakpoints.html#Breakpoints">Breakpoints</a>
  16 <hr><br>
  17 </div>
  18
  19 <h4 class="subsection">Setting watchpoints</h4>
  20
  21    <p>You can use a watchpoint to stop execution whenever the value of an
  22 expression changes, without having to predict a particular place where
  23 this may happen.
  24
  25    <p>Depending on your system, watchpoints may be implemented in software or
  26 hardware.  GDB does software watchpointing by single-stepping your
  27 program and testing the variable's value each time, which is hundreds of
  28 times slower than normal execution.  (But this may still be worth it, to
  29 catch errors where you have no clue what part of your program is the
  30 culprit.)
  31
  32    <p>On some systems, such as HP-UX, Linux and some other x86-based targets,
  33 GDB includes support for
  34 hardware watchpoints, which do not slow down the running of your
  35 program.
  36
  37      <dl>
  38 <dt><code>watch </code><var>expr</var><code></code>
  39      <dd>Set a watchpoint for an expression.  GDB will break when <var>expr</var>
  40 is written into by the program and its value changes.
  41
  42      <br><dt><code>rwatch </code><var>expr</var><code></code>
  43      <dd>Set a watchpoint that will break when watch <var>expr</var> is read by the program.
  44
  45      <br><dt><code>awatch </code><var>expr</var><code></code>
  46      <dd>Set a watchpoint that will break when <var>expr</var> is either read or written into
  47 by the program.
  48
  49      <br><dt><code>info watchpoints</code>
  50      <dd>This command prints a list of watchpoints, breakpoints, and catchpoints;
  51 it is the same as <code>info break</code>.
  52 </dl>
  53
  54    GDB sets a <dfn>hardware watchpoint</dfn> if possible.  Hardware
  55 watchpoints execute very quickly, and the debugger reports a change in
  56 value at the exact instruction where the change occurs.  If GDB
  57 cannot set a hardware watchpoint, it sets a software watchpoint, which
  58 executes more slowly and reports the change in value at the next
  59 statement, not the instruction, after the change occurs.
  60
  61    <p>When you issue the <code>watch</code> command, GDB reports
  62
  63 <pre class="example">     Hardware watchpoint <var>num</var>: <var>expr</var>
  64      </pre>
  65
  66 <p>if it was able to set a hardware watchpoint.
  67
  68    <p>Currently, the <code>awatch</code> and <code>rwatch</code> commands can only set
  69 hardware watchpoints, because accesses to data that don't change the
  70 value of the watched expression cannot be detected without examining
  71 every instruction as it is being executed, and GDB does not do
  72 that currently.  If GDB finds that it is unable to set a
  73 hardware breakpoint with the <code>awatch</code> or <code>rwatch</code> command, it
  74 will print a message like this:
  75
  76 <pre class="smallexample">     Expression cannot be implemented with read/access watchpoint.
  77      </pre>
  78
  79    <p>Sometimes, GDB cannot set a hardware watchpoint because the
  80 data type of the watched expression is wider than what a hardware
  81 watchpoint on the target machine can handle.  For example, some systems
  82 can only watch regions that are up to 4 bytes wide; on such systems you
  83 cannot set hardware watchpoints for an expression that yields a
  84 double-precision floating-point number (which is typically 8 bytes
  85 wide).  As a work-around, it might be possible to break the large region
  86 into a series of smaller ones and watch them with separate watchpoints.
  87
  88    <p>If you set too many hardware watchpoints, GDB might be unable
  89 to insert all of them when you resume the execution of your program.
  90 Since the precise number of active watchpoints is unknown until such
  91 time as the program is about to be resumed, GDB might not be
  92 able to warn you about this when you set the watchpoints, and the
  93 warning will be printed only when the program is resumed:
  94
  95 <pre class="smallexample">     Hardware watchpoint <var>num</var>: Could not insert watchpoint
  96      </pre>
  97
  98 <p>If this happens, delete or disable some of the watchpoints.
  99
 100    <p>The SPARClite DSU will generate traps when a program accesses some data
 101 or instruction address that is assigned to the debug registers.  For the
 102 data addresses, DSU facilitates the <code>watch</code> command.  However the
 103 hardware breakpoint registers can only take two data watchpoints, and
 104 both watchpoints must be the same kind.  For example, you can set two
 105 watchpoints with <code>watch</code> commands, two with <code>rwatch</code> commands,
 106 <strong>or</strong> two with <code>awatch</code> commands, but you cannot set one
 107 watchpoint with one command and the other with a different command.
 108 GDB will reject the command if you try to mix watchpoints.
 109 Delete or disable unused watchpoint commands before setting new ones.
 110
 111    <p>If you call a function interactively using <code>print</code> or <code>call</code>,
 112 any watchpoints you have set will be inactive until GDB reaches another
 113 kind of breakpoint or the call completes.
 114
 115    GDB automatically deletes watchpoints that watch local
 116 (automatic) variables, or expressions that involve such variables, when
 117 they go out of scope, that is, when the execution leaves the block in
 118 which these variables were defined.  In particular, when the program
 119 being debugged terminates, <em>all</em> local variables go out of scope,
 120 and so only watchpoints that watch global variables remain set.  If you
 121 rerun the program, you will need to set all such watchpoints again.  One
 122 way of doing that would be to set a code breakpoint at the entry to the
 123 <code>main</code> function and when it breaks, set all the watchpoints.
 124
 125    <blockquote>
 126 <em>Warning:</em> In multi-thread programs, watchpoints have only limited
 127 usefulness.  With the current watchpoint implementation, GDB
 128 can only watch the value of an expression <em>in a single thread</em>.  If
 129 you are confident that the expression can only change due to the current
 130 thread's activity (and if you are also confident that no other thread
 131 can become current), then you can use watchpoints as usual.  However,
 132 GDB may not notice when a non-current thread's activity changes
 133 the expression.
 134
 135         <p><em>HP-UX Warning:</em> In multi-thread programs, software watchpoints
 136 have only limited usefulness.  If GDB creates a software
 137 watchpoint, it can only watch the value of an expression <em>in a
 138 single thread</em>.  If you are confident that the expression can only
 139 change due to the current thread's activity (and if you are also
 140 confident that no other thread can become current), then you can use
 141 software watchpoints as usual.  However, GDB may not notice
 142 when a non-current thread's activity changes the expression.  (Hardware
 143 watchpoints, in contrast, watch an expression in all threads.)
 144 </blockquote>
 145
 146    </body></html>
 147