mingw/info/gdb/Conditions.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="Conditions">Conditions</a>,
  13 Next:<a rel="next" accesskey="n" href="Break-Commands.html#Break%20Commands">Break Commands</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Disabling.html#Disabling">Disabling</a>,
  15 Up:<a rel="up" accesskey="u" href="Breakpoints.html#Breakpoints">Breakpoints</a>
  16 <hr><br>
  17 </div>
  18
  19 <h4 class="subsection">Break conditions</h4>
  20
  21    <p>The simplest sort of breakpoint breaks every time your program reaches a
  22 specified place.  You can also specify a <dfn>condition</dfn> for a
  23 breakpoint.  A condition is just a Boolean expression in your
  24 programming language (see <a href="Expressions.html#Expressions">Expressions</a>).  A breakpoint with
  25 a condition evaluates the expression each time your program reaches it,
  26 and your program stops only if the condition is <em>true</em>.
  27
  28    <p>This is the converse of using assertions for program validation; in that
  29 situation, you want to stop when the assertion is violated--that is,
  30 when the condition is false.  In C, if you want to test an assertion expressed
  31 by the condition <var>assert</var>, you should set the condition
  32 <code>! </code><var>assert</var><code></code> on the appropriate breakpoint.
  33
  34    <p>Conditions are also accepted for watchpoints; you may not need them,
  35 since a watchpoint is inspecting the value of an expression anyhow--but
  36 it might be simpler, say, to just set a watchpoint on a variable name,
  37 and specify a condition that tests whether the new value is an interesting
  38 one.
  39
  40    <p>Break conditions can have side effects, and may even call functions in
  41 your program.  This can be useful, for example, to activate functions
  42 that log program progress, or to use your own print functions to
  43 format special data structures. The effects are completely predictable
  44 unless there is another enabled breakpoint at the same address.  (In
  45 that case, GDB might see the other breakpoint first and stop your
  46 program without checking the condition of this one.)  Note that
  47 breakpoint commands are usually more convenient and flexible than break
  48 conditions for the
  49 purpose of performing side effects when a breakpoint is reached
  50 (see <a href="Break-Commands.html#Break%20Commands">Breakpoint command lists</a>).
  51
  52    <p>Break conditions can be specified when a breakpoint is set, by using
  53 <code>if</code> in the arguments to the <code>break</code> command.  See <a href="Set-Breaks.html#Set%20Breaks">Setting breakpoints</a>.  They can also be changed at any time
  54 with the <code>condition</code> command.
  55
  56    <p>You can also use the <code>if</code> keyword with the <code>watch</code> command.
  57 The <code>catch</code> command does not recognize the <code>if</code> keyword;
  58 <code>condition</code> is the only way to impose a further condition on a
  59 catchpoint.
  60
  61      <dl>
  62 <dt><code>condition </code><var>bnum</var><code> </code><var>expression</var><code></code>
  63      <dd>Specify <var>expression</var> as the break condition for breakpoint,
  64 watchpoint, or catchpoint number <var>bnum</var>.  After you set a condition,
  65 breakpoint <var>bnum</var> stops your program only if the value of
  66 <var>expression</var> is true (nonzero, in C).  When you use
  67 <code>condition</code>, GDB checks <var>expression</var> immediately for
  68 syntactic correctness, and to determine whether symbols in it have
  69 referents in the context of your breakpoint.  If <var>expression</var> uses
  70 symbols not referenced in the context of the breakpoint, GDB
  71 prints an error message:
  72
  73      <pre class="example">          No symbol "foo" in current context.
  74           </pre>
  75
  76      GDB does
  77 not actually evaluate <var>expression</var> at the time the <code>condition</code>
  78 command (or a command that sets a breakpoint with a condition, like
  79 <code>break if ...</code>) is given, however.  See <a href="Expressions.html#Expressions">Expressions</a>.
  80
  81      <br><dt><code>condition </code><var>bnum</var><code></code>
  82      <dd>Remove the condition from breakpoint number <var>bnum</var>.  It becomes
  83 an ordinary unconditional breakpoint.
  84 </dl>
  85
  86    <p>A special case of a breakpoint condition is to stop only when the
  87 breakpoint has been reached a certain number of times.  This is so
  88 useful that there is a special way to do it, using the <dfn>ignore
  89 count</dfn> of the breakpoint.  Every breakpoint has an ignore count, which
  90 is an integer.  Most of the time, the ignore count is zero, and
  91 therefore has no effect.  But if your program reaches a breakpoint whose
  92 ignore count is positive, then instead of stopping, it just decrements
  93 the ignore count by one and continues.  As a result, if the ignore count
  94 value is <var>n</var>, the breakpoint does not stop the next <var>n</var> times
  95 your program reaches it.
  96
  97      <dl>
  98 <dt><code>ignore </code><var>bnum</var><code> </code><var>count</var><code></code>
  99      <dd>Set the ignore count of breakpoint number <var>bnum</var> to <var>count</var>.
 100 The next <var>count</var> times the breakpoint is reached, your program's
 101 execution does not stop; other than to decrement the ignore count, GDB
 102 takes no action.
 103
 104      <p>To make the breakpoint stop the next time it is reached, specify
 105 a count of zero.
 106
 107      <p>When you use <code>continue</code> to resume execution of your program from a
 108 breakpoint, you can specify an ignore count directly as an argument to
 109 <code>continue</code>, rather than using <code>ignore</code>.  See <a href="Continuing-and-Stepping.html#Continuing%20and%20Stepping">Continuing and stepping</a>.
 110
 111      <p>If a breakpoint has a positive ignore count and a condition, the
 112 condition is not checked.  Once the ignore count reaches zero,
 113 GDB resumes checking the condition.
 114
 115      <p>You could achieve the effect of the ignore count with a condition such
 116 as <code>$foo--&nbsp;&lt;=&nbsp;0</code> using a debugger convenience variable that
 117 is decremented each time.  See <a href="Convenience-Vars.html#Convenience%20Vars">Convenience variables</a>.
 118 </dl>
 119
 120    <p>Ignore counts apply to breakpoints, watchpoints, and catchpoints.
 121
 122    </body></html>
 123