1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Conditions</title> 18 19<meta name="description" content="Debugging with GDB: Conditions"> 20<meta name="keywords" content="Debugging with GDB: Conditions"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Breakpoints.html#Breakpoints" rel="up" title="Breakpoints"> 29<link href="Break-Commands.html#Break-Commands" rel="next" title="Break Commands"> 30<link href="Disabling.html#Disabling" rel="previous" title="Disabling"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Conditions"></a> 65<div class="header"> 66<p> 67Next: <a href="Break-Commands.html#Break-Commands" accesskey="n" rel="next">Break Commands</a>, Previous: <a href="Disabling.html#Disabling" accesskey="p" rel="previous">Disabling</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> [<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> 68</div> 69<hr> 70<a name="Break-Conditions"></a> 71<h4 class="subsection">5.1.6 Break Conditions</h4> 72<a name="index-conditional-breakpoints"></a> 73<a name="index-breakpoint-conditions"></a> 74 75<p>The simplest sort of breakpoint breaks every time your program reaches a 76specified place. You can also specify a <em>condition</em> for a 77breakpoint. A condition is just a Boolean expression in your 78programming language (see <a href="Expressions.html#Expressions">Expressions</a>). A breakpoint with 79a condition evaluates the expression each time your program reaches it, 80and your program stops only if the condition is <em>true</em>. 81</p> 82<p>This is the converse of using assertions for program validation; in that 83situation, you want to stop when the assertion is violated—that is, 84when the condition is false. In C, if you want to test an assertion expressed 85by the condition <var>assert</var>, you should set the condition 86‘<samp>! <var>assert</var></samp>’ on the appropriate breakpoint. 87</p> 88<p>Conditions are also accepted for watchpoints; you may not need them, 89since a watchpoint is inspecting the value of an expression anyhow—but 90it might be simpler, say, to just set a watchpoint on a variable name, 91and specify a condition that tests whether the new value is an interesting 92one. 93</p> 94<p>Break conditions can have side effects, and may even call functions in 95your program. This can be useful, for example, to activate functions 96that log program progress, or to use your own print functions to 97format special data structures. The effects are completely predictable 98unless there is another enabled breakpoint at the same address. (In 99that case, <small>GDB</small> might see the other breakpoint first and stop your 100program without checking the condition of this one.) Note that 101breakpoint commands are usually more convenient and flexible than break 102conditions for the 103purpose of performing side effects when a breakpoint is reached 104(see <a href="Break-Commands.html#Break-Commands">Breakpoint Command Lists</a>). 105</p> 106<p>Breakpoint conditions can also be evaluated on the target’s side if 107the target supports it. Instead of evaluating the conditions locally, 108<small>GDB</small> encodes the expression into an agent expression 109(see <a href="Agent-Expressions.html#Agent-Expressions">Agent Expressions</a>) suitable for execution on the target, 110independently of <small>GDB</small>. Global variables become raw memory 111locations, locals become stack accesses, and so forth. 112</p> 113<p>In this case, <small>GDB</small> will only be notified of a breakpoint trigger 114when its condition evaluates to true. This mechanism may provide faster 115response times depending on the performance characteristics of the target 116since it does not need to keep <small>GDB</small> informed about 117every breakpoint trigger, even those with false conditions. 118</p> 119<p>Break conditions can be specified when a breakpoint is set, by using 120‘<samp>if</samp>’ 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 121with the <code>condition</code> command. 122</p> 123<p>You can also use the <code>if</code> keyword with the <code>watch</code> command. 124The <code>catch</code> command does not recognize the <code>if</code> keyword; 125<code>condition</code> is the only way to impose a further condition on a 126catchpoint. 127</p> 128<dl compact="compact"> 129<dd><a name="index-condition"></a> 130</dd> 131<dt><code>condition <var>bnum</var> <var>expression</var></code></dt> 132<dd><p>Specify <var>expression</var> as the break condition for breakpoint, 133watchpoint, or catchpoint number <var>bnum</var>. After you set a condition, 134breakpoint <var>bnum</var> stops your program only if the value of 135<var>expression</var> is true (nonzero, in C). When you use 136<code>condition</code>, <small>GDB</small> checks <var>expression</var> immediately for 137syntactic correctness, and to determine whether symbols in it have 138referents in the context of your breakpoint. If <var>expression</var> uses 139symbols not referenced in the context of the breakpoint, <small>GDB</small> 140prints an error message: 141</p> 142<div class="smallexample"> 143<pre class="smallexample">No symbol "foo" in current context. 144</pre></div> 145 146<p><small>GDB</small> does 147not actually evaluate <var>expression</var> at the time the <code>condition</code> 148command (or a command that sets a breakpoint with a condition, like 149<code>break if …</code>) is given, however. See <a href="Expressions.html#Expressions">Expressions</a>. 150</p> 151</dd> 152<dt><code>condition <var>bnum</var></code></dt> 153<dd><p>Remove the condition from breakpoint number <var>bnum</var>. It becomes 154an ordinary unconditional breakpoint. 155</p></dd> 156</dl> 157 158<a name="index-ignore-count-_0028of-breakpoint_0029"></a> 159<p>A special case of a breakpoint condition is to stop only when the 160breakpoint has been reached a certain number of times. This is so 161useful that there is a special way to do it, using the <em>ignore 162count</em> of the breakpoint. Every breakpoint has an ignore count, which 163is an integer. Most of the time, the ignore count is zero, and 164therefore has no effect. But if your program reaches a breakpoint whose 165ignore count is positive, then instead of stopping, it just decrements 166the ignore count by one and continues. As a result, if the ignore count 167value is <var>n</var>, the breakpoint does not stop the next <var>n</var> times 168your program reaches it. 169</p> 170<dl compact="compact"> 171<dd><a name="index-ignore"></a> 172</dd> 173<dt><code>ignore <var>bnum</var> <var>count</var></code></dt> 174<dd><p>Set the ignore count of breakpoint number <var>bnum</var> to <var>count</var>. 175The next <var>count</var> times the breakpoint is reached, your program’s 176execution does not stop; other than to decrement the ignore count, <small>GDB</small> 177takes no action. 178</p> 179<p>To make the breakpoint stop the next time it is reached, specify 180a count of zero. 181</p> 182<p>When you use <code>continue</code> to resume execution of your program from a 183breakpoint, you can specify an ignore count directly as an argument to 184<code>continue</code>, rather than using <code>ignore</code>. See <a href="Continuing-and-Stepping.html#Continuing-and-Stepping">Continuing and Stepping</a>. 185</p> 186<p>If a breakpoint has a positive ignore count and a condition, the 187condition is not checked. Once the ignore count reaches zero, 188<small>GDB</small> resumes checking the condition. 189</p> 190<p>You could achieve the effect of the ignore count with a condition such 191as ‘<samp><span class="nolinebreak">$foo--</span> <= 0</samp>’<!-- /@w --> using a debugger convenience variable that 192is decremented each time. See <a href="Convenience-Vars.html#Convenience-Vars">Convenience 193Variables</a>. 194</p></dd> 195</dl> 196 197<p>Ignore counts apply to breakpoints, watchpoints, and catchpoints. 198</p> 199 200<hr> 201<div class="header"> 202<p> 203Next: <a href="Break-Commands.html#Break-Commands" accesskey="n" rel="next">Break Commands</a>, Previous: <a href="Disabling.html#Disabling" accesskey="p" rel="previous">Disabling</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> [<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> 204</div> 205 206 207 208</body> 209</html> 210