1<html lang="en"> 2<head> 3<title>Events In Python - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Python-API.html#Python-API" title="Python API"> 9<link rel="prev" href="Inferiors-In-Python.html#Inferiors-In-Python" title="Inferiors In Python"> 10<link rel="next" href="Threads-In-Python.html#Threads-In-Python" title="Threads In Python"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988-2013 Free Software Foundation, Inc. 14 15Permission is granted to copy, distribute and/or modify this document 16under the terms of the GNU Free Documentation License, Version 1.3 or 17any later version published by the Free Software Foundation; with the 18Invariant Sections being ``Free Software'' and ``Free Software Needs 19Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 20and with the Back-Cover Texts as in (a) below. 21 22(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 23this GNU Manual. Buying copies from GNU Press supports the FSF in 24developing GNU and promoting software freedom.'' 25--> 26<meta http-equiv="Content-Style-Type" content="text/css"> 27<style type="text/css"><!-- 28 pre.display { font-family:inherit } 29 pre.format { font-family:inherit } 30 pre.smalldisplay { font-family:inherit; font-size:smaller } 31 pre.smallformat { font-family:inherit; font-size:smaller } 32 pre.smallexample { font-size:smaller } 33 pre.smalllisp { font-size:smaller } 34 span.sc { font-variant:small-caps } 35 span.roman { font-family:serif; font-weight:normal; } 36 span.sansserif { font-family:sans-serif; font-weight:normal; } 37--></style> 38<link rel="stylesheet" type="text/css" href="../cs.css"> 39</head> 40<body> 41<div class="node"> 42<a name="Events-In-Python"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Threads-In-Python.html#Threads-In-Python">Threads In Python</a>, 45Previous: <a rel="previous" accesskey="p" href="Inferiors-In-Python.html#Inferiors-In-Python">Inferiors In Python</a>, 46Up: <a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a> 47<hr> 48</div> 49 50<h5 class="subsubsection">23.2.2.13 Events In Python</h5> 51 52<p><a name="index-inferior-events-in-Python-1913"></a> 53<span class="sc">gdb</span> provides a general event facility so that Python code can be 54notified of various state changes, particularly changes that occur in 55the inferior. 56 57 <p>An <dfn>event</dfn> is just an object that describes some state change. The 58type of the object and its attributes will vary depending on the details 59of the change. All the existing events are described below. 60 61 <p>In order to be notified of an event, you must register an event handler 62with an <dfn>event registry</dfn>. An event registry is an object in the 63<code>gdb.events</code> module which dispatches particular events. A registry 64provides methods to register and unregister event handlers: 65 66<div class="defun"> 67— Function: <b>EventRegistry.connect</b> (<var>object</var>)<var><a name="index-EventRegistry_002econnect-1914"></a></var><br> 68<blockquote><p>Add the given callable <var>object</var> to the registry. This object will be 69called when an event corresponding to this registry occurs. 70</p></blockquote></div> 71 72<div class="defun"> 73— Function: <b>EventRegistry.disconnect</b> (<var>object</var>)<var><a name="index-EventRegistry_002edisconnect-1915"></a></var><br> 74<blockquote><p>Remove the given <var>object</var> from the registry. Once removed, the object 75will no longer receive notifications of events. 76</p></blockquote></div> 77 78 <p>Here is an example: 79 80<pre class="smallexample"> def exit_handler (event): 81 print "event type: exit" 82 print "exit code: %d" % (event.exit_code) 83 84 gdb.events.exited.connect (exit_handler) 85</pre> 86 <p>In the above example we connect our handler <code>exit_handler</code> to the 87registry <code>events.exited</code>. Once connected, <code>exit_handler</code> gets 88called when the inferior exits. The argument <dfn>event</dfn> in this example is 89of type <code>gdb.ExitedEvent</code>. As you can see in the example the 90<code>ExitedEvent</code> object has an attribute which indicates the exit code of 91the inferior. 92 93 <p>The following is a listing of the event registries that are available and 94details of the events they emit: 95 96 <dl> 97<dt><code>events.cont</code><dd>Emits <code>gdb.ThreadEvent</code>. 98 99 <p>Some events can be thread specific when <span class="sc">gdb</span> is running in non-stop 100mode. When represented in Python, these events all extend 101<code>gdb.ThreadEvent</code>. Note, this event is not emitted directly; instead, 102events which are emitted by this or other modules might extend this event. 103Examples of these events are <code>gdb.BreakpointEvent</code> and 104<code>gdb.ContinueEvent</code>. 105 106 <div class="defun"> 107— Variable: <b>ThreadEvent.inferior_thread</b><var><a name="index-ThreadEvent_002einferior_005fthread-1916"></a></var><br> 108<blockquote> <p>In non-stop mode this attribute will be set to the specific thread which was 109involved in the emitted event. Otherwise, it will be set to <code>None</code>. 110</p></blockquote></div> 111 112 <p>Emits <code>gdb.ContinueEvent</code> which extends <code>gdb.ThreadEvent</code>. 113 114 <p>This event indicates that the inferior has been continued after a stop. For 115inherited attribute refer to <code>gdb.ThreadEvent</code> above. 116 117 <br><dt><code>events.exited</code><dd>Emits <code>events.ExitedEvent</code> which indicates that the inferior has exited. 118<code>events.ExitedEvent</code> has two attributes: 119 120 <div class="defun"> 121— Variable: <b>ExitedEvent.exit_code</b><var><a name="index-ExitedEvent_002eexit_005fcode-1917"></a></var><br> 122<blockquote> <p>An integer representing the exit code, if available, which the inferior 123has returned. (The exit code could be unavailable if, for example, 124<span class="sc">gdb</span> detaches from the inferior.) If the exit code is unavailable, 125the attribute does not exist. 126</p></blockquote></div> 127 128 <div class="defun"> 129— Variable: <b>ExitedEvent</b><var> inferior<a name="index-ExitedEvent-1918"></a></var><br> 130<blockquote> <p>A reference to the inferior which triggered the <code>exited</code> event. 131</p></blockquote></div> 132 133 <br><dt><code>events.stop</code><dd>Emits <code>gdb.StopEvent</code> which extends <code>gdb.ThreadEvent</code>. 134 135 <p>Indicates that the inferior has stopped. All events emitted by this registry 136extend StopEvent. As a child of <code>gdb.ThreadEvent</code>, <code>gdb.StopEvent</code> 137will indicate the stopped thread when <span class="sc">gdb</span> is running in non-stop 138mode. Refer to <code>gdb.ThreadEvent</code> above for more details. 139 140 <p>Emits <code>gdb.SignalEvent</code> which extends <code>gdb.StopEvent</code>. 141 142 <p>This event indicates that the inferior or one of its threads has received as 143signal. <code>gdb.SignalEvent</code> has the following attributes: 144 145 <div class="defun"> 146— Variable: <b>SignalEvent.stop_signal</b><var><a name="index-SignalEvent_002estop_005fsignal-1919"></a></var><br> 147<blockquote> <p>A string representing the signal received by the inferior. A list of possible 148signal values can be obtained by running the command <code>info signals</code> in 149the <span class="sc">gdb</span> command prompt. 150</p></blockquote></div> 151 152 <p>Also emits <code>gdb.BreakpointEvent</code> which extends <code>gdb.StopEvent</code>. 153 154 <p><code>gdb.BreakpointEvent</code> event indicates that one or more breakpoints have 155been hit, and has the following attributes: 156 157 <div class="defun"> 158— Variable: <b>BreakpointEvent.breakpoints</b><var><a name="index-BreakpointEvent_002ebreakpoints-1920"></a></var><br> 159<blockquote> <p>A sequence containing references to all the breakpoints (type 160<code>gdb.Breakpoint</code>) that were hit. 161See <a href="Breakpoints-In-Python.html#Breakpoints-In-Python">Breakpoints In Python</a>, for details of the <code>gdb.Breakpoint</code> object. 162</p></blockquote></div> 163 164 <div class="defun"> 165— Variable: <b>BreakpointEvent.breakpoint</b><var><a name="index-BreakpointEvent_002ebreakpoint-1921"></a></var><br> 166<blockquote> <p>A reference to the first breakpoint that was hit. 167This function is maintained for backward compatibility and is now deprecated 168in favor of the <code>gdb.BreakpointEvent.breakpoints</code> attribute. 169</p></blockquote></div> 170 171 <br><dt><code>events.new_objfile</code><dd>Emits <code>gdb.NewObjFileEvent</code> which indicates that a new object file has 172been loaded by <span class="sc">gdb</span>. <code>gdb.NewObjFileEvent</code> has one attribute: 173 174 <div class="defun"> 175— Variable: <b>NewObjFileEvent.new_objfile</b><var><a name="index-NewObjFileEvent_002enew_005fobjfile-1922"></a></var><br> 176<blockquote> <p>A reference to the object file (<code>gdb.Objfile</code>) which has been loaded. 177See <a href="Objfiles-In-Python.html#Objfiles-In-Python">Objfiles In Python</a>, for details of the <code>gdb.Objfile</code> object. 178</p></blockquote></div> 179 180 </dl> 181 182 </body></html> 183 184