1<html lang="en"> 2<head> 3<title>Commands 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="Threads-In-Python.html#Threads-In-Python" title="Threads In Python"> 10<link rel="next" href="Parameters-In-Python.html#Parameters-In-Python" title="Parameters In Python"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 141998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 15Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation; with the 20Invariant Sections being ``Free Software'' and ``Free Software Needs 21Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 22and with the Back-Cover Texts as in (a) below. 23 24(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 25this GNU Manual. Buying copies from GNU Press supports the FSF in 26developing GNU and promoting software freedom.''--> 27<meta http-equiv="Content-Style-Type" content="text/css"> 28<style type="text/css"><!-- 29 pre.display { font-family:inherit } 30 pre.format { font-family:inherit } 31 pre.smalldisplay { font-family:inherit; font-size:smaller } 32 pre.smallformat { font-family:inherit; font-size:smaller } 33 pre.smallexample { font-size:smaller } 34 pre.smalllisp { font-size:smaller } 35 span.sc { font-variant:small-caps } 36 span.roman { font-family:serif; font-weight:normal; } 37 span.sansserif { font-family:sans-serif; font-weight:normal; } 38--></style> 39<link rel="stylesheet" type="text/css" href="../cs.css"> 40</head> 41<body> 42<div class="node"> 43<a name="Commands-In-Python"></a> 44<p> 45Next: <a rel="next" accesskey="n" href="Parameters-In-Python.html#Parameters-In-Python">Parameters In Python</a>, 46Previous: <a rel="previous" accesskey="p" href="Threads-In-Python.html#Threads-In-Python">Threads In Python</a>, 47Up: <a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a> 48<hr> 49</div> 50 51<h5 class="subsubsection">23.2.2.10 Commands In Python</h5> 52 53<p><a name="index-commands-in-python-1723"></a><a name="index-python-commands-1724"></a>You can implement new <span class="sc">gdb</span> CLI commands in Python. A CLI 54command is implemented using an instance of the <code>gdb.Command</code> 55class, most commonly using a subclass. 56 57<div class="defun"> 58— Method on Command: <b>__init__</b><var> name command_class </var><span class="roman">[</span><var>completer_class</var><span class="roman">]</span> <span class="roman">[</span><var>prefix</var><span class="roman">]</span><var><a name="index-g_t_005f_005finit_005f_005f-on-Command-1725"></a></var><br> 59<blockquote><p>The object initializer for <code>Command</code> registers the new command 60with <span class="sc">gdb</span>. This initializer is normally invoked from the 61subclass' own <code>__init__</code> method. 62 63 <p><var>name</var> is the name of the command. If <var>name</var> consists of 64multiple words, then the initial words are looked for as prefix 65commands. In this case, if one of the prefix commands does not exist, 66an exception is raised. 67 68 <p>There is no support for multi-line commands. 69 70 <p><var>command_class</var> should be one of the ‘<samp><span class="samp">COMMAND_</span></samp>’ constants 71defined below. This argument tells <span class="sc">gdb</span> how to categorize the 72new command in the help system. 73 74 <p><var>completer_class</var> is an optional argument. If given, it should be 75one of the ‘<samp><span class="samp">COMPLETE_</span></samp>’ constants defined below. This argument 76tells <span class="sc">gdb</span> how to perform completion for this command. If not 77given, <span class="sc">gdb</span> will attempt to complete using the object's 78<code>complete</code> method (see below); if no such method is found, an 79error will occur when completion is attempted. 80 81 <p><var>prefix</var> is an optional argument. If <code>True</code>, then the new 82command is a prefix command; sub-commands of this command may be 83registered. 84 85 <p>The help text for the new command is taken from the Python 86documentation string for the command's class, if there is one. If no 87documentation string is provided, the default value “This command is 88not documented.” is used. 89</p></blockquote></div> 90 91 <p><a name="index-don_0027t-repeat-Python-command-1726"></a> 92 93<div class="defun"> 94— Method on Command: <b>dont_repeat</b><var><a name="index-dont_005frepeat-on-Command-1727"></a></var><br> 95<blockquote><p>By default, a <span class="sc">gdb</span> command is repeated when the user enters a 96blank line at the command prompt. A command can suppress this 97behavior by invoking the <code>dont_repeat</code> method. This is similar 98to the user command <code>dont-repeat</code>, see <a href="Define.html#Define">dont-repeat</a>. 99</p></blockquote></div> 100 101<div class="defun"> 102— Method on Command: <b>invoke</b><var> argument from_tty<a name="index-invoke-on-Command-1728"></a></var><br> 103<blockquote><p>This method is called by <span class="sc">gdb</span> when this command is invoked. 104 105 <p><var>argument</var> is a string. It is the argument to the command, after 106leading and trailing whitespace has been stripped. 107 108 <p><var>from_tty</var> is a boolean argument. When true, this means that the 109command was entered by the user at the terminal; when false it means 110that the command came from elsewhere. 111 112 <p>If this method throws an exception, it is turned into a <span class="sc">gdb</span> 113<code>error</code> call. Otherwise, the return value is ignored. 114 115 <p><a name="index-gdb_002estring_005fto_005fargv-1729"></a>To break <var>argument</var> up into an argv-like string use 116<code>gdb.string_to_argv</code>. This function behaves identically to 117<span class="sc">gdb</span>'s internal argument lexer <code>buildargv</code>. 118It is recommended to use this for consistency. 119Arguments are separated by spaces and may be quoted. 120Example: 121 122 <pre class="smallexample"> print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") 123 ['1', '2 "3', '4 "5', "6 '7"] 124</pre> 125 </blockquote></div> 126 127 <p><a name="index-completion-of-Python-commands-1730"></a> 128 129<div class="defun"> 130— Method on Command: <b>complete</b><var> text word<a name="index-complete-on-Command-1731"></a></var><br> 131<blockquote><p>This method is called by <span class="sc">gdb</span> when the user attempts 132completion on this command. All forms of completion are handled by 133this method, that is, the <TAB> and <M-?> key bindings 134(see <a href="Completion.html#Completion">Completion</a>), and the <code>complete</code> command (see <a href="Help.html#Help">complete</a>). 135 136 <p>The arguments <var>text</var> and <var>word</var> are both strings. <var>text</var> 137holds the complete command line up to the cursor's location. 138<var>word</var> holds the last word of the command line; this is computed 139using a word-breaking heuristic. 140 141 <p>The <code>complete</code> method can return several values: 142 <ul> 143<li>If the return value is a sequence, the contents of the sequence are 144used as the completions. It is up to <code>complete</code> to ensure that the 145contents actually do complete the word. A zero-length sequence is 146allowed, it means that there were no completions available. Only 147string elements of the sequence are used; other elements in the 148sequence are ignored. 149 150 <li>If the return value is one of the ‘<samp><span class="samp">COMPLETE_</span></samp>’ constants defined 151below, then the corresponding <span class="sc">gdb</span>-internal completion 152function is invoked, and its result is used. 153 154 <li>All other results are treated as though there were no available 155completions. 156</ul> 157 </p></blockquote></div> 158 159 <p>When a new command is registered, it must be declared as a member of 160some general class of commands. This is used to classify top-level 161commands in the on-line help system; note that prefix commands are not 162listed under their own category but rather that of their top-level 163command. The available classifications are represented by constants 164defined in the <code>gdb</code> module: 165 166 167<a name="index-COMMAND_005fNONE-1732"></a> 168<a name="index-gdb_002eCOMMAND_005fNONE-1733"></a> 169<dl><dt><code>COMMAND_NONE</code><dd>The command does not belong to any particular class. A command in 170this category will not be displayed in any of the help categories. 171 172 <p><a name="index-COMMAND_005fRUNNING-1734"></a><a name="index-gdb_002eCOMMAND_005fRUNNING-1735"></a><br><dt><code>COMMAND_RUNNING</code><dd>The command is related to running the inferior. For example, 173<code>start</code>, <code>step</code>, and <code>continue</code> are in this category. 174Type <kbd>help running</kbd> at the <span class="sc">gdb</span> prompt to see a list of 175commands in this category. 176 177 <p><a name="index-COMMAND_005fDATA-1736"></a><a name="index-gdb_002eCOMMAND_005fDATA-1737"></a><br><dt><code>COMMAND_DATA</code><dd>The command is related to data or variables. For example, 178<code>call</code>, <code>find</code>, and <code>print</code> are in this category. Type 179<kbd>help data</kbd> at the <span class="sc">gdb</span> prompt to see a list of commands 180in this category. 181 182 <p><a name="index-COMMAND_005fSTACK-1738"></a><a name="index-gdb_002eCOMMAND_005fSTACK-1739"></a><br><dt><code>COMMAND_STACK</code><dd>The command has to do with manipulation of the stack. For example, 183<code>backtrace</code>, <code>frame</code>, and <code>return</code> are in this 184category. Type <kbd>help stack</kbd> at the <span class="sc">gdb</span> prompt to see a 185list of commands in this category. 186 187 <p><a name="index-COMMAND_005fFILES-1740"></a><a name="index-gdb_002eCOMMAND_005fFILES-1741"></a><br><dt><code>COMMAND_FILES</code><dd>This class is used for file-related commands. For example, 188<code>file</code>, <code>list</code> and <code>section</code> are in this category. 189Type <kbd>help files</kbd> at the <span class="sc">gdb</span> prompt to see a list of 190commands in this category. 191 192 <p><a name="index-COMMAND_005fSUPPORT-1742"></a><a name="index-gdb_002eCOMMAND_005fSUPPORT-1743"></a><br><dt><code>COMMAND_SUPPORT</code><dd>This should be used for “support facilities”, generally meaning 193things that are useful to the user when interacting with <span class="sc">gdb</span>, 194but not related to the state of the inferior. For example, 195<code>help</code>, <code>make</code>, and <code>shell</code> are in this category. Type 196<kbd>help support</kbd> at the <span class="sc">gdb</span> prompt to see a list of 197commands in this category. 198 199 <p><a name="index-COMMAND_005fSTATUS-1744"></a><a name="index-gdb_002eCOMMAND_005fSTATUS-1745"></a><br><dt><code>COMMAND_STATUS</code><dd>The command is an ‘<samp><span class="samp">info</span></samp>’-related command, that is, related to the 200state of <span class="sc">gdb</span> itself. For example, <code>info</code>, <code>macro</code>, 201and <code>show</code> are in this category. Type <kbd>help status</kbd> at the 202<span class="sc">gdb</span> prompt to see a list of commands in this category. 203 204 <p><a name="index-COMMAND_005fBREAKPOINTS-1746"></a><a name="index-gdb_002eCOMMAND_005fBREAKPOINTS-1747"></a><br><dt><code>COMMAND_BREAKPOINTS</code><dd>The command has to do with breakpoints. For example, <code>break</code>, 205<code>clear</code>, and <code>delete</code> are in this category. Type <kbd>help 206breakpoints</kbd> at the <span class="sc">gdb</span> prompt to see a list of commands in 207this category. 208 209 <p><a name="index-COMMAND_005fTRACEPOINTS-1748"></a><a name="index-gdb_002eCOMMAND_005fTRACEPOINTS-1749"></a><br><dt><code>COMMAND_TRACEPOINTS</code><dd>The command has to do with tracepoints. For example, <code>trace</code>, 210<code>actions</code>, and <code>tfind</code> are in this category. Type 211<kbd>help tracepoints</kbd> at the <span class="sc">gdb</span> prompt to see a list of 212commands in this category. 213 214 <p><a name="index-COMMAND_005fOBSCURE-1750"></a><a name="index-gdb_002eCOMMAND_005fOBSCURE-1751"></a><br><dt><code>COMMAND_OBSCURE</code><dd>The command is only used in unusual circumstances, or is not of 215general interest to users. For example, <code>checkpoint</code>, 216<code>fork</code>, and <code>stop</code> are in this category. Type <kbd>help 217obscure</kbd> at the <span class="sc">gdb</span> prompt to see a list of commands in this 218category. 219 220 <p><a name="index-COMMAND_005fMAINTENANCE-1752"></a><a name="index-gdb_002eCOMMAND_005fMAINTENANCE-1753"></a><br><dt><code>COMMAND_MAINTENANCE</code><dd>The command is only useful to <span class="sc">gdb</span> maintainers. The 221<code>maintenance</code> and <code>flushregs</code> commands are in this category. 222Type <kbd>help internals</kbd> at the <span class="sc">gdb</span> prompt to see a list of 223commands in this category. 224</dl> 225 226 <p>A new command can use a predefined completion function, either by 227specifying it via an argument at initialization, or by returning it 228from the <code>complete</code> method. These predefined completion 229constants are all defined in the <code>gdb</code> module: 230 231 232<a name="index-COMPLETE_005fNONE-1754"></a> 233<a name="index-gdb_002eCOMPLETE_005fNONE-1755"></a> 234<dl><dt><code>COMPLETE_NONE</code><dd>This constant means that no completion should be done. 235 236 <p><a name="index-COMPLETE_005fFILENAME-1756"></a><a name="index-gdb_002eCOMPLETE_005fFILENAME-1757"></a><br><dt><code>COMPLETE_FILENAME</code><dd>This constant means that filename completion should be performed. 237 238 <p><a name="index-COMPLETE_005fLOCATION-1758"></a><a name="index-gdb_002eCOMPLETE_005fLOCATION-1759"></a><br><dt><code>COMPLETE_LOCATION</code><dd>This constant means that location completion should be done. 239See <a href="Specify-Location.html#Specify-Location">Specify Location</a>. 240 241 <p><a name="index-COMPLETE_005fCOMMAND-1760"></a><a name="index-gdb_002eCOMPLETE_005fCOMMAND-1761"></a><br><dt><code>COMPLETE_COMMAND</code><dd>This constant means that completion should examine <span class="sc">gdb</span> 242command names. 243 244 <p><a name="index-COMPLETE_005fSYMBOL-1762"></a><a name="index-gdb_002eCOMPLETE_005fSYMBOL-1763"></a><br><dt><code>COMPLETE_SYMBOL</code><dd>This constant means that completion should be done using symbol names 245as the source. 246</dl> 247 248 <p>The following code snippet shows how a trivial CLI command can be 249implemented in Python: 250 251<pre class="smallexample"> class HelloWorld (gdb.Command): 252 """Greet the whole world.""" 253 254 def __init__ (self): 255 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE) 256 257 def invoke (self, arg, from_tty): 258 print "Hello, World!" 259 260 HelloWorld () 261</pre> 262 <p>The last line instantiates the class, and is necessary to trigger the 263registration of the command with <span class="sc">gdb</span>. Depending on how the 264Python code is read into <span class="sc">gdb</span>, you may need to import the 265<code>gdb</code> module explicitly. 266 267 </body></html> 268 269