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: Commands In Python</title> 18 19<meta name="description" content="Debugging with GDB: Commands In Python"> 20<meta name="keywords" content="Debugging with GDB: Commands 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="Parameters-In-Python.html#Parameters-In-Python" rel="next" title="Parameters In Python"> 30<link href="Recordings-In-Python.html#Recordings-In-Python" rel="previous" title="Recordings 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="Commands-In-Python"></a> 65<div class="header"> 66<p> 67Next: <a href="Parameters-In-Python.html#Parameters-In-Python" accesskey="n" rel="next">Parameters In Python</a>, Previous: <a href="Recordings-In-Python.html#Recordings-In-Python" accesskey="p" rel="previous">Recordings 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="Commands-In-Python-1"></a> 71<h4 class="subsubsection">23.2.2.20 Commands In Python</h4> 72 73<a name="index-commands-in-python"></a> 74<a name="index-python-commands-1"></a> 75<p>You can implement new <small>GDB</small> CLI commands in Python. A CLI 76command is implemented using an instance of the <code>gdb.Command</code> 77class, most commonly using a subclass. 78</p> 79<dl> 80<dt><a name="index-Command_002e_005f_005finit_005f_005f"></a>Function: <strong>Command.__init__</strong> <em>(name, <var>command_class</var> <span class="roman">[</span>, <var>completer_class</var> <span class="roman">[</span>, <var>prefix</var><span class="roman">]]</span>)</em></dt> 81<dd><p>The object initializer for <code>Command</code> registers the new command 82with <small>GDB</small>. This initializer is normally invoked from the 83subclass’ own <code>__init__</code> method. 84</p> 85<p><var>name</var> is the name of the command. If <var>name</var> consists of 86multiple words, then the initial words are looked for as prefix 87commands. In this case, if one of the prefix commands does not exist, 88an exception is raised. 89</p> 90<p>There is no support for multi-line commands. 91</p> 92<p><var>command_class</var> should be one of the ‘<samp>COMMAND_</samp>’ constants 93defined below. This argument tells <small>GDB</small> how to categorize the 94new command in the help system. 95</p> 96<p><var>completer_class</var> is an optional argument. If given, it should be 97one of the ‘<samp>COMPLETE_</samp>’ constants defined below. This argument 98tells <small>GDB</small> how to perform completion for this command. If not 99given, <small>GDB</small> will attempt to complete using the object’s 100<code>complete</code> method (see below); if no such method is found, an 101error will occur when completion is attempted. 102</p> 103<p><var>prefix</var> is an optional argument. If <code>True</code>, then the new 104command is a prefix command; sub-commands of this command may be 105registered. 106</p> 107<p>The help text for the new command is taken from the Python 108documentation string for the command’s class, if there is one. If no 109documentation string is provided, the default value “This command is 110not documented.” is used. 111</p></dd></dl> 112 113<a name="index-don_0027t-repeat-Python-command"></a> 114<dl> 115<dt><a name="index-Command_002edont_005frepeat"></a>Function: <strong>Command.dont_repeat</strong> <em>()</em></dt> 116<dd><p>By default, a <small>GDB</small> command is repeated when the user enters a 117blank line at the command prompt. A command can suppress this 118behavior by invoking the <code>dont_repeat</code> method. This is similar 119to the user command <code>dont-repeat</code>, see <a href="Define.html#Define">dont-repeat</a>. 120</p></dd></dl> 121 122<dl> 123<dt><a name="index-Command_002einvoke"></a>Function: <strong>Command.invoke</strong> <em>(argument, from_tty)</em></dt> 124<dd><p>This method is called by <small>GDB</small> when this command is invoked. 125</p> 126<p><var>argument</var> is a string. It is the argument to the command, after 127leading and trailing whitespace has been stripped. 128</p> 129<p><var>from_tty</var> is a boolean argument. When true, this means that the 130command was entered by the user at the terminal; when false it means 131that the command came from elsewhere. 132</p> 133<p>If this method throws an exception, it is turned into a <small>GDB</small> 134<code>error</code> call. Otherwise, the return value is ignored. 135</p> 136<a name="index-gdb_002estring_005fto_005fargv"></a> 137<p>To break <var>argument</var> up into an argv-like string use 138<code>gdb.string_to_argv</code>. This function behaves identically to 139<small>GDB</small>’s internal argument lexer <code>buildargv</code>. 140It is recommended to use this for consistency. 141Arguments are separated by spaces and may be quoted. 142Example: 143</p> 144<div class="smallexample"> 145<pre class="smallexample">print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") 146['1', '2 "3', '4 "5', "6 '7"] 147</pre></div> 148 149</dd></dl> 150 151<a name="index-completion-of-Python-commands"></a> 152<dl> 153<dt><a name="index-Command_002ecomplete"></a>Function: <strong>Command.complete</strong> <em>(text, word)</em></dt> 154<dd><p>This method is called by <small>GDB</small> when the user attempts 155completion on this command. All forms of completion are handled by 156this method, that is, the <tt class="key">TAB</tt> and <tt class="key">M-?</tt> key bindings 157(see <a href="Completion.html#Completion">Completion</a>), and the <code>complete</code> command (see <a href="Help.html#Help">complete</a>). 158</p> 159<p>The arguments <var>text</var> and <var>word</var> are both strings; <var>text</var> 160holds the complete command line up to the cursor’s location, while 161<var>word</var> holds the last word of the command line; this is computed 162using a word-breaking heuristic. 163</p> 164<p>The <code>complete</code> method can return several values: 165</p><ul> 166<li> If the return value is a sequence, the contents of the sequence are 167used as the completions. It is up to <code>complete</code> to ensure that the 168contents actually do complete the word. A zero-length sequence is 169allowed, it means that there were no completions available. Only 170string elements of the sequence are used; other elements in the 171sequence are ignored. 172 173</li><li> If the return value is one of the ‘<samp>COMPLETE_</samp>’ constants defined 174below, then the corresponding <small>GDB</small>-internal completion 175function is invoked, and its result is used. 176 177</li><li> All other results are treated as though there were no available 178completions. 179</li></ul> 180</dd></dl> 181 182<p>When a new command is registered, it must be declared as a member of 183some general class of commands. This is used to classify top-level 184commands in the on-line help system; note that prefix commands are not 185listed under their own category but rather that of their top-level 186command. The available classifications are represented by constants 187defined in the <code>gdb</code> module: 188</p> 189<dl compact="compact"> 190<dd><a name="index-COMMAND_005fNONE"></a> 191<a name="index-gdb_002eCOMMAND_005fNONE"></a> 192</dd> 193<dt><code>gdb.COMMAND_NONE</code></dt> 194<dd><p>The command does not belong to any particular class. A command in 195this category will not be displayed in any of the help categories. 196</p> 197<a name="index-COMMAND_005fRUNNING"></a> 198<a name="index-gdb_002eCOMMAND_005fRUNNING"></a> 199</dd> 200<dt><code>gdb.COMMAND_RUNNING</code></dt> 201<dd><p>The command is related to running the inferior. For example, 202<code>start</code>, <code>step</code>, and <code>continue</code> are in this category. 203Type <kbd>help running</kbd> at the <small>GDB</small> prompt to see a list of 204commands in this category. 205</p> 206<a name="index-COMMAND_005fDATA"></a> 207<a name="index-gdb_002eCOMMAND_005fDATA"></a> 208</dd> 209<dt><code>gdb.COMMAND_DATA</code></dt> 210<dd><p>The command is related to data or variables. For example, 211<code>call</code>, <code>find</code>, and <code>print</code> are in this category. Type 212<kbd>help data</kbd> at the <small>GDB</small> prompt to see a list of commands 213in this category. 214</p> 215<a name="index-COMMAND_005fSTACK"></a> 216<a name="index-gdb_002eCOMMAND_005fSTACK"></a> 217</dd> 218<dt><code>gdb.COMMAND_STACK</code></dt> 219<dd><p>The command has to do with manipulation of the stack. For example, 220<code>backtrace</code>, <code>frame</code>, and <code>return</code> are in this 221category. Type <kbd>help stack</kbd> at the <small>GDB</small> prompt to see a 222list of commands in this category. 223</p> 224<a name="index-COMMAND_005fFILES"></a> 225<a name="index-gdb_002eCOMMAND_005fFILES"></a> 226</dd> 227<dt><code>gdb.COMMAND_FILES</code></dt> 228<dd><p>This class is used for file-related commands. For example, 229<code>file</code>, <code>list</code> and <code>section</code> are in this category. 230Type <kbd>help files</kbd> at the <small>GDB</small> prompt to see a list of 231commands in this category. 232</p> 233<a name="index-COMMAND_005fSUPPORT"></a> 234<a name="index-gdb_002eCOMMAND_005fSUPPORT"></a> 235</dd> 236<dt><code>gdb.COMMAND_SUPPORT</code></dt> 237<dd><p>This should be used for “support facilities”, generally meaning 238things that are useful to the user when interacting with <small>GDB</small>, 239but not related to the state of the inferior. For example, 240<code>help</code>, <code>make</code>, and <code>shell</code> are in this category. Type 241<kbd>help support</kbd> at the <small>GDB</small> prompt to see a list of 242commands in this category. 243</p> 244<a name="index-COMMAND_005fSTATUS"></a> 245<a name="index-gdb_002eCOMMAND_005fSTATUS"></a> 246</dd> 247<dt><code>gdb.COMMAND_STATUS</code></dt> 248<dd><p>The command is an ‘<samp>info</samp>’-related command, that is, related to the 249state of <small>GDB</small> itself. For example, <code>info</code>, <code>macro</code>, 250and <code>show</code> are in this category. Type <kbd>help status</kbd> at the 251<small>GDB</small> prompt to see a list of commands in this category. 252</p> 253<a name="index-COMMAND_005fBREAKPOINTS"></a> 254<a name="index-gdb_002eCOMMAND_005fBREAKPOINTS"></a> 255</dd> 256<dt><code>gdb.COMMAND_BREAKPOINTS</code></dt> 257<dd><p>The command has to do with breakpoints. For example, <code>break</code>, 258<code>clear</code>, and <code>delete</code> are in this category. Type <kbd>help 259breakpoints</kbd> at the <small>GDB</small> prompt to see a list of commands in 260this category. 261</p> 262<a name="index-COMMAND_005fTRACEPOINTS"></a> 263<a name="index-gdb_002eCOMMAND_005fTRACEPOINTS"></a> 264</dd> 265<dt><code>gdb.COMMAND_TRACEPOINTS</code></dt> 266<dd><p>The command has to do with tracepoints. For example, <code>trace</code>, 267<code>actions</code>, and <code>tfind</code> are in this category. Type 268<kbd>help tracepoints</kbd> at the <small>GDB</small> prompt to see a list of 269commands in this category. 270</p> 271<a name="index-COMMAND_005fTUI"></a> 272<a name="index-gdb_002eCOMMAND_005fTUI"></a> 273</dd> 274<dt><code>gdb.COMMAND_TUI</code></dt> 275<dd><p>The command has to do with the text user interface (see <a href="TUI.html#TUI">TUI</a>). 276Type <kbd>help tui</kbd> at the <small>GDB</small> prompt to see a list of 277commands in this category. 278</p> 279<a name="index-COMMAND_005fUSER"></a> 280<a name="index-gdb_002eCOMMAND_005fUSER"></a> 281</dd> 282<dt><code>gdb.COMMAND_USER</code></dt> 283<dd><p>The command is a general purpose command for the user, and typically 284does not fit in one of the other categories. 285Type <kbd>help user-defined</kbd> at the <small>GDB</small> prompt to see 286a list of commands in this category, as well as the list of gdb macros 287(see <a href="Sequences.html#Sequences">Sequences</a>). 288</p> 289<a name="index-COMMAND_005fOBSCURE"></a> 290<a name="index-gdb_002eCOMMAND_005fOBSCURE"></a> 291</dd> 292<dt><code>gdb.COMMAND_OBSCURE</code></dt> 293<dd><p>The command is only used in unusual circumstances, or is not of 294general interest to users. For example, <code>checkpoint</code>, 295<code>fork</code>, and <code>stop</code> are in this category. Type <kbd>help 296obscure</kbd> at the <small>GDB</small> prompt to see a list of commands in this 297category. 298</p> 299<a name="index-COMMAND_005fMAINTENANCE"></a> 300<a name="index-gdb_002eCOMMAND_005fMAINTENANCE"></a> 301</dd> 302<dt><code>gdb.COMMAND_MAINTENANCE</code></dt> 303<dd><p>The command is only useful to <small>GDB</small> maintainers. The 304<code>maintenance</code> and <code>flushregs</code> commands are in this category. 305Type <kbd>help internals</kbd> at the <small>GDB</small> prompt to see a list of 306commands in this category. 307</p></dd> 308</dl> 309 310<p>A new command can use a predefined completion function, either by 311specifying it via an argument at initialization, or by returning it 312from the <code>complete</code> method. These predefined completion 313constants are all defined in the <code>gdb</code> module: 314</p> 315<dl compact="compact"> 316<dd><a name="index-COMPLETE_005fNONE"></a> 317</dd> 318<dt><code>gdb.COMPLETE_NONE</code> 319<a name="index-gdb_002eCOMPLETE_005fNONE"></a> 320</dt> 321<dd><p>This constant means that no completion should be done. 322</p> 323<a name="index-COMPLETE_005fFILENAME"></a> 324</dd> 325<dt><code>gdb.COMPLETE_FILENAME</code> 326<a name="index-gdb_002eCOMPLETE_005fFILENAME"></a> 327</dt> 328<dd><p>This constant means that filename completion should be performed. 329</p> 330<a name="index-COMPLETE_005fLOCATION"></a> 331</dd> 332<dt><code>gdb.COMPLETE_LOCATION</code> 333<a name="index-gdb_002eCOMPLETE_005fLOCATION"></a> 334</dt> 335<dd><p>This constant means that location completion should be done. 336See <a href="Specify-Location.html#Specify-Location">Specify Location</a>. 337</p> 338<a name="index-COMPLETE_005fCOMMAND"></a> 339</dd> 340<dt><code>gdb.COMPLETE_COMMAND</code> 341<a name="index-gdb_002eCOMPLETE_005fCOMMAND"></a> 342</dt> 343<dd><p>This constant means that completion should examine <small>GDB</small> 344command names. 345</p> 346<a name="index-COMPLETE_005fSYMBOL"></a> 347</dd> 348<dt><code>gdb.COMPLETE_SYMBOL</code> 349<a name="index-gdb_002eCOMPLETE_005fSYMBOL"></a> 350</dt> 351<dd><p>This constant means that completion should be done using symbol names 352as the source. 353</p> 354<a name="index-COMPLETE_005fEXPRESSION"></a> 355</dd> 356<dt><code>gdb.COMPLETE_EXPRESSION</code> 357<a name="index-gdb_002eCOMPLETE_005fEXPRESSION"></a> 358</dt> 359<dd><p>This constant means that completion should be done on expressions. 360Often this means completing on symbol names, but some language 361parsers also have support for completing on field names. 362</p></dd> 363</dl> 364 365<p>The following code snippet shows how a trivial CLI command can be 366implemented in Python: 367</p> 368<div class="smallexample"> 369<pre class="smallexample">class HelloWorld (gdb.Command): 370 """Greet the whole world.""" 371 372 def __init__ (self): 373 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) 374 375 def invoke (self, arg, from_tty): 376 print "Hello, World!" 377 378HelloWorld () 379</pre></div> 380 381<p>The last line instantiates the class, and is necessary to trigger the 382registration of the command with <small>GDB</small>. Depending on how the 383Python code is read into <small>GDB</small>, you may need to import the 384<code>gdb</code> module explicitly. 385</p> 386<hr> 387<div class="header"> 388<p> 389Next: <a href="Parameters-In-Python.html#Parameters-In-Python" accesskey="n" rel="next">Parameters In Python</a>, Previous: <a href="Recordings-In-Python.html#Recordings-In-Python" accesskey="p" rel="previous">Recordings 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> 390</div> 391 392 393 394</body> 395</html> 396