304 lines
16 KiB
HTML
304 lines
16 KiB
HTML
<html lang="en">
|
|
<head>
|
|
<title>Breakpoints In Python - Debugging with GDB</title>
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
<meta name="description" content="Debugging with GDB">
|
|
<meta name="generator" content="makeinfo 4.13">
|
|
<link title="Top" rel="start" href="index.html#Top">
|
|
<link rel="up" href="Python-API.html#Python-API" title="Python API">
|
|
<link rel="prev" href="Line-Tables-In-Python.html#Line-Tables-In-Python" title="Line Tables In Python">
|
|
<link rel="next" href="Finish-Breakpoints-in-Python.html#Finish-Breakpoints-in-Python" title="Finish Breakpoints in Python">
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
|
<!--
|
|
Copyright (C) 1988-2019 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.''
|
|
-->
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
|
<style type="text/css"><!--
|
|
pre.display { font-family:inherit }
|
|
pre.format { font-family:inherit }
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
|
pre.smallexample { font-size:smaller }
|
|
pre.smalllisp { font-size:smaller }
|
|
span.sc { font-variant:small-caps }
|
|
span.roman { font-family:serif; font-weight:normal; }
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
<div class="node">
|
|
<a name="Breakpoints-In-Python"></a>
|
|
<p>
|
|
Next: <a rel="next" accesskey="n" href="Finish-Breakpoints-in-Python.html#Finish-Breakpoints-in-Python">Finish Breakpoints in Python</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="Line-Tables-In-Python.html#Line-Tables-In-Python">Line Tables In Python</a>,
|
|
Up: <a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a>
|
|
<hr>
|
|
</div>
|
|
|
|
<h5 class="subsubsection">23.2.2.30 Manipulating breakpoints using Python</h5>
|
|
|
|
<p><a name="index-breakpoints-in-python-2384"></a><a name="index-gdb_002eBreakpoint-2385"></a>
|
|
Python code can manipulate breakpoints via the <code>gdb.Breakpoint</code>
|
|
class.
|
|
|
|
<p>A breakpoint can be created using one of the two forms of the
|
|
<code>gdb.Breakpoint</code> constructor. The first one accepts a string
|
|
like one would pass to the <code>break</code>
|
|
(see <a href="Set-Breaks.html#Set-Breaks">Setting Breakpoints</a>) and <code>watch</code>
|
|
(see <a href="Set-Watchpoints.html#Set-Watchpoints">Setting Watchpoints</a>) commands, and can be used to
|
|
create both breakpoints and watchpoints. The second accepts separate Python
|
|
arguments similar to <a href="Explicit-Locations.html#Explicit-Locations">Explicit Locations</a>, and can only be used to create
|
|
breakpoints.
|
|
|
|
<div class="defun">
|
|
— Function: <b>Breakpoint.__init__</b> (<var>spec </var><span class="roman">[</span><var>, type </var><span class="roman">][</span><var>, wp_class </var><span class="roman">][</span><var>, internal </var><span class="roman">][</span><var>, temporary </var><span class="roman">][</span><var>, qualified </var><span class="roman">]</span>)<var><a name="index-Breakpoint_002e_005f_005finit_005f_005f-2386"></a></var><br>
|
|
<blockquote><p>Create a new breakpoint according to <var>spec</var>, which is a string naming the
|
|
location of a breakpoint, or an expression that defines a watchpoint. The
|
|
string should describe a location in a format recognized by the <code>break</code>
|
|
command (see <a href="Set-Breaks.html#Set-Breaks">Setting Breakpoints</a>) or, in the case of a
|
|
watchpoint, by the <code>watch</code> command
|
|
(see <a href="Set-Watchpoints.html#Set-Watchpoints">Setting Watchpoints</a>).
|
|
|
|
<p>The optional <var>type</var> argument specifies the type of the breakpoint to create,
|
|
as defined below.
|
|
|
|
<p>The optional <var>wp_class</var> argument defines the class of watchpoint to create,
|
|
if <var>type</var> is <code>gdb.BP_WATCHPOINT</code>. If <var>wp_class</var> is omitted, it
|
|
defaults to <code>gdb.WP_WRITE</code>.
|
|
|
|
<p>The optional <var>internal</var> argument allows the breakpoint to become invisible
|
|
to the user. The breakpoint will neither be reported when created, nor will it
|
|
be listed in the output from <code>info breakpoints</code> (but will be listed with
|
|
the <code>maint info breakpoints</code> command).
|
|
|
|
<p>The optional <var>temporary</var> argument makes the breakpoint a temporary
|
|
breakpoint. Temporary breakpoints are deleted after they have been hit. Any
|
|
further access to the Python breakpoint after it has been hit will result in a
|
|
runtime error (as that breakpoint has now been automatically deleted).
|
|
|
|
<p>The optional <var>qualified</var> argument is a boolean that allows interpreting
|
|
the function passed in <code>spec</code> as a fully-qualified name. It is equivalent
|
|
to <code>break</code>'s <code>-qualified</code> flag (see <a href="Linespec-Locations.html#Linespec-Locations">Linespec Locations</a> and
|
|
<a href="Explicit-Locations.html#Explicit-Locations">Explicit Locations</a>).
|
|
|
|
</blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Function: <b>Breakpoint.__init__</b> (<span class="roman">[</span><var> source </var><span class="roman">][</span><var>, function </var><span class="roman">][</span><var>, label </var><span class="roman">][</span><var>, line </var><span class="roman">]</span><var>, </var><span class="roman">][</span><var> internal </var><span class="roman">][</span><var>, temporary </var><span class="roman">][</span><var>, qualified </var><span class="roman">]</span>)<var><a name="index-Breakpoint_002e_005f_005finit_005f_005f-2387"></a></var><br>
|
|
<blockquote><p>This second form of creating a new breakpoint specifies the explicit
|
|
location (see <a href="Explicit-Locations.html#Explicit-Locations">Explicit Locations</a>) using keywords. The new breakpoint will
|
|
be created in the specified source file <var>source</var>, at the specified
|
|
<var>function</var>, <var>label</var> and <var>line</var>.
|
|
|
|
<p><var>internal</var>, <var>temporary</var> and <var>qualified</var> have the same usage as
|
|
explained previously.
|
|
</p></blockquote></div>
|
|
|
|
<p>The available types are represented by constants defined in the <code>gdb</code>
|
|
module:
|
|
|
|
|
|
<a name="index-BP_005fBREAKPOINT-2388"></a>
|
|
<dl><dt><code>gdb.BP_BREAKPOINT</code><a name="index-gdb_002eBP_005fBREAKPOINT-2389"></a><dd>Normal code breakpoint.
|
|
|
|
<p><a name="index-BP_005fWATCHPOINT-2390"></a><br><dt><code>gdb.BP_WATCHPOINT</code><a name="index-gdb_002eBP_005fWATCHPOINT-2391"></a><dd>Watchpoint breakpoint.
|
|
|
|
<p><a name="index-BP_005fHARDWARE_005fWATCHPOINT-2392"></a><br><dt><code>gdb.BP_HARDWARE_WATCHPOINT</code><a name="index-gdb_002eBP_005fHARDWARE_005fWATCHPOINT-2393"></a><dd>Hardware assisted watchpoint.
|
|
|
|
<p><a name="index-BP_005fREAD_005fWATCHPOINT-2394"></a><br><dt><code>gdb.BP_READ_WATCHPOINT</code><a name="index-gdb_002eBP_005fREAD_005fWATCHPOINT-2395"></a><dd>Hardware assisted read watchpoint.
|
|
|
|
<p><a name="index-BP_005fACCESS_005fWATCHPOINT-2396"></a><br><dt><code>gdb.BP_ACCESS_WATCHPOINT</code><a name="index-gdb_002eBP_005fACCESS_005fWATCHPOINT-2397"></a><dd>Hardware assisted access watchpoint.
|
|
</dl>
|
|
|
|
<p>The available watchpoint types represented by constants are defined in the
|
|
<code>gdb</code> module:
|
|
|
|
|
|
<a name="index-WP_005fREAD-2398"></a>
|
|
<dl><dt><code>gdb.WP_READ</code><a name="index-gdb_002eWP_005fREAD-2399"></a><dd>Read only watchpoint.
|
|
|
|
<p><a name="index-WP_005fWRITE-2400"></a><br><dt><code>gdb.WP_WRITE</code><a name="index-gdb_002eWP_005fWRITE-2401"></a><dd>Write only watchpoint.
|
|
|
|
<p><a name="index-WP_005fACCESS-2402"></a><br><dt><code>gdb.WP_ACCESS</code><a name="index-gdb_002eWP_005fACCESS-2403"></a><dd>Read/Write watchpoint.
|
|
</dl>
|
|
|
|
<div class="defun">
|
|
— Function: <b>Breakpoint.stop</b> (<var>self</var>)<var><a name="index-Breakpoint_002estop-2404"></a></var><br>
|
|
<blockquote><p>The <code>gdb.Breakpoint</code> class can be sub-classed and, in
|
|
particular, you may choose to implement the <code>stop</code> method.
|
|
If this method is defined in a sub-class of <code>gdb.Breakpoint</code>,
|
|
it will be called when the inferior reaches any location of a
|
|
breakpoint which instantiates that sub-class. If the method returns
|
|
<code>True</code>, the inferior will be stopped at the location of the
|
|
breakpoint, otherwise the inferior will continue.
|
|
|
|
<p>If there are multiple breakpoints at the same location with a
|
|
<code>stop</code> method, each one will be called regardless of the
|
|
return status of the previous. This ensures that all <code>stop</code>
|
|
methods have a chance to execute at that location. In this scenario
|
|
if one of the methods returns <code>True</code> but the others return
|
|
<code>False</code>, the inferior will still be stopped.
|
|
|
|
<p>You should not alter the execution state of the inferior (i.e., step,
|
|
next, etc.), alter the current frame context (i.e., change the current
|
|
active frame), or alter, add or delete any breakpoint. As a general
|
|
rule, you should not alter any data within <span class="sc">gdb</span> or the inferior
|
|
at this time.
|
|
|
|
<p>Example <code>stop</code> implementation:
|
|
|
|
<pre class="smallexample"> class MyBreakpoint (gdb.Breakpoint):
|
|
def stop (self):
|
|
inf_val = gdb.parse_and_eval("foo")
|
|
if inf_val == 3:
|
|
return True
|
|
return False
|
|
</pre>
|
|
</blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Function: <b>Breakpoint.is_valid</b> ()<var><a name="index-Breakpoint_002eis_005fvalid-2405"></a></var><br>
|
|
<blockquote><p>Return <code>True</code> if this <code>Breakpoint</code> object is valid,
|
|
<code>False</code> otherwise. A <code>Breakpoint</code> object can become invalid
|
|
if the user deletes the breakpoint. In this case, the object still
|
|
exists, but the underlying breakpoint does not. In the cases of
|
|
watchpoint scope, the watchpoint remains valid even if execution of the
|
|
inferior leaves the scope of that watchpoint.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Function: <b>Breakpoint.delete</b> ()<var><a name="index-Breakpoint_002edelete-2406"></a></var><br>
|
|
<blockquote><p>Permanently deletes the <span class="sc">gdb</span> breakpoint. This also
|
|
invalidates the Python <code>Breakpoint</code> object. Any further access
|
|
to this object's attributes or methods will raise an error.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.enabled</b><var><a name="index-Breakpoint_002eenabled-2407"></a></var><br>
|
|
<blockquote><p>This attribute is <code>True</code> if the breakpoint is enabled, and
|
|
<code>False</code> otherwise. This attribute is writable. You can use it to enable
|
|
or disable the breakpoint.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.silent</b><var><a name="index-Breakpoint_002esilent-2408"></a></var><br>
|
|
<blockquote><p>This attribute is <code>True</code> if the breakpoint is silent, and
|
|
<code>False</code> otherwise. This attribute is writable.
|
|
|
|
<p>Note that a breakpoint can also be silent if it has commands and the
|
|
first command is <code>silent</code>. This is not reported by the
|
|
<code>silent</code> attribute.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.pending</b><var><a name="index-Breakpoint_002epending-2409"></a></var><br>
|
|
<blockquote><p>This attribute is <code>True</code> if the breakpoint is pending, and
|
|
<code>False</code> otherwise. See <a href="Set-Breaks.html#Set-Breaks">Set Breaks</a>. This attribute is
|
|
read-only.
|
|
</p></blockquote></div>
|
|
|
|
<p><a name="python_005fbreakpoint_005fthread"></a>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.thread</b><var><a name="index-Breakpoint_002ethread-2410"></a></var><br>
|
|
<blockquote><p>If the breakpoint is thread-specific, this attribute holds the
|
|
thread's global id. If the breakpoint is not thread-specific, this
|
|
attribute is <code>None</code>. This attribute is writable.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.task</b><var><a name="index-Breakpoint_002etask-2411"></a></var><br>
|
|
<blockquote><p>If the breakpoint is Ada task-specific, this attribute holds the Ada task
|
|
id. If the breakpoint is not task-specific (or the underlying
|
|
language is not Ada), this attribute is <code>None</code>. This attribute
|
|
is writable.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.ignore_count</b><var><a name="index-Breakpoint_002eignore_005fcount-2412"></a></var><br>
|
|
<blockquote><p>This attribute holds the ignore count for the breakpoint, an integer.
|
|
This attribute is writable.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.number</b><var><a name="index-Breakpoint_002enumber-2413"></a></var><br>
|
|
<blockquote><p>This attribute holds the breakpoint's number — the identifier used by
|
|
the user to manipulate the breakpoint. This attribute is not writable.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.type</b><var><a name="index-Breakpoint_002etype-2414"></a></var><br>
|
|
<blockquote><p>This attribute holds the breakpoint's type — the identifier used to
|
|
determine the actual breakpoint type or use-case. This attribute is not
|
|
writable.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.visible</b><var><a name="index-Breakpoint_002evisible-2415"></a></var><br>
|
|
<blockquote><p>This attribute tells whether the breakpoint is visible to the user
|
|
when set, or when the ‘<samp><span class="samp">info breakpoints</span></samp>’ command is run. This
|
|
attribute is not writable.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.temporary</b><var><a name="index-Breakpoint_002etemporary-2416"></a></var><br>
|
|
<blockquote><p>This attribute indicates whether the breakpoint was created as a
|
|
temporary breakpoint. Temporary breakpoints are automatically deleted
|
|
after that breakpoint has been hit. Access to this attribute, and all
|
|
other attributes and functions other than the <code>is_valid</code>
|
|
function, will result in an error after the breakpoint has been hit
|
|
(as it has been automatically deleted). This attribute is not
|
|
writable.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.hit_count</b><var><a name="index-Breakpoint_002ehit_005fcount-2417"></a></var><br>
|
|
<blockquote><p>This attribute holds the hit count for the breakpoint, an integer.
|
|
This attribute is writable, but currently it can only be set to zero.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.location</b><var><a name="index-Breakpoint_002elocation-2418"></a></var><br>
|
|
<blockquote><p>This attribute holds the location of the breakpoint, as specified by
|
|
the user. It is a string. If the breakpoint does not have a location
|
|
(that is, it is a watchpoint) the attribute's value is <code>None</code>. This
|
|
attribute is not writable.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.expression</b><var><a name="index-Breakpoint_002eexpression-2419"></a></var><br>
|
|
<blockquote><p>This attribute holds a breakpoint expression, as specified by
|
|
the user. It is a string. If the breakpoint does not have an
|
|
expression (the breakpoint is not a watchpoint) the attribute's value
|
|
is <code>None</code>. This attribute is not writable.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.condition</b><var><a name="index-Breakpoint_002econdition-2420"></a></var><br>
|
|
<blockquote><p>This attribute holds the condition of the breakpoint, as specified by
|
|
the user. It is a string. If there is no condition, this attribute's
|
|
value is <code>None</code>. This attribute is writable.
|
|
</p></blockquote></div>
|
|
|
|
<div class="defun">
|
|
— Variable: <b>Breakpoint.commands</b><var><a name="index-Breakpoint_002ecommands-2421"></a></var><br>
|
|
<blockquote><p>This attribute holds the commands attached to the breakpoint. If
|
|
there are commands, this attribute's value is a string holding all the
|
|
commands, separated by newlines. If there are no commands, this
|
|
attribute is <code>None</code>. This attribute is writable.
|
|
</p></blockquote></div>
|
|
|
|
</body></html>
|
|
|