1<html lang="en"> 2<head> 3<title>Basic 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="next" href="Exception-Handling.html#Exception-Handling" title="Exception Handling"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12Copyright (C) 1988-2013 Free Software Foundation, Inc. 13 14Permission is granted to copy, distribute and/or modify this document 15under the terms of the GNU Free Documentation License, Version 1.3 or 16any later version published by the Free Software Foundation; with the 17Invariant Sections being ``Free Software'' and ``Free Software Needs 18Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 19and with the Back-Cover Texts as in (a) below. 20 21(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 22this GNU Manual. Buying copies from GNU Press supports the FSF in 23developing GNU and promoting software freedom.'' 24--> 25<meta http-equiv="Content-Style-Type" content="text/css"> 26<style type="text/css"><!-- 27 pre.display { font-family:inherit } 28 pre.format { font-family:inherit } 29 pre.smalldisplay { font-family:inherit; font-size:smaller } 30 pre.smallformat { font-family:inherit; font-size:smaller } 31 pre.smallexample { font-size:smaller } 32 pre.smalllisp { font-size:smaller } 33 span.sc { font-variant:small-caps } 34 span.roman { font-family:serif; font-weight:normal; } 35 span.sansserif { font-family:sans-serif; font-weight:normal; } 36--></style> 37<link rel="stylesheet" type="text/css" href="../cs.css"> 38</head> 39<body> 40<div class="node"> 41<a name="Basic-Python"></a> 42<p> 43Next: <a rel="next" accesskey="n" href="Exception-Handling.html#Exception-Handling">Exception Handling</a>, 44Up: <a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a> 45<hr> 46</div> 47 48<h5 class="subsubsection">23.2.2.1 Basic Python</h5> 49 50<p><a name="index-python-stdout-1729"></a><a name="index-python-pagination-1730"></a>At startup, <span class="sc">gdb</span> overrides Python's <code>sys.stdout</code> and 51<code>sys.stderr</code> to print using <span class="sc">gdb</span>'s output-paging streams. 52A Python program which outputs to one of these streams may have its 53output interrupted by the user (see <a href="Screen-Size.html#Screen-Size">Screen Size</a>). In this 54situation, a Python <code>KeyboardInterrupt</code> exception is thrown. 55 56 <p>Some care must be taken when writing Python code to run in 57<span class="sc">gdb</span>. Two things worth noting in particular: 58 59 <ul> 60<li><span class="sc">gdb</span> install handlers for <code>SIGCHLD</code> and <code>SIGINT</code>. 61Python code must not override these, or even change the options using 62<code>sigaction</code>. If your program changes the handling of these 63signals, <span class="sc">gdb</span> will most likely stop working correctly. Note 64that it is unfortunately common for GUI toolkits to install a 65<code>SIGCHLD</code> handler. 66 67 <li><span class="sc">gdb</span> takes care to mark its internal file descriptors as 68close-on-exec. However, this cannot be done in a thread-safe way on 69all platforms. Your Python programs should be aware of this and 70should both create new file descriptors with the close-on-exec flag 71set and arrange to close unneeded file descriptors before starting a 72child process. 73</ul> 74 75 <p><a name="index-python-functions-1731"></a><a name="index-python-module-1732"></a><a name="index-gdb-module-1733"></a><span class="sc">gdb</span> introduces a new Python module, named <code>gdb</code>. All 76methods and classes added by <span class="sc">gdb</span> are placed in this module. 77<span class="sc">gdb</span> automatically <code>import</code>s the <code>gdb</code> module for 78use in all scripts evaluated by the <code>python</code> command. 79 80 <p><a name="index-gdb_002ePYTHONDIR-1734"></a> 81 82<div class="defun"> 83— Variable: <b>gdb.PYTHONDIR</b><var><a name="index-gdb_002ePYTHONDIR-1735"></a></var><br> 84<blockquote><p>A string containing the python directory (see <a href="Python.html#Python">Python</a>). 85</p></blockquote></div> 86 87 <p><a name="index-gdb_002eexecute-1736"></a> 88 89<div class="defun"> 90— Function: <b>gdb.execute</b> (<var>command </var><span class="roman">[</span><var>, from_tty </var><span class="roman">[</span><var>, to_string</var><span class="roman">]]</span>)<var><a name="index-gdb_002eexecute-1737"></a></var><br> 91<blockquote><p>Evaluate <var>command</var>, a string, as a <span class="sc">gdb</span> CLI command. 92If a GDB exception happens while <var>command</var> runs, it is 93translated as described in <a href="Exception-Handling.html#Exception-Handling">Exception Handling</a>. 94 95 <p><var>from_tty</var> specifies whether <span class="sc">gdb</span> ought to consider this 96command as having originated from the user invoking it interactively. 97It must be a boolean value. If omitted, it defaults to <code>False</code>. 98 99 <p>By default, any output produced by <var>command</var> is sent to 100<span class="sc">gdb</span>'s standard output. If the <var>to_string</var> parameter is 101<code>True</code>, then output will be collected by <code>gdb.execute</code> and 102returned as a string. The default is <code>False</code>, in which case the 103return value is <code>None</code>. If <var>to_string</var> is <code>True</code>, the 104<span class="sc">gdb</span> virtual terminal will be temporarily set to unlimited width 105and height, and its pagination will be disabled; see <a href="Screen-Size.html#Screen-Size">Screen Size</a>. 106</p></blockquote></div> 107 108 <p><a name="index-gdb_002ebreakpoints-1738"></a> 109 110<div class="defun"> 111— Function: <b>gdb.breakpoints</b> ()<var><a name="index-gdb_002ebreakpoints-1739"></a></var><br> 112<blockquote><p>Return a sequence holding all of <span class="sc">gdb</span>'s breakpoints. 113See <a href="Breakpoints-In-Python.html#Breakpoints-In-Python">Breakpoints In Python</a>, for more information. 114</p></blockquote></div> 115 116 <p><a name="index-gdb_002eparameter-1740"></a> 117 118<div class="defun"> 119— Function: <b>gdb.parameter</b> (<var>parameter</var>)<var><a name="index-gdb_002eparameter-1741"></a></var><br> 120<blockquote><p>Return the value of a <span class="sc">gdb</span> parameter. <var>parameter</var> is a 121string naming the parameter to look up; <var>parameter</var> may contain 122spaces if the parameter has a multi-part name. For example, 123‘<samp><span class="samp">print object</span></samp>’ is a valid parameter name. 124 125 <p>If the named parameter does not exist, this function throws a 126<code>gdb.error</code> (see <a href="Exception-Handling.html#Exception-Handling">Exception Handling</a>). Otherwise, the 127parameter's value is converted to a Python value of the appropriate 128type, and returned. 129</p></blockquote></div> 130 131 <p><a name="index-gdb_002ehistory-1742"></a> 132 133<div class="defun"> 134— Function: <b>gdb.history</b> (<var>number</var>)<var><a name="index-gdb_002ehistory-1743"></a></var><br> 135<blockquote><p>Return a value from <span class="sc">gdb</span>'s value history (see <a href="Value-History.html#Value-History">Value History</a>). <var>number</var> indicates which history element to return. 136If <var>number</var> is negative, then <span class="sc">gdb</span> will take its absolute value 137and count backward from the last element (i.e., the most recent element) to 138find the value to return. If <var>number</var> is zero, then <span class="sc">gdb</span> will 139return the most recent element. If the element specified by <var>number</var> 140doesn't exist in the value history, a <code>gdb.error</code> exception will be 141raised. 142 143 <p>If no exception is raised, the return value is always an instance of 144<code>gdb.Value</code> (see <a href="Values-From-Inferior.html#Values-From-Inferior">Values From Inferior</a>). 145</p></blockquote></div> 146 147 <p><a name="index-gdb_002eparse_005fand_005feval-1744"></a> 148 149<div class="defun"> 150— Function: <b>gdb.parse_and_eval</b> (<var>expression</var>)<var><a name="index-gdb_002eparse_005fand_005feval-1745"></a></var><br> 151<blockquote><p>Parse <var>expression</var> as an expression in the current language, 152evaluate it, and return the result as a <code>gdb.Value</code>. 153<var>expression</var> must be a string. 154 155 <p>This function can be useful when implementing a new command 156(see <a href="Commands-In-Python.html#Commands-In-Python">Commands In Python</a>), as it provides a way to parse the 157command's argument as an expression. It is also useful simply to 158compute values, for example, it is the only way to get the value of a 159convenience variable (see <a href="Convenience-Vars.html#Convenience-Vars">Convenience Vars</a>) as a <code>gdb.Value</code>. 160</p></blockquote></div> 161 162 <p><a name="index-gdb_002efind_005fpc_005fline-1746"></a> 163 164<div class="defun"> 165— Function: <b>gdb.find_pc_line</b> (<var>pc</var>)<var><a name="index-gdb_002efind_005fpc_005fline-1747"></a></var><br> 166<blockquote><p>Return the <code>gdb.Symtab_and_line</code> object corresponding to the 167<var>pc</var> value. See <a href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python">Symbol Tables In Python</a>. If an invalid 168value of <var>pc</var> is passed as an argument, then the <code>symtab</code> and 169<code>line</code> attributes of the returned <code>gdb.Symtab_and_line</code> object 170will be <code>None</code> and 0 respectively. 171</p></blockquote></div> 172 173 <p><a name="index-gdb_002epost_005fevent-1748"></a> 174 175<div class="defun"> 176— Function: <b>gdb.post_event</b> (<var>event</var>)<var><a name="index-gdb_002epost_005fevent-1749"></a></var><br> 177<blockquote><p>Put <var>event</var>, a callable object taking no arguments, into 178<span class="sc">gdb</span>'s internal event queue. This callable will be invoked at 179some later point, during <span class="sc">gdb</span>'s event processing. Events 180posted using <code>post_event</code> will be run in the order in which they 181were posted; however, there is no way to know when they will be 182processed relative to other events inside <span class="sc">gdb</span>. 183 184 <p><span class="sc">gdb</span> is not thread-safe. If your Python program uses multiple 185threads, you must be careful to only call <span class="sc">gdb</span>-specific 186functions in the main <span class="sc">gdb</span> thread. <code>post_event</code> ensures 187this. For example: 188 189 <pre class="smallexample"> (gdb) python 190 >import threading 191 > 192 >class Writer(): 193 > def __init__(self, message): 194 > self.message = message; 195 > def __call__(self): 196 > gdb.write(self.message) 197 > 198 >class MyThread1 (threading.Thread): 199 > def run (self): 200 > gdb.post_event(Writer("Hello ")) 201 > 202 >class MyThread2 (threading.Thread): 203 > def run (self): 204 > gdb.post_event(Writer("World\n")) 205 > 206 >MyThread1().start() 207 >MyThread2().start() 208 >end 209 (gdb) Hello World 210</pre> 211 </blockquote></div> 212 213 <p><a name="index-gdb_002ewrite-1750"></a> 214 215<div class="defun"> 216— Function: <b>gdb.write</b> (<var>string </var><span class="roman">[</span><var>, stream</var>])<var><a name="index-gdb_002ewrite-1751"></a></var><br> 217<blockquote><p>Print a string to <span class="sc">gdb</span>'s paginated output stream. The 218optional <var>stream</var> determines the stream to print to. The default 219stream is <span class="sc">gdb</span>'s standard output stream. Possible stream 220values are: 221 222 223<a name="index-STDOUT-1752"></a> 224<a name="index-gdb_002eSTDOUT-1753"></a> 225<dl><dt><code>gdb.STDOUT</code><dd><span class="sc">gdb</span>'s standard output stream. 226 227 <p><a name="index-STDERR-1754"></a><a name="index-gdb_002eSTDERR-1755"></a><br><dt><code>gdb.STDERR</code><dd><span class="sc">gdb</span>'s standard error stream. 228 229 <p><a name="index-STDLOG-1756"></a><a name="index-gdb_002eSTDLOG-1757"></a><br><dt><code>gdb.STDLOG</code><dd><span class="sc">gdb</span>'s log stream (see <a href="Logging-Output.html#Logging-Output">Logging Output</a>). 230</dl> 231 232 <p>Writing to <code>sys.stdout</code> or <code>sys.stderr</code> will automatically 233call this function and will automatically direct the output to the 234relevant stream. 235</p></blockquote></div> 236 237 <p><a name="index-gdb_002eflush-1758"></a> 238 239<div class="defun"> 240— Function: <b>gdb.flush</b> ()<var><a name="index-gdb_002eflush-1759"></a></var><br> 241<blockquote><p>Flush the buffer of a <span class="sc">gdb</span> paginated stream so that the 242contents are displayed immediately. <span class="sc">gdb</span> will flush the 243contents of a stream automatically when it encounters a newline in the 244buffer. The optional <var>stream</var> determines the stream to flush. The 245default stream is <span class="sc">gdb</span>'s standard output stream. Possible 246stream values are: 247 248 249<a name="index-STDOUT-1760"></a> 250<a name="index-gdb_002eSTDOUT-1761"></a> 251<dl><dt><code>gdb.STDOUT</code><dd><span class="sc">gdb</span>'s standard output stream. 252 253 <p><a name="index-STDERR-1762"></a><a name="index-gdb_002eSTDERR-1763"></a><br><dt><code>gdb.STDERR</code><dd><span class="sc">gdb</span>'s standard error stream. 254 255 <p><a name="index-STDLOG-1764"></a><a name="index-gdb_002eSTDLOG-1765"></a><br><dt><code>gdb.STDLOG</code><dd><span class="sc">gdb</span>'s log stream (see <a href="Logging-Output.html#Logging-Output">Logging Output</a>). 256 257 </dl> 258 259 <p>Flushing <code>sys.stdout</code> or <code>sys.stderr</code> will automatically 260call this function for the relevant stream. 261</p></blockquote></div> 262 263 <p><a name="index-gdb_002etarget_005fcharset-1766"></a> 264 265<div class="defun"> 266— Function: <b>gdb.target_charset</b> ()<var><a name="index-gdb_002etarget_005fcharset-1767"></a></var><br> 267<blockquote><p>Return the name of the current target character set (see <a href="Character-Sets.html#Character-Sets">Character Sets</a>). This differs from <code>gdb.parameter('target-charset')</code> in 268that ‘<samp><span class="samp">auto</span></samp>’ is never returned. 269</p></blockquote></div> 270 271 <p><a name="index-gdb_002etarget_005fwide_005fcharset-1768"></a> 272 273<div class="defun"> 274— Function: <b>gdb.target_wide_charset</b> ()<var><a name="index-gdb_002etarget_005fwide_005fcharset-1769"></a></var><br> 275<blockquote><p>Return the name of the current target wide character set 276(see <a href="Character-Sets.html#Character-Sets">Character Sets</a>). This differs from 277<code>gdb.parameter('target-wide-charset')</code> in that ‘<samp><span class="samp">auto</span></samp>’ is 278never returned. 279</p></blockquote></div> 280 281 <p><a name="index-gdb_002esolib_005fname-1770"></a> 282 283<div class="defun"> 284— Function: <b>gdb.solib_name</b> (<var>address</var>)<var><a name="index-gdb_002esolib_005fname-1771"></a></var><br> 285<blockquote><p>Return the name of the shared library holding the given <var>address</var> 286as a string, or <code>None</code>. 287</p></blockquote></div> 288 289 <p><a name="index-gdb_002edecode_005fline-1772"></a> 290 291<div class="defun"> 292— Function: <b>gdb.decode_line</b> <span class="roman">[</span><var>expression</var><span class="roman">]</span><var><a name="index-gdb_002edecode_005fline-1773"></a></var><br> 293<blockquote><p>Return locations of the line specified by <var>expression</var>, or of the 294current line if no argument was given. This function returns a Python 295tuple containing two elements. The first element contains a string 296holding any unparsed section of <var>expression</var> (or <code>None</code> if 297the expression has been fully parsed). The second element contains 298either <code>None</code> or another tuple that contains all the locations 299that match the expression represented as <code>gdb.Symtab_and_line</code> 300objects (see <a href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python">Symbol Tables In Python</a>). If <var>expression</var> is 301provided, it is decoded the way that <span class="sc">gdb</span>'s inbuilt 302<code>break</code> or <code>edit</code> commands do (see <a href="Specify-Location.html#Specify-Location">Specify Location</a>). 303</p></blockquote></div> 304 305<div class="defun"> 306— Function: <b>gdb.prompt_hook</b> (<var>current_prompt</var>)<var><a name="index-gdb_002eprompt_005fhook-1774"></a></var><br> 307<blockquote><p><a name="prompt_005fhook"></a>If <var>prompt_hook</var> is callable, <span class="sc">gdb</span> will call the method 308assigned to this operation before a prompt is displayed by 309<span class="sc">gdb</span>. 310 311 <p>The parameter <code>current_prompt</code> contains the current <span class="sc">gdb</span> 312prompt. This method must return a Python string, or <code>None</code>. If 313a string is returned, the <span class="sc">gdb</span> prompt will be set to that 314string. If <code>None</code> is returned, <span class="sc">gdb</span> will continue to use 315the current prompt. 316 317 <p>Some prompts cannot be substituted in <span class="sc">gdb</span>. Secondary prompts 318such as those used by readline for command input, and annotation 319related prompts are prohibited from being changed. 320</p></blockquote></div> 321 322 </body></html> 323 324