<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2015 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 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Debugging with GDB: Conditions</title>

<meta name="description" content="Debugging with GDB: Conditions">
<meta name="keywords" content="Debugging with GDB: Conditions">
<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="Break-Commands.html#Break-Commands" rel="next" title="Break Commands">
<link href="Disabling.html#Disabling" rel="prev" title="Disabling">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
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.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Conditions"></a>
<div class="header">
<p>
Next: <a href="Break-Commands.html#Break-Commands" accesskey="n" rel="next">Break Commands</a>, Previous: <a href="Disabling.html#Disabling" accesskey="p" rel="prev">Disabling</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> &nbsp; [<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="Break-Conditions"></a>
<h4 class="subsection">5.1.6 Break Conditions</h4>
<a name="index-conditional-breakpoints"></a>
<a name="index-breakpoint-conditions"></a>

<p>The simplest sort of breakpoint breaks every time your program reaches a
specified place.  You can also specify a <em>condition</em> for a
breakpoint.  A condition is just a Boolean expression in your
programming language (see <a href="Expressions.html#Expressions">Expressions</a>).  A breakpoint with
a condition evaluates the expression each time your program reaches it,
and your program stops only if the condition is <em>true</em>.
</p>
<p>This is the converse of using assertions for program validation; in that
situation, you want to stop when the assertion is violated&mdash;that is,
when the condition is false.  In C, if you want to test an assertion expressed
by the condition <var>assert</var>, you should set the condition
&lsquo;<samp>! <var>assert</var></samp>&rsquo; on the appropriate breakpoint.
</p>
<p>Conditions are also accepted for watchpoints; you may not need them,
since a watchpoint is inspecting the value of an expression anyhow&mdash;but
it might be simpler, say, to just set a watchpoint on a variable name,
and specify a condition that tests whether the new value is an interesting
one.
</p>
<p>Break conditions can have side effects, and may even call functions in
your program.  This can be useful, for example, to activate functions
that log program progress, or to use your own print functions to
format special data structures.  The effects are completely predictable
unless there is another enabled breakpoint at the same address.  (In
that case, <small>GDB</small> might see the other breakpoint first and stop your
program without checking the condition of this one.)  Note that
breakpoint commands are usually more convenient and flexible than break
conditions for the
purpose of performing side effects when a breakpoint is reached
(see <a href="Break-Commands.html#Break-Commands">Breakpoint Command Lists</a>).
</p>
<p>Breakpoint conditions can also be evaluated on the target&rsquo;s side if
the target supports it.  Instead of evaluating the conditions locally,
<small>GDB</small> encodes the expression into an agent expression
(see <a href="Agent-Expressions.html#Agent-Expressions">Agent Expressions</a>) suitable for execution on the target,
independently of <small>GDB</small>.  Global variables become raw memory
locations, locals become stack accesses, and so forth.
</p>
<p>In this case, <small>GDB</small> will only be notified of a breakpoint trigger
when its condition evaluates to true.  This mechanism may provide faster
response times depending on the performance characteristics of the target
since it does not need to keep <small>GDB</small> informed about
every breakpoint trigger, even those with false conditions.
</p>
<p>Break conditions can be specified when a breakpoint is set, by using
&lsquo;<samp>if</samp>&rsquo; in the arguments to the <code>break</code> command.  See <a href="Set-Breaks.html#Set-Breaks">Setting Breakpoints</a>.  They can also be changed at any time
with the <code>condition</code> command.
</p>
<p>You can also use the <code>if</code> keyword with the <code>watch</code> command.
The <code>catch</code> command does not recognize the <code>if</code> keyword;
<code>condition</code> is the only way to impose a further condition on a
catchpoint.
</p>
<dl compact="compact">
<dd><a name="index-condition"></a>
</dd>
<dt><code>condition <var>bnum</var> <var>expression</var></code></dt>
<dd><p>Specify <var>expression</var> as the break condition for breakpoint,
watchpoint, or catchpoint number <var>bnum</var>.  After you set a condition,
breakpoint <var>bnum</var> stops your program only if the value of
<var>expression</var> is true (nonzero, in C).  When you use
<code>condition</code>, <small>GDB</small> checks <var>expression</var> immediately for
syntactic correctness, and to determine whether symbols in it have
referents in the context of your breakpoint.  If <var>expression</var> uses
symbols not referenced in the context of the breakpoint, <small>GDB</small>
prints an error message:
</p>
<div class="smallexample">
<pre class="smallexample">No symbol &quot;foo&quot; in current context.
</pre></div>

<p><small>GDB</small> does
not actually evaluate <var>expression</var> at the time the <code>condition</code>
command (or a command that sets a breakpoint with a condition, like
<code>break if &hellip;</code>) is given, however.  See <a href="Expressions.html#Expressions">Expressions</a>.
</p>
</dd>
<dt><code>condition <var>bnum</var></code></dt>
<dd><p>Remove the condition from breakpoint number <var>bnum</var>.  It becomes
an ordinary unconditional breakpoint.
</p></dd>
</dl>

<a name="index-ignore-count-_0028of-breakpoint_0029"></a>
<p>A special case of a breakpoint condition is to stop only when the
breakpoint has been reached a certain number of times.  This is so
useful that there is a special way to do it, using the <em>ignore
count</em> of the breakpoint.  Every breakpoint has an ignore count, which
is an integer.  Most of the time, the ignore count is zero, and
therefore has no effect.  But if your program reaches a breakpoint whose
ignore count is positive, then instead of stopping, it just decrements
the ignore count by one and continues.  As a result, if the ignore count
value is <var>n</var>, the breakpoint does not stop the next <var>n</var> times
your program reaches it.
</p>
<dl compact="compact">
<dd><a name="index-ignore"></a>
</dd>
<dt><code>ignore <var>bnum</var> <var>count</var></code></dt>
<dd><p>Set the ignore count of breakpoint number <var>bnum</var> to <var>count</var>.
The next <var>count</var> times the breakpoint is reached, your program&rsquo;s
execution does not stop; other than to decrement the ignore count, <small>GDB</small>
takes no action.
</p>
<p>To make the breakpoint stop the next time it is reached, specify
a count of zero.
</p>
<p>When you use <code>continue</code> to resume execution of your program from a
breakpoint, you can specify an ignore count directly as an argument to
<code>continue</code>, rather than using <code>ignore</code>.  See <a href="Continuing-and-Stepping.html#Continuing-and-Stepping">Continuing and Stepping</a>.
</p>
<p>If a breakpoint has a positive ignore count and a condition, the
condition is not checked.  Once the ignore count reaches zero,
<small>GDB</small> resumes checking the condition.
</p>
<p>You could achieve the effect of the ignore count with a condition such
as &lsquo;<samp><span class="nolinebreak">$foo--</span>&nbsp;&lt;=&nbsp;0</samp>&rsquo;<!-- /@w --> using a debugger convenience variable that
is decremented each time.  See <a href="Convenience-Vars.html#Convenience-Vars">Convenience
Variables</a>.
</p></dd>
</dl>

<p>Ignore counts apply to breakpoints, watchpoints, and catchpoints.
</p>

<hr>
<div class="header">
<p>
Next: <a href="Break-Commands.html#Break-Commands" accesskey="n" rel="next">Break Commands</a>, Previous: <a href="Disabling.html#Disabling" accesskey="p" rel="prev">Disabling</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> &nbsp; [<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>