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: Events In Python</title> 18 19<meta name="description" content="Debugging with GDB: Events In Python"> 20<meta name="keywords" content="Debugging with GDB: Events 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="Threads-In-Python.html#Threads-In-Python" rel="next" title="Threads In Python"> 30<link href="Inferiors-In-Python.html#Inferiors-In-Python" rel="previous" title="Inferiors 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="Events-In-Python"></a> 65<div class="header"> 66<p> 67Next: <a href="Threads-In-Python.html#Threads-In-Python" accesskey="n" rel="next">Threads In Python</a>, Previous: <a href="Inferiors-In-Python.html#Inferiors-In-Python" accesskey="p" rel="previous">Inferiors 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="Events-In-Python-1"></a> 71<h4 class="subsubsection">23.2.2.17 Events In Python</h4> 72<a name="index-inferior-events-in-Python"></a> 73 74<p><small>GDB</small> provides a general event facility so that Python code can be 75notified of various state changes, particularly changes that occur in 76the inferior. 77</p> 78<p>An <em>event</em> is just an object that describes some state change. The 79type of the object and its attributes will vary depending on the details 80of the change. All the existing events are described below. 81</p> 82<p>In order to be notified of an event, you must register an event handler 83with an <em>event registry</em>. An event registry is an object in the 84<code>gdb.events</code> module which dispatches particular events. A registry 85provides methods to register and unregister event handlers: 86</p> 87<dl> 88<dt><a name="index-EventRegistry_002econnect"></a>Function: <strong>EventRegistry.connect</strong> <em>(object)</em></dt> 89<dd><p>Add the given callable <var>object</var> to the registry. This object will be 90called when an event corresponding to this registry occurs. 91</p></dd></dl> 92 93<dl> 94<dt><a name="index-EventRegistry_002edisconnect"></a>Function: <strong>EventRegistry.disconnect</strong> <em>(object)</em></dt> 95<dd><p>Remove the given <var>object</var> from the registry. Once removed, the object 96will no longer receive notifications of events. 97</p></dd></dl> 98 99<p>Here is an example: 100</p> 101<div class="smallexample"> 102<pre class="smallexample">def exit_handler (event): 103 print "event type: exit" 104 print "exit code: %d" % (event.exit_code) 105 106gdb.events.exited.connect (exit_handler) 107</pre></div> 108 109<p>In the above example we connect our handler <code>exit_handler</code> to the 110registry <code>events.exited</code>. Once connected, <code>exit_handler</code> gets 111called when the inferior exits. The argument <em>event</em> in this example is 112of type <code>gdb.ExitedEvent</code>. As you can see in the example the 113<code>ExitedEvent</code> object has an attribute which indicates the exit code of 114the inferior. 115</p> 116<p>The following is a listing of the event registries that are available and 117details of the events they emit: 118</p> 119<dl compact="compact"> 120<dt><code>events.cont</code></dt> 121<dd><p>Emits <code>gdb.ThreadEvent</code>. 122</p> 123<p>Some events can be thread specific when <small>GDB</small> is running in non-stop 124mode. When represented in Python, these events all extend 125<code>gdb.ThreadEvent</code>. Note, this event is not emitted directly; instead, 126events which are emitted by this or other modules might extend this event. 127Examples of these events are <code>gdb.BreakpointEvent</code> and 128<code>gdb.ContinueEvent</code>. 129</p> 130<dl> 131<dt><a name="index-ThreadEvent_002einferior_005fthread"></a>Variable: <strong>ThreadEvent.inferior_thread</strong></dt> 132<dd><p>In non-stop mode this attribute will be set to the specific thread which was 133involved in the emitted event. Otherwise, it will be set to <code>None</code>. 134</p></dd></dl> 135 136<p>Emits <code>gdb.ContinueEvent</code> which extends <code>gdb.ThreadEvent</code>. 137</p> 138<p>This event indicates that the inferior has been continued after a stop. For 139inherited attribute refer to <code>gdb.ThreadEvent</code> above. 140</p> 141</dd> 142<dt><code>events.exited</code></dt> 143<dd><p>Emits <code>events.ExitedEvent</code> which indicates that the inferior has exited. 144<code>events.ExitedEvent</code> has two attributes: 145</p><dl> 146<dt><a name="index-ExitedEvent_002eexit_005fcode"></a>Variable: <strong>ExitedEvent.exit_code</strong></dt> 147<dd><p>An integer representing the exit code, if available, which the inferior 148has returned. (The exit code could be unavailable if, for example, 149<small>GDB</small> detaches from the inferior.) If the exit code is unavailable, 150the attribute does not exist. 151</p></dd></dl> 152<dl> 153<dt><a name="index-ExitedEvent_002einferior"></a>Variable: <strong>ExitedEvent.inferior</strong></dt> 154<dd><p>A reference to the inferior which triggered the <code>exited</code> event. 155</p></dd></dl> 156 157</dd> 158<dt><code>events.stop</code></dt> 159<dd><p>Emits <code>gdb.StopEvent</code> which extends <code>gdb.ThreadEvent</code>. 160</p> 161<p>Indicates that the inferior has stopped. All events emitted by this registry 162extend StopEvent. As a child of <code>gdb.ThreadEvent</code>, <code>gdb.StopEvent</code> 163will indicate the stopped thread when <small>GDB</small> is running in non-stop 164mode. Refer to <code>gdb.ThreadEvent</code> above for more details. 165</p> 166<p>Emits <code>gdb.SignalEvent</code> which extends <code>gdb.StopEvent</code>. 167</p> 168<p>This event indicates that the inferior or one of its threads has received as 169signal. <code>gdb.SignalEvent</code> has the following attributes: 170</p> 171<dl> 172<dt><a name="index-SignalEvent_002estop_005fsignal"></a>Variable: <strong>SignalEvent.stop_signal</strong></dt> 173<dd><p>A string representing the signal received by the inferior. A list of possible 174signal values can be obtained by running the command <code>info signals</code> in 175the <small>GDB</small> command prompt. 176</p></dd></dl> 177 178<p>Also emits <code>gdb.BreakpointEvent</code> which extends <code>gdb.StopEvent</code>. 179</p> 180<p><code>gdb.BreakpointEvent</code> event indicates that one or more breakpoints have 181been hit, and has the following attributes: 182</p> 183<dl> 184<dt><a name="index-BreakpointEvent_002ebreakpoints"></a>Variable: <strong>BreakpointEvent.breakpoints</strong></dt> 185<dd><p>A sequence containing references to all the breakpoints (type 186<code>gdb.Breakpoint</code>) that were hit. 187See <a href="Breakpoints-In-Python.html#Breakpoints-In-Python">Breakpoints In Python</a>, for details of the <code>gdb.Breakpoint</code> object. 188</p></dd></dl> 189<dl> 190<dt><a name="index-BreakpointEvent_002ebreakpoint"></a>Variable: <strong>BreakpointEvent.breakpoint</strong></dt> 191<dd><p>A reference to the first breakpoint that was hit. 192This function is maintained for backward compatibility and is now deprecated 193in favor of the <code>gdb.BreakpointEvent.breakpoints</code> attribute. 194</p></dd></dl> 195 196</dd> 197<dt><code>events.new_objfile</code></dt> 198<dd><p>Emits <code>gdb.NewObjFileEvent</code> which indicates that a new object file has 199been loaded by <small>GDB</small>. <code>gdb.NewObjFileEvent</code> has one attribute: 200</p> 201<dl> 202<dt><a name="index-NewObjFileEvent_002enew_005fobjfile"></a>Variable: <strong>NewObjFileEvent.new_objfile</strong></dt> 203<dd><p>A reference to the object file (<code>gdb.Objfile</code>) which has been loaded. 204See <a href="Objfiles-In-Python.html#Objfiles-In-Python">Objfiles In Python</a>, for details of the <code>gdb.Objfile</code> object. 205</p></dd></dl> 206 207</dd> 208<dt><code>events.clear_objfiles</code></dt> 209<dd><p>Emits <code>gdb.ClearObjFilesEvent</code> which indicates that the list of object 210files for a program space has been reset. 211<code>gdb.ClearObjFilesEvent</code> has one attribute: 212</p> 213<dl> 214<dt><a name="index-ClearObjFilesEvent_002eprogspace"></a>Variable: <strong>ClearObjFilesEvent.progspace</strong></dt> 215<dd><p>A reference to the program space (<code>gdb.Progspace</code>) whose objfile list has 216been cleared. See <a href="Progspaces-In-Python.html#Progspaces-In-Python">Progspaces In Python</a>. 217</p></dd></dl> 218 219</dd> 220<dt><code>events.inferior_call</code></dt> 221<dd><p>Emits events just before and after a function in the inferior is 222called by <small>GDB</small>. Before an inferior call, this emits an event 223of type <code>gdb.InferiorCallPreEvent</code>, and after an inferior call, 224this emits an event of type <code>gdb.InferiorCallPostEvent</code>. 225</p> 226<dl compact="compact"> 227<dd><a name="index-gdb_002eInferiorCallPreEvent"></a> 228</dd> 229<dt><code><code>gdb.InferiorCallPreEvent</code></code></dt> 230<dd><p>Indicates that a function in the inferior is about to be called. 231</p> 232<dl> 233<dt><a name="index-InferiorCallPreEvent_002eptid"></a>Variable: <strong>InferiorCallPreEvent.ptid</strong></dt> 234<dd><p>The thread in which the call will be run. 235</p></dd></dl> 236 237<dl> 238<dt><a name="index-InferiorCallPreEvent_002eaddress"></a>Variable: <strong>InferiorCallPreEvent.address</strong></dt> 239<dd><p>The location of the function to be called. 240</p></dd></dl> 241 242<a name="index-gdb_002eInferiorCallPostEvent"></a> 243</dd> 244<dt><code><code>gdb.InferiorCallPostEvent</code></code></dt> 245<dd><p>Indicates that a function in the inferior has just been called. 246</p> 247<dl> 248<dt><a name="index-InferiorCallPostEvent_002eptid"></a>Variable: <strong>InferiorCallPostEvent.ptid</strong></dt> 249<dd><p>The thread in which the call was run. 250</p></dd></dl> 251 252<dl> 253<dt><a name="index-InferiorCallPostEvent_002eaddress"></a>Variable: <strong>InferiorCallPostEvent.address</strong></dt> 254<dd><p>The location of the function that was called. 255</p></dd></dl> 256</dd> 257</dl> 258 259</dd> 260<dt><code>events.memory_changed</code></dt> 261<dd><p>Emits <code>gdb.MemoryChangedEvent</code> which indicates that the memory of the 262inferior has been modified by the <small>GDB</small> user, for instance via a 263command like <code>set *addr = value</code><!-- /@w -->. The event has the following 264attributes: 265</p> 266<dl> 267<dt><a name="index-MemoryChangedEvent_002eaddress"></a>Variable: <strong>MemoryChangedEvent.address</strong></dt> 268<dd><p>The start address of the changed region. 269</p></dd></dl> 270 271<dl> 272<dt><a name="index-MemoryChangedEvent_002elength"></a>Variable: <strong>MemoryChangedEvent.length</strong></dt> 273<dd><p>Length in bytes of the changed region. 274</p></dd></dl> 275 276</dd> 277<dt><code>events.register_changed</code></dt> 278<dd><p>Emits <code>gdb.RegisterChangedEvent</code> which indicates that a register in the 279inferior has been modified by the <small>GDB</small> user. 280</p> 281<dl> 282<dt><a name="index-RegisterChangedEvent_002eframe"></a>Variable: <strong>RegisterChangedEvent.frame</strong></dt> 283<dd><p>A gdb.Frame object representing the frame in which the register was modified. 284</p></dd></dl> 285<dl> 286<dt><a name="index-RegisterChangedEvent_002eregnum"></a>Variable: <strong>RegisterChangedEvent.regnum</strong></dt> 287<dd><p>Denotes which register was modified. 288</p></dd></dl> 289 290</dd> 291<dt><code>events.breakpoint_created</code></dt> 292<dd><p>This is emitted when a new breakpoint has been created. The argument 293that is passed is the new <code>gdb.Breakpoint</code> object. 294</p> 295</dd> 296<dt><code>events.breakpoint_modified</code></dt> 297<dd><p>This is emitted when a breakpoint has been modified in some way. The 298argument that is passed is the new <code>gdb.Breakpoint</code> object. 299</p> 300</dd> 301<dt><code>events.breakpoint_deleted</code></dt> 302<dd><p>This is emitted when a breakpoint has been deleted. The argument that 303is passed is the <code>gdb.Breakpoint</code> object. When this event is 304emitted, the <code>gdb.Breakpoint</code> object will already be in its 305invalid state; that is, the <code>is_valid</code> method will return 306<code>False</code>. 307</p> 308</dd> 309<dt><code>events.before_prompt</code></dt> 310<dd><p>This event carries no payload. It is emitted each time <small>GDB</small> 311presents a prompt to the user. 312</p> 313</dd> 314<dt><code>events.new_inferior</code></dt> 315<dd><p>This is emitted when a new inferior is created. Note that the 316inferior is not necessarily running; in fact, it may not even have an 317associated executable. 318</p> 319<p>The event is of type <code>gdb.NewInferiorEvent</code>. This has a single 320attribute: 321</p> 322<dl> 323<dt><a name="index-NewInferiorEvent_002einferior"></a>Variable: <strong>NewInferiorEvent.inferior</strong></dt> 324<dd><p>The new inferior, a <code>gdb.Inferior</code> object. 325</p></dd></dl> 326 327</dd> 328<dt><code>events.inferior_deleted</code></dt> 329<dd><p>This is emitted when an inferior has been deleted. Note that this is 330not the same as process exit; it is notified when the inferior itself 331is removed, say via <code>remove-inferiors</code>. 332</p> 333<p>The event is of type <code>gdb.InferiorDeletedEvent</code>. This has a single 334attribute: 335</p> 336<dl> 337<dt><a name="index-NewInferiorEvent_002einferior-1"></a>Variable: <strong>NewInferiorEvent.inferior</strong></dt> 338<dd><p>The inferior that is being removed, a <code>gdb.Inferior</code> object. 339</p></dd></dl> 340 341</dd> 342<dt><code>events.new_thread</code></dt> 343<dd><p>This is emitted when <small>GDB</small> notices a new thread. The event is of 344type <code>gdb.NewThreadEvent</code>, which extends <code>gdb.ThreadEvent</code>. 345This has a single attribute: 346</p> 347<dl> 348<dt><a name="index-NewThreadEvent_002einferior_005fthread"></a>Variable: <strong>NewThreadEvent.inferior_thread</strong></dt> 349<dd><p>The new thread. 350</p></dd></dl> 351 352</dd> 353</dl> 354 355<hr> 356<div class="header"> 357<p> 358Next: <a href="Threads-In-Python.html#Threads-In-Python" accesskey="n" rel="next">Threads In Python</a>, Previous: <a href="Inferiors-In-Python.html#Inferiors-In-Python" accesskey="p" rel="previous">Inferiors 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> 359</div> 360 361 362 363</body> 364</html> 365