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: Breakpoints In Python</title> 18 19<meta name="description" content="Debugging with GDB: Breakpoints In Python"> 20<meta name="keywords" content="Debugging with GDB: Breakpoints In Python"> 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="Python-API.html#Python-API" rel="up" title="Python API"> 29<link href="Finish-Breakpoints-in-Python.html#Finish-Breakpoints-in-Python" rel="next" title="Finish Breakpoints in Python"> 30<link href="Line-Tables-In-Python.html#Line-Tables-In-Python" rel="previous" title="Line Tables In Python"> 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="Breakpoints-In-Python"></a> 65<div class="header"> 66<p> 67Next: <a href="Finish-Breakpoints-in-Python.html#Finish-Breakpoints-in-Python" accesskey="n" rel="next">Finish Breakpoints in Python</a>, Previous: <a href="Line-Tables-In-Python.html#Line-Tables-In-Python" accesskey="p" rel="previous">Line Tables In Python</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</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="Manipulating-breakpoints-using-Python"></a> 71<h4 class="subsubsection">23.2.2.30 Manipulating breakpoints using Python</h4> 72 73<a name="index-breakpoints-in-python"></a> 74<a name="index-gdb_002eBreakpoint"></a> 75 76<p>Python code can manipulate breakpoints via the <code>gdb.Breakpoint</code> 77class. 78</p> 79<p>A breakpoint can be created using one of the two forms of the 80<code>gdb.Breakpoint</code> constructor. The first one accepts a string 81like one would pass to the <code>break</code> 82(see <a href="Set-Breaks.html#Set-Breaks">Setting Breakpoints</a>) and <code>watch</code> 83(see <a href="Set-Watchpoints.html#Set-Watchpoints">Setting Watchpoints</a>) commands, and can be used to 84create both breakpoints and watchpoints. The second accepts separate Python 85arguments similar to <a href="Explicit-Locations.html#Explicit-Locations">Explicit Locations</a>, and can only be used to create 86breakpoints. 87</p> 88<dl> 89<dt><a name="index-Breakpoint_002e_005f_005finit_005f_005f"></a>Function: <strong>Breakpoint.__init__</strong> <em>(spec <span class="roman">[</span>, type <span class="roman">][</span>, wp_class <span class="roman">][</span>, internal <span class="roman">][</span>, temporary <span class="roman">][</span>, qualified <span class="roman">]</span>)</em></dt> 90<dd><p>Create a new breakpoint according to <var>spec</var>, which is a string naming the 91location of a breakpoint, or an expression that defines a watchpoint. The 92string should describe a location in a format recognized by the <code>break</code> 93command (see <a href="Set-Breaks.html#Set-Breaks">Setting Breakpoints</a>) or, in the case of a 94watchpoint, by the <code>watch</code> command 95(see <a href="Set-Watchpoints.html#Set-Watchpoints">Setting Watchpoints</a>). 96</p> 97<p>The optional <var>type</var> argument specifies the type of the breakpoint to create, 98as defined below. 99</p> 100<p>The optional <var>wp_class</var> argument defines the class of watchpoint to create, 101if <var>type</var> is <code>gdb.BP_WATCHPOINT</code>. If <var>wp_class</var> is omitted, it 102defaults to <code>gdb.WP_WRITE</code>. 103</p> 104<p>The optional <var>internal</var> argument allows the breakpoint to become invisible 105to the user. The breakpoint will neither be reported when created, nor will it 106be listed in the output from <code>info breakpoints</code> (but will be listed with 107the <code>maint info breakpoints</code> command). 108</p> 109<p>The optional <var>temporary</var> argument makes the breakpoint a temporary 110breakpoint. Temporary breakpoints are deleted after they have been hit. Any 111further access to the Python breakpoint after it has been hit will result in a 112runtime error (as that breakpoint has now been automatically deleted). 113</p> 114<p>The optional <var>qualified</var> argument is a boolean that allows interpreting 115the function passed in <code>spec</code> as a fully-qualified name. It is equivalent 116to <code>break</code>’s <code>-qualified</code> flag (see <a href="Linespec-Locations.html#Linespec-Locations">Linespec Locations</a> and 117<a href="Explicit-Locations.html#Explicit-Locations">Explicit Locations</a>). 118</p> 119</dd></dl> 120 121<dl> 122<dt><a name="index-Breakpoint_002e_005f_005finit_005f_005f-1"></a>Function: <strong>Breakpoint.__init__</strong> <em>(<span class="roman">[</span> source <span class="roman">][</span>, function <span class="roman">][</span>, label <span class="roman">][</span>, line <span class="roman">]</span>, <span class="roman">][</span> internal <span class="roman">][</span>, temporary <span class="roman">][</span>, qualified <span class="roman">]</span>)</em></dt> 123<dd><p>This second form of creating a new breakpoint specifies the explicit 124location (see <a href="Explicit-Locations.html#Explicit-Locations">Explicit Locations</a>) using keywords. The new breakpoint will 125be created in the specified source file <var>source</var>, at the specified 126<var>function</var>, <var>label</var> and <var>line</var>. 127</p> 128<p><var>internal</var>, <var>temporary</var> and <var>qualified</var> have the same usage as 129explained previously. 130</p></dd></dl> 131 132<p>The available types are represented by constants defined in the <code>gdb</code> 133module: 134</p> 135<dl compact="compact"> 136<dd><a name="index-BP_005fBREAKPOINT"></a> 137</dd> 138<dt><code>gdb.BP_BREAKPOINT</code> 139<a name="index-gdb_002eBP_005fBREAKPOINT"></a> 140</dt> 141<dd><p>Normal code breakpoint. 142</p> 143<a name="index-BP_005fWATCHPOINT"></a> 144</dd> 145<dt><code>gdb.BP_WATCHPOINT</code> 146<a name="index-gdb_002eBP_005fWATCHPOINT"></a> 147</dt> 148<dd><p>Watchpoint breakpoint. 149</p> 150<a name="index-BP_005fHARDWARE_005fWATCHPOINT"></a> 151</dd> 152<dt><code>gdb.BP_HARDWARE_WATCHPOINT</code> 153<a name="index-gdb_002eBP_005fHARDWARE_005fWATCHPOINT"></a> 154</dt> 155<dd><p>Hardware assisted watchpoint. 156</p> 157<a name="index-BP_005fREAD_005fWATCHPOINT"></a> 158</dd> 159<dt><code>gdb.BP_READ_WATCHPOINT</code> 160<a name="index-gdb_002eBP_005fREAD_005fWATCHPOINT"></a> 161</dt> 162<dd><p>Hardware assisted read watchpoint. 163</p> 164<a name="index-BP_005fACCESS_005fWATCHPOINT"></a> 165</dd> 166<dt><code>gdb.BP_ACCESS_WATCHPOINT</code> 167<a name="index-gdb_002eBP_005fACCESS_005fWATCHPOINT"></a> 168</dt> 169<dd><p>Hardware assisted access watchpoint. 170</p></dd> 171</dl> 172 173<p>The available watchpoint types represented by constants are defined in the 174<code>gdb</code> module: 175</p> 176<dl compact="compact"> 177<dd><a name="index-WP_005fREAD"></a> 178</dd> 179<dt><code>gdb.WP_READ</code> 180<a name="index-gdb_002eWP_005fREAD"></a> 181</dt> 182<dd><p>Read only watchpoint. 183</p> 184<a name="index-WP_005fWRITE"></a> 185</dd> 186<dt><code>gdb.WP_WRITE</code> 187<a name="index-gdb_002eWP_005fWRITE"></a> 188</dt> 189<dd><p>Write only watchpoint. 190</p> 191<a name="index-WP_005fACCESS"></a> 192</dd> 193<dt><code>gdb.WP_ACCESS</code> 194<a name="index-gdb_002eWP_005fACCESS"></a> 195</dt> 196<dd><p>Read/Write watchpoint. 197</p></dd> 198</dl> 199 200<dl> 201<dt><a name="index-Breakpoint_002estop"></a>Function: <strong>Breakpoint.stop</strong> <em>(self)</em></dt> 202<dd><p>The <code>gdb.Breakpoint</code> class can be sub-classed and, in 203particular, you may choose to implement the <code>stop</code> method. 204If this method is defined in a sub-class of <code>gdb.Breakpoint</code>, 205it will be called when the inferior reaches any location of a 206breakpoint which instantiates that sub-class. If the method returns 207<code>True</code>, the inferior will be stopped at the location of the 208breakpoint, otherwise the inferior will continue. 209</p> 210<p>If there are multiple breakpoints at the same location with a 211<code>stop</code> method, each one will be called regardless of the 212return status of the previous. This ensures that all <code>stop</code> 213methods have a chance to execute at that location. In this scenario 214if one of the methods returns <code>True</code> but the others return 215<code>False</code>, the inferior will still be stopped. 216</p> 217<p>You should not alter the execution state of the inferior (i.e., step, 218next, etc.), alter the current frame context (i.e., change the current 219active frame), or alter, add or delete any breakpoint. As a general 220rule, you should not alter any data within <small>GDB</small> or the inferior 221at this time. 222</p> 223<p>Example <code>stop</code> implementation: 224</p> 225<div class="smallexample"> 226<pre class="smallexample">class MyBreakpoint (gdb.Breakpoint): 227 def stop (self): 228 inf_val = gdb.parse_and_eval("foo") 229 if inf_val == 3: 230 return True 231 return False 232</pre></div> 233</dd></dl> 234 235<dl> 236<dt><a name="index-Breakpoint_002eis_005fvalid"></a>Function: <strong>Breakpoint.is_valid</strong> <em>()</em></dt> 237<dd><p>Return <code>True</code> if this <code>Breakpoint</code> object is valid, 238<code>False</code> otherwise. A <code>Breakpoint</code> object can become invalid 239if the user deletes the breakpoint. In this case, the object still 240exists, but the underlying breakpoint does not. In the cases of 241watchpoint scope, the watchpoint remains valid even if execution of the 242inferior leaves the scope of that watchpoint. 243</p></dd></dl> 244 245<dl> 246<dt><a name="index-Breakpoint_002edelete"></a>Function: <strong>Breakpoint.delete</strong> <em>()</em></dt> 247<dd><p>Permanently deletes the <small>GDB</small> breakpoint. This also 248invalidates the Python <code>Breakpoint</code> object. Any further access 249to this object’s attributes or methods will raise an error. 250</p></dd></dl> 251 252<dl> 253<dt><a name="index-Breakpoint_002eenabled"></a>Variable: <strong>Breakpoint.enabled</strong></dt> 254<dd><p>This attribute is <code>True</code> if the breakpoint is enabled, and 255<code>False</code> otherwise. This attribute is writable. You can use it to enable 256or disable the breakpoint. 257</p></dd></dl> 258 259<dl> 260<dt><a name="index-Breakpoint_002esilent"></a>Variable: <strong>Breakpoint.silent</strong></dt> 261<dd><p>This attribute is <code>True</code> if the breakpoint is silent, and 262<code>False</code> otherwise. This attribute is writable. 263</p> 264<p>Note that a breakpoint can also be silent if it has commands and the 265first command is <code>silent</code>. This is not reported by the 266<code>silent</code> attribute. 267</p></dd></dl> 268 269<dl> 270<dt><a name="index-Breakpoint_002epending"></a>Variable: <strong>Breakpoint.pending</strong></dt> 271<dd><p>This attribute is <code>True</code> if the breakpoint is pending, and 272<code>False</code> otherwise. See <a href="Set-Breaks.html#Set-Breaks">Set Breaks</a>. This attribute is 273read-only. 274</p></dd></dl> 275 276<a name="python_005fbreakpoint_005fthread"></a><dl> 277<dt><a name="index-Breakpoint_002ethread"></a>Variable: <strong>Breakpoint.thread</strong></dt> 278<dd><p>If the breakpoint is thread-specific, this attribute holds the 279thread’s global id. If the breakpoint is not thread-specific, this 280attribute is <code>None</code>. This attribute is writable. 281</p></dd></dl> 282 283<dl> 284<dt><a name="index-Breakpoint_002etask"></a>Variable: <strong>Breakpoint.task</strong></dt> 285<dd><p>If the breakpoint is Ada task-specific, this attribute holds the Ada task 286id. If the breakpoint is not task-specific (or the underlying 287language is not Ada), this attribute is <code>None</code>. This attribute 288is writable. 289</p></dd></dl> 290 291<dl> 292<dt><a name="index-Breakpoint_002eignore_005fcount"></a>Variable: <strong>Breakpoint.ignore_count</strong></dt> 293<dd><p>This attribute holds the ignore count for the breakpoint, an integer. 294This attribute is writable. 295</p></dd></dl> 296 297<dl> 298<dt><a name="index-Breakpoint_002enumber"></a>Variable: <strong>Breakpoint.number</strong></dt> 299<dd><p>This attribute holds the breakpoint’s number — the identifier used by 300the user to manipulate the breakpoint. This attribute is not writable. 301</p></dd></dl> 302 303<dl> 304<dt><a name="index-Breakpoint_002etype"></a>Variable: <strong>Breakpoint.type</strong></dt> 305<dd><p>This attribute holds the breakpoint’s type — the identifier used to 306determine the actual breakpoint type or use-case. This attribute is not 307writable. 308</p></dd></dl> 309 310<dl> 311<dt><a name="index-Breakpoint_002evisible"></a>Variable: <strong>Breakpoint.visible</strong></dt> 312<dd><p>This attribute tells whether the breakpoint is visible to the user 313when set, or when the ‘<samp>info breakpoints</samp>’ command is run. This 314attribute is not writable. 315</p></dd></dl> 316 317<dl> 318<dt><a name="index-Breakpoint_002etemporary"></a>Variable: <strong>Breakpoint.temporary</strong></dt> 319<dd><p>This attribute indicates whether the breakpoint was created as a 320temporary breakpoint. Temporary breakpoints are automatically deleted 321after that breakpoint has been hit. Access to this attribute, and all 322other attributes and functions other than the <code>is_valid</code> 323function, will result in an error after the breakpoint has been hit 324(as it has been automatically deleted). This attribute is not 325writable. 326</p></dd></dl> 327 328<dl> 329<dt><a name="index-Breakpoint_002ehit_005fcount"></a>Variable: <strong>Breakpoint.hit_count</strong></dt> 330<dd><p>This attribute holds the hit count for the breakpoint, an integer. 331This attribute is writable, but currently it can only be set to zero. 332</p></dd></dl> 333 334<dl> 335<dt><a name="index-Breakpoint_002elocation"></a>Variable: <strong>Breakpoint.location</strong></dt> 336<dd><p>This attribute holds the location of the breakpoint, as specified by 337the user. It is a string. If the breakpoint does not have a location 338(that is, it is a watchpoint) the attribute’s value is <code>None</code>. This 339attribute is not writable. 340</p></dd></dl> 341 342<dl> 343<dt><a name="index-Breakpoint_002eexpression"></a>Variable: <strong>Breakpoint.expression</strong></dt> 344<dd><p>This attribute holds a breakpoint expression, as specified by 345the user. It is a string. If the breakpoint does not have an 346expression (the breakpoint is not a watchpoint) the attribute’s value 347is <code>None</code>. This attribute is not writable. 348</p></dd></dl> 349 350<dl> 351<dt><a name="index-Breakpoint_002econdition"></a>Variable: <strong>Breakpoint.condition</strong></dt> 352<dd><p>This attribute holds the condition of the breakpoint, as specified by 353the user. It is a string. If there is no condition, this attribute’s 354value is <code>None</code>. This attribute is writable. 355</p></dd></dl> 356 357<dl> 358<dt><a name="index-Breakpoint_002ecommands"></a>Variable: <strong>Breakpoint.commands</strong></dt> 359<dd><p>This attribute holds the commands attached to the breakpoint. If 360there are commands, this attribute’s value is a string holding all the 361commands, separated by newlines. If there are no commands, this 362attribute is <code>None</code>. This attribute is writable. 363</p></dd></dl> 364 365<hr> 366<div class="header"> 367<p> 368Next: <a href="Finish-Breakpoints-in-Python.html#Finish-Breakpoints-in-Python" accesskey="n" rel="next">Finish Breakpoints in Python</a>, Previous: <a href="Line-Tables-In-Python.html#Line-Tables-In-Python" accesskey="p" rel="previous">Line Tables In Python</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</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> 369</div> 370 371 372 373</body> 374</html> 375