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, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 131998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 14Free Software Foundation, Inc. 15 16Permission is granted to copy, distribute and/or modify this document 17under the terms of the GNU Free Documentation License, Version 1.3 or 18any later version published by the Free Software Foundation; with the 19Invariant Sections being ``Free Software'' and ``Free Software Needs 20Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 21and with the Back-Cover Texts as in (a) below. 22 23(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 24this GNU Manual. Buying copies from GNU Press supports the FSF in 25developing GNU and promoting software freedom.''--> 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="Basic-Python"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Exception-Handling.html#Exception-Handling">Exception Handling</a>, 45Up: <a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a> 46<hr> 47</div> 48 49<h5 class="subsubsection">23.2.2.1 Basic Python</h5> 50 51<p><a name="index-python-functions-1577"></a><a name="index-python-module-1578"></a><a name="index-gdb-module-1579"></a><span class="sc">gdb</span> introduces a new Python module, named <code>gdb</code>. All 52methods and classes added by <span class="sc">gdb</span> are placed in this module. 53<span class="sc">gdb</span> automatically <code>import</code>s the <code>gdb</code> module for 54use in all scripts evaluated by the <code>python</code> command. 55 56 <p><a name="index-gdb_002ePYTHONDIR-1580"></a> 57 58<div class="defun"> 59— Variable: <b>PYTHONDIR</b><var><a name="index-PYTHONDIR-1581"></a></var><br> 60<blockquote><p>A string containing the python directory (see <a href="Python.html#Python">Python</a>). 61</p></blockquote></div> 62 63 <p><a name="index-gdb_002eexecute-1582"></a> 64 65<div class="defun"> 66— Function: <b>execute</b><var> command </var>[<var>from_tty</var>] [<var>to_string</var>]<var><a name="index-execute-1583"></a></var><br> 67<blockquote><p>Evaluate <var>command</var>, a string, as a <span class="sc">gdb</span> CLI command. 68If a GDB exception happens while <var>command</var> runs, it is 69translated as described in <a href="Exception-Handling.html#Exception-Handling">Exception Handling</a>. 70 71 <p><var>from_tty</var> specifies whether <span class="sc">gdb</span> ought to consider this 72command as having originated from the user invoking it interactively. 73It must be a boolean value. If omitted, it defaults to <code>False</code>. 74 75 <p>By default, any output produced by <var>command</var> is sent to 76<span class="sc">gdb</span>'s standard output. If the <var>to_string</var> parameter is 77<code>True</code>, then output will be collected by <code>gdb.execute</code> and 78returned as a string. The default is <code>False</code>, in which case the 79return value is <code>None</code>. If <var>to_string</var> is <code>True</code>, the 80<span class="sc">gdb</span> virtual terminal will be temporarily set to unlimited width 81and height, and its pagination will be disabled; see <a href="Screen-Size.html#Screen-Size">Screen Size</a>. 82</p></blockquote></div> 83 84 <p><a name="index-gdb_002ebreakpoints-1584"></a> 85 86<div class="defun"> 87— Function: <b>breakpoints</b><var><a name="index-breakpoints-1585"></a></var><br> 88<blockquote><p>Return a sequence holding all of <span class="sc">gdb</span>'s breakpoints. 89See <a href="Breakpoints-In-Python.html#Breakpoints-In-Python">Breakpoints In Python</a>, for more information. 90</p></blockquote></div> 91 92 <p><a name="index-gdb_002eparameter-1586"></a> 93 94<div class="defun"> 95— Function: <b>parameter</b><var> parameter<a name="index-parameter-1587"></a></var><br> 96<blockquote><p>Return the value of a <span class="sc">gdb</span> parameter. <var>parameter</var> is a 97string naming the parameter to look up; <var>parameter</var> may contain 98spaces if the parameter has a multi-part name. For example, 99‘<samp><span class="samp">print object</span></samp>’ is a valid parameter name. 100 101 <p>If the named parameter does not exist, this function throws a 102<code>RuntimeError</code>. Otherwise, the parameter's value is converted to 103a Python value of the appropriate type, and returned. 104</p></blockquote></div> 105 106 <p><a name="index-gdb_002ehistory-1588"></a> 107 108<div class="defun"> 109— Function: <b>history</b><var> number<a name="index-history-1589"></a></var><br> 110<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. 111If <var>number</var> is negative, then <span class="sc">gdb</span> will take its absolute value 112and count backward from the last element (i.e., the most recent element) to 113find the value to return. If <var>number</var> is zero, then <span class="sc">gdb</span> will 114return the most recent element. If the element specified by <var>number</var> 115doesn't exist in the value history, a <code>RuntimeError</code> exception will be 116raised. 117 118 <p>If no exception is raised, the return value is always an instance of 119<code>gdb.Value</code> (see <a href="Values-From-Inferior.html#Values-From-Inferior">Values From Inferior</a>). 120</p></blockquote></div> 121 122 <p><a name="index-gdb_002eparse_005fand_005feval-1590"></a> 123 124<div class="defun"> 125— Function: <b>parse_and_eval</b><var> expression<a name="index-parse_005fand_005feval-1591"></a></var><br> 126<blockquote><p>Parse <var>expression</var> as an expression in the current language, 127evaluate it, and return the result as a <code>gdb.Value</code>. 128<var>expression</var> must be a string. 129 130 <p>This function can be useful when implementing a new command 131(see <a href="Commands-In-Python.html#Commands-In-Python">Commands In Python</a>), as it provides a way to parse the 132command's argument as an expression. It is also useful simply to 133compute values, for example, it is the only way to get the value of a 134convenience variable (see <a href="Convenience-Vars.html#Convenience-Vars">Convenience Vars</a>) as a <code>gdb.Value</code>. 135</p></blockquote></div> 136 137 <p><a name="index-gdb_002epost_005fevent-1592"></a> 138 139<div class="defun"> 140— Function: <b>post_event</b><var> event<a name="index-post_005fevent-1593"></a></var><br> 141<blockquote><p>Put <var>event</var>, a callable object taking no arguments, into 142<span class="sc">gdb</span>'s internal event queue. This callable will be invoked at 143some later point, during <span class="sc">gdb</span>'s event processing. Events 144posted using <code>post_event</code> will be run in the order in which they 145were posted; however, there is no way to know when they will be 146processed relative to other events inside <span class="sc">gdb</span>. 147 148 <p><span class="sc">gdb</span> is not thread-safe. If your Python program uses multiple 149threads, you must be careful to only call <span class="sc">gdb</span>-specific 150functions in the main <span class="sc">gdb</span> thread. <code>post_event</code> ensures 151this. For example: 152 153 <pre class="smallexample"> (gdb) python 154 >import threading 155 > 156 >class Writer(): 157 > def __init__(self, message): 158 > self.message = message; 159 > def __call__(self): 160 > gdb.write(self.message) 161 > 162 >class MyThread1 (threading.Thread): 163 > def run (self): 164 > gdb.post_event(Writer("Hello ")) 165 > 166 >class MyThread2 (threading.Thread): 167 > def run (self): 168 > gdb.post_event(Writer("World\n")) 169 > 170 >MyThread1().start() 171 >MyThread2().start() 172 >end 173 (gdb) Hello World 174</pre> 175 </blockquote></div> 176 177 <p><a name="index-gdb_002ewrite-1594"></a> 178 179<div class="defun"> 180— Function: <b>write</b><var> string<a name="index-write-1595"></a></var><br> 181<blockquote><p>Print a string to <span class="sc">gdb</span>'s paginated standard output stream. 182Writing to <code>sys.stdout</code> or <code>sys.stderr</code> will automatically 183call this function. 184</p></blockquote></div> 185 186 <p><a name="index-gdb_002eflush-1596"></a> 187 188<div class="defun"> 189— Function: <b>flush</b><var><a name="index-flush-1597"></a></var><br> 190<blockquote><p>Flush <span class="sc">gdb</span>'s paginated standard output stream. Flushing 191<code>sys.stdout</code> or <code>sys.stderr</code> will automatically call this 192function. 193</p></blockquote></div> 194 195 <p><a name="index-gdb_002etarget_005fcharset-1598"></a> 196 197<div class="defun"> 198— Function: <b>target_charset</b><var><a name="index-target_005fcharset-1599"></a></var><br> 199<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 200that ‘<samp><span class="samp">auto</span></samp>’ is never returned. 201</p></blockquote></div> 202 203 <p><a name="index-gdb_002etarget_005fwide_005fcharset-1600"></a> 204 205<div class="defun"> 206— Function: <b>target_wide_charset</b><var><a name="index-target_005fwide_005fcharset-1601"></a></var><br> 207<blockquote><p>Return the name of the current target wide character set 208(see <a href="Character-Sets.html#Character-Sets">Character Sets</a>). This differs from 209<code>gdb.parameter('target-wide-charset')</code> in that ‘<samp><span class="samp">auto</span></samp>’ is 210never returned. 211</p></blockquote></div> 212 213 <p><a name="index-gdb_002esolib_005fname-1602"></a> 214 215<div class="defun"> 216— Function: <b>solib_name</b><var> address<a name="index-solib_005fname-1603"></a></var><br> 217<blockquote><p>Return the name of the shared library holding the given <var>address</var> 218as a string, or <code>None</code>. 219</p></blockquote></div> 220 221 <p><a name="index-gdb_002edecode_005fline-1604"></a> 222 223<div class="defun"> 224— Function: <b>decode_line</b> <span class="roman">[</span><var>expression</var><span class="roman">]</span><var><a name="index-decode_005fline-1605"></a></var><br> 225<blockquote><p>Return locations of the line specified by <var>expression</var>, or of the 226current line if no argument was given. This function returns a Python 227tuple containing two elements. The first element contains a string 228holding any unparsed section of <var>expression</var> (or <code>None</code> if 229the expression has been fully parsed). The second element contains 230either <code>None</code> or another tuple that contains all the locations 231that match the expression represented as <code>gdb.Symtab_and_line</code> 232objects (see <a href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python">Symbol Tables In Python</a>). If <var>expression</var> is 233provided, it is decoded the way that <span class="sc">gdb</span>'s inbuilt 234<code>break</code> or <code>edit</code> commands do (see <a href="Specify-Location.html#Specify-Location">Specify Location</a>). 235</p></blockquote></div> 236 237 </body></html> 238 239