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-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="Commands-In-Python"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Parameters-In-Python.html#Parameters-In-Python">Parameters In Python</a>, 45Previous: <a rel="previous" accesskey="p" href="Threads-In-Python.html#Threads-In-Python">Threads 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.15 Commands In Python</h5> 51 52<p><a name="index-commands-in-python-1935"></a><a name="index-python-commands-1936"></a>You can implement new <span class="sc">gdb</span> CLI commands in Python. A CLI 53command is implemented using an instance of the <code>gdb.Command</code> 54class, most commonly using a subclass. 55 56<div class="defun"> 57— Function: <b>Command.__init__</b> (<var>name, command_class </var><span class="roman">[</span><var>, completer_class </var><span class="roman">[</span><var>, prefix</var><span class="roman">]]</span>)<var><a name="index-Command_002e_005f_005finit_005f_005f-1937"></a></var><br> 58<blockquote><p>The object initializer for <code>Command</code> registers the new command 59with <span class="sc">gdb</span>. This initializer is normally invoked from the 60subclass' own <code>__init__</code> method. 61 62 <p><var>name</var> is the name of the command. If <var>name</var> consists of 63multiple words, then the initial words are looked for as prefix 64commands. In this case, if one of the prefix commands does not exist, 65an exception is raised. 66 67 <p>There is no support for multi-line commands. 68 69 <p><var>command_class</var> should be one of the ‘<samp><span class="samp">COMMAND_</span></samp>’ constants 70defined below. This argument tells <span class="sc">gdb</span> how to categorize the 71new command in the help system. 72 73 <p><var>completer_class</var> is an optional argument. If given, it should be 74one of the ‘<samp><span class="samp">COMPLETE_</span></samp>’ constants defined below. This argument 75tells <span class="sc">gdb</span> how to perform completion for this command. If not 76given, <span class="sc">gdb</span> will attempt to complete using the object's 77<code>complete</code> method (see below); if no such method is found, an 78error will occur when completion is attempted. 79 80 <p><var>prefix</var> is an optional argument. If <code>True</code>, then the new 81command is a prefix command; sub-commands of this command may be 82registered. 83 84 <p>The help text for the new command is taken from the Python 85documentation string for the command's class, if there is one. If no 86documentation string is provided, the default value “This command is 87not documented.” is used. 88</p></blockquote></div> 89 90 <p><a name="index-don_0027t-repeat-Python-command-1938"></a> 91 92<div class="defun"> 93— Function: <b>Command.dont_repeat</b> ()<var><a name="index-Command_002edont_005frepeat-1939"></a></var><br> 94<blockquote><p>By default, a <span class="sc">gdb</span> command is repeated when the user enters a 95blank line at the command prompt. A command can suppress this 96behavior by invoking the <code>dont_repeat</code> method. This is similar 97to the user command <code>dont-repeat</code>, see <a href="Define.html#Define">dont-repeat</a>. 98</p></blockquote></div> 99 100<div class="defun"> 101— Function: <b>Command.invoke</b> (<var>argument, from_tty</var>)<var><a name="index-Command_002einvoke-1940"></a></var><br> 102<blockquote><p>This method is called by <span class="sc">gdb</span> when this command is invoked. 103 104 <p><var>argument</var> is a string. It is the argument to the command, after 105leading and trailing whitespace has been stripped. 106 107 <p><var>from_tty</var> is a boolean argument. When true, this means that the 108command was entered by the user at the terminal; when false it means 109that the command came from elsewhere. 110 111 <p>If this method throws an exception, it is turned into a <span class="sc">gdb</span> 112<code>error</code> call. Otherwise, the return value is ignored. 113 114 <p><a name="index-gdb_002estring_005fto_005fargv-1941"></a>To break <var>argument</var> up into an argv-like string use 115<code>gdb.string_to_argv</code>. This function behaves identically to 116<span class="sc">gdb</span>'s internal argument lexer <code>buildargv</code>. 117It is recommended to use this for consistency. 118Arguments are separated by spaces and may be quoted. 119Example: 120 121 <pre class="smallexample"> print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") 122 ['1', '2 "3', '4 "5', "6 '7"] 123</pre> 124 </blockquote></div> 125 126 <p><a name="index-completion-of-Python-commands-1942"></a> 127 128<div class="defun"> 129— Function: <b>Command.complete</b> (<var>text, word</var>)<var><a name="index-Command_002ecomplete-1943"></a></var><br> 130<blockquote><p>This method is called by <span class="sc">gdb</span> when the user attempts 131completion on this command. All forms of completion are handled by 132this method, that is, the <TAB> and <M-?> key bindings 133(see <a href="Completion.html#Completion">Completion</a>), and the <code>complete</code> command (see <a href="Help.html#Help">complete</a>). 134 135 <p>The arguments <var>text</var> and <var>word</var> are both strings. <var>text</var> 136holds the complete command line up to the cursor's location. 137<var>word</var> holds the last word of the command line; this is computed 138using a word-breaking heuristic. 139 140 <p>The <code>complete</code> method can return several values: 141 <ul> 142<li>If the return value is a sequence, the contents of the sequence are 143used as the completions. It is up to <code>complete</code> to ensure that the 144contents actually do complete the word. A zero-length sequence is 145allowed, it means that there were no completions available. Only 146string elements of the sequence are used; other elements in the 147sequence are ignored. 148 149 <li>If the return value is one of the ‘<samp><span class="samp">COMPLETE_</span></samp>’ constants defined 150below, then the corresponding <span class="sc">gdb</span>-internal completion 151function is invoked, and its result is used. 152 153 <li>All other results are treated as though there were no available 154completions. 155</ul> 156 </p></blockquote></div> 157 158 <p>When a new command is registered, it must be declared as a member of 159some general class of commands. This is used to classify top-level 160commands in the on-line help system; note that prefix commands are not 161listed under their own category but rather that of their top-level 162command. The available classifications are represented by constants 163defined in the <code>gdb</code> module: 164 165 166<a name="index-COMMAND_005fNONE-1944"></a> 167<a name="index-gdb_002eCOMMAND_005fNONE-1945"></a> 168<dl><dt><code>gdb.COMMAND_NONE</code><dd>The command does not belong to any particular class. A command in 169this category will not be displayed in any of the help categories. 170 171 <p><a name="index-COMMAND_005fRUNNING-1946"></a><a name="index-gdb_002eCOMMAND_005fRUNNING-1947"></a><br><dt><code>gdb.COMMAND_RUNNING</code><dd>The command is related to running the inferior. For example, 172<code>start</code>, <code>step</code>, and <code>continue</code> are in this category. 173Type <kbd>help running</kbd> at the <span class="sc">gdb</span> prompt to see a list of 174commands in this category. 175 176 <p><a name="index-COMMAND_005fDATA-1948"></a><a name="index-gdb_002eCOMMAND_005fDATA-1949"></a><br><dt><code>gdb.COMMAND_DATA</code><dd>The command is related to data or variables. For example, 177<code>call</code>, <code>find</code>, and <code>print</code> are in this category. Type 178<kbd>help data</kbd> at the <span class="sc">gdb</span> prompt to see a list of commands 179in this category. 180 181 <p><a name="index-COMMAND_005fSTACK-1950"></a><a name="index-gdb_002eCOMMAND_005fSTACK-1951"></a><br><dt><code>gdb.COMMAND_STACK</code><dd>The command has to do with manipulation of the stack. For example, 182<code>backtrace</code>, <code>frame</code>, and <code>return</code> are in this 183category. Type <kbd>help stack</kbd> at the <span class="sc">gdb</span> prompt to see a 184list of commands in this category. 185 186 <p><a name="index-COMMAND_005fFILES-1952"></a><a name="index-gdb_002eCOMMAND_005fFILES-1953"></a><br><dt><code>gdb.COMMAND_FILES</code><dd>This class is used for file-related commands. For example, 187<code>file</code>, <code>list</code> and <code>section</code> are in this category. 188Type <kbd>help files</kbd> at the <span class="sc">gdb</span> prompt to see a list of 189commands in this category. 190 191 <p><a name="index-COMMAND_005fSUPPORT-1954"></a><a name="index-gdb_002eCOMMAND_005fSUPPORT-1955"></a><br><dt><code>gdb.COMMAND_SUPPORT</code><dd>This should be used for “support facilities”, generally meaning 192things that are useful to the user when interacting with <span class="sc">gdb</span>, 193but not related to the state of the inferior. For example, 194<code>help</code>, <code>make</code>, and <code>shell</code> are in this category. Type 195<kbd>help support</kbd> at the <span class="sc">gdb</span> prompt to see a list of 196commands in this category. 197 198 <p><a name="index-COMMAND_005fSTATUS-1956"></a><a name="index-gdb_002eCOMMAND_005fSTATUS-1957"></a><br><dt><code>gdb.COMMAND_STATUS</code><dd>The command is an ‘<samp><span class="samp">info</span></samp>’-related command, that is, related to the 199state of <span class="sc">gdb</span> itself. For example, <code>info</code>, <code>macro</code>, 200and <code>show</code> are in this category. Type <kbd>help status</kbd> at the 201<span class="sc">gdb</span> prompt to see a list of commands in this category. 202 203 <p><a name="index-COMMAND_005fBREAKPOINTS-1958"></a><a name="index-gdb_002eCOMMAND_005fBREAKPOINTS-1959"></a><br><dt><code>gdb.COMMAND_BREAKPOINTS</code><dd>The command has to do with breakpoints. For example, <code>break</code>, 204<code>clear</code>, and <code>delete</code> are in this category. Type <kbd>help 205breakpoints</kbd> at the <span class="sc">gdb</span> prompt to see a list of commands in 206this category. 207 208 <p><a name="index-COMMAND_005fTRACEPOINTS-1960"></a><a name="index-gdb_002eCOMMAND_005fTRACEPOINTS-1961"></a><br><dt><code>gdb.COMMAND_TRACEPOINTS</code><dd>The command has to do with tracepoints. For example, <code>trace</code>, 209<code>actions</code>, and <code>tfind</code> are in this category. Type 210<kbd>help tracepoints</kbd> at the <span class="sc">gdb</span> prompt to see a list of 211commands in this category. 212 213 <p><a name="index-COMMAND_005fUSER-1962"></a><a name="index-gdb_002eCOMMAND_005fUSER-1963"></a><br><dt><code>gdb.COMMAND_USER</code><dd>The command is a general purpose command for the user, and typically 214does not fit in one of the other categories. 215Type <kbd>help user-defined</kbd> at the <span class="sc">gdb</span> prompt to see 216a list of commands in this category, as well as the list of gdb macros 217(see <a href="Sequences.html#Sequences">Sequences</a>). 218 219 <p><a name="index-COMMAND_005fOBSCURE-1964"></a><a name="index-gdb_002eCOMMAND_005fOBSCURE-1965"></a><br><dt><code>gdb.COMMAND_OBSCURE</code><dd>The command is only used in unusual circumstances, or is not of 220general interest to users. For example, <code>checkpoint</code>, 221<code>fork</code>, and <code>stop</code> are in this category. Type <kbd>help 222obscure</kbd> at the <span class="sc">gdb</span> prompt to see a list of commands in this 223category. 224 225 <p><a name="index-COMMAND_005fMAINTENANCE-1966"></a><a name="index-gdb_002eCOMMAND_005fMAINTENANCE-1967"></a><br><dt><code>gdb.COMMAND_MAINTENANCE</code><dd>The command is only useful to <span class="sc">gdb</span> maintainers. The 226<code>maintenance</code> and <code>flushregs</code> commands are in this category. 227Type <kbd>help internals</kbd> at the <span class="sc">gdb</span> prompt to see a list of 228commands in this category. 229</dl> 230 231 <p>A new command can use a predefined completion function, either by 232specifying it via an argument at initialization, or by returning it 233from the <code>complete</code> method. These predefined completion 234constants are all defined in the <code>gdb</code> module: 235 236 237<a name="index-COMPLETE_005fNONE-1968"></a> 238<a name="index-gdb_002eCOMPLETE_005fNONE-1969"></a> 239<dl><dt><code>gdb.COMPLETE_NONE</code><dd>This constant means that no completion should be done. 240 241 <p><a name="index-COMPLETE_005fFILENAME-1970"></a><a name="index-gdb_002eCOMPLETE_005fFILENAME-1971"></a><br><dt><code>gdb.COMPLETE_FILENAME</code><dd>This constant means that filename completion should be performed. 242 243 <p><a name="index-COMPLETE_005fLOCATION-1972"></a><a name="index-gdb_002eCOMPLETE_005fLOCATION-1973"></a><br><dt><code>gdb.COMPLETE_LOCATION</code><dd>This constant means that location completion should be done. 244See <a href="Specify-Location.html#Specify-Location">Specify Location</a>. 245 246 <p><a name="index-COMPLETE_005fCOMMAND-1974"></a><a name="index-gdb_002eCOMPLETE_005fCOMMAND-1975"></a><br><dt><code>gdb.COMPLETE_COMMAND</code><dd>This constant means that completion should examine <span class="sc">gdb</span> 247command names. 248 249 <p><a name="index-COMPLETE_005fSYMBOL-1976"></a><a name="index-gdb_002eCOMPLETE_005fSYMBOL-1977"></a><br><dt><code>gdb.COMPLETE_SYMBOL</code><dd>This constant means that completion should be done using symbol names 250as the source. 251</dl> 252 253 <p>The following code snippet shows how a trivial CLI command can be 254implemented in Python: 255 256<pre class="smallexample"> class HelloWorld (gdb.Command): 257 """Greet the whole world.""" 258 259 def __init__ (self): 260 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) 261 262 def invoke (self, arg, from_tty): 263 print "Hello, World!" 264 265 HelloWorld () 266</pre> 267 <p>The last line instantiates the class, and is necessary to trigger the 268registration of the command with <span class="sc">gdb</span>. Depending on how the 269Python code is read into <span class="sc">gdb</span>, you may need to import the 270<code>gdb</code> module explicitly. 271 272 </body></html> 273 274