<html lang="en">
<head>
<title>Commands In Python - Debugging with GDB</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Debugging with GDB">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Python-API.html#Python-API" title="Python API">
<link rel="prev" href="Recordings-In-Python.html#Recordings-In-Python" title="Recordings In Python">
<link rel="next" href="Parameters-In-Python.html#Parameters-In-Python" title="Parameters In Python">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1988-2019 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software'' and ``Free Software Needs
Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="Commands-In-Python"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Parameters-In-Python.html#Parameters-In-Python">Parameters In Python</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Recordings-In-Python.html#Recordings-In-Python">Recordings In Python</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a>
<hr>
</div>

<h5 class="subsubsection">23.2.2.20 Commands In Python</h5>

<p><a name="index-commands-in-python-2138"></a><a name="index-python-commands-2139"></a>You can implement new <span class="sc">gdb</span> CLI commands in Python.  A CLI
command is implemented using an instance of the <code>gdb.Command</code>
class, most commonly using a subclass.

<div class="defun">
&mdash; 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-2140"></a></var><br>
<blockquote><p>The object initializer for <code>Command</code> registers the new command
with <span class="sc">gdb</span>.  This initializer is normally invoked from the
subclass' own <code>__init__</code> method.

        <p><var>name</var> is the name of the command.  If <var>name</var> consists of
multiple words, then the initial words are looked for as prefix
commands.  In this case, if one of the prefix commands does not exist,
an exception is raised.

        <p>There is no support for multi-line commands.

        <p><var>command_class</var> should be one of the &lsquo;<samp><span class="samp">COMMAND_</span></samp>&rsquo; constants
defined below.  This argument tells <span class="sc">gdb</span> how to categorize the
new command in the help system.

        <p><var>completer_class</var> is an optional argument.  If given, it should be
one of the &lsquo;<samp><span class="samp">COMPLETE_</span></samp>&rsquo; constants defined below.  This argument
tells <span class="sc">gdb</span> how to perform completion for this command.  If not
given, <span class="sc">gdb</span> will attempt to complete using the object's
<code>complete</code> method (see below); if no such method is found, an
error will occur when completion is attempted.

        <p><var>prefix</var> is an optional argument.  If <code>True</code>, then the new
command is a prefix command; sub-commands of this command may be
registered.

        <p>The help text for the new command is taken from the Python
documentation string for the command's class, if there is one.  If no
documentation string is provided, the default value &ldquo;This command is
not documented.&rdquo; is used. 
</p></blockquote></div>

   <p><a name="index-don_0027t-repeat-Python-command-2141"></a>

<div class="defun">
&mdash; Function: <b>Command.dont_repeat</b> ()<var><a name="index-Command_002edont_005frepeat-2142"></a></var><br>
<blockquote><p>By default, a <span class="sc">gdb</span> command is repeated when the user enters a
blank line at the command prompt.  A command can suppress this
behavior by invoking the <code>dont_repeat</code> method.  This is similar
to the user command <code>dont-repeat</code>, see <a href="Define.html#Define">dont-repeat</a>. 
</p></blockquote></div>

<div class="defun">
&mdash; Function: <b>Command.invoke</b> (<var>argument, from_tty</var>)<var><a name="index-Command_002einvoke-2143"></a></var><br>
<blockquote><p>This method is called by <span class="sc">gdb</span> when this command is invoked.

        <p><var>argument</var> is a string.  It is the argument to the command, after
leading and trailing whitespace has been stripped.

        <p><var>from_tty</var> is a boolean argument.  When true, this means that the
command was entered by the user at the terminal; when false it means
that the command came from elsewhere.

        <p>If this method throws an exception, it is turned into a <span class="sc">gdb</span>
<code>error</code> call.  Otherwise, the return value is ignored.

        <p><a name="index-gdb_002estring_005fto_005fargv-2144"></a>To break <var>argument</var> up into an argv-like string use
<code>gdb.string_to_argv</code>.  This function behaves identically to
<span class="sc">gdb</span>'s internal argument lexer <code>buildargv</code>. 
It is recommended to use this for consistency. 
Arguments are separated by spaces and may be quoted. 
Example:

     <pre class="smallexample">          print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
          ['1', '2 "3', '4 "5', "6 '7"]
</pre>
        </blockquote></div>

   <p><a name="index-completion-of-Python-commands-2145"></a>

<div class="defun">
&mdash; Function: <b>Command.complete</b> (<var>text, word</var>)<var><a name="index-Command_002ecomplete-2146"></a></var><br>
<blockquote><p>This method is called by <span class="sc">gdb</span> when the user attempts
completion on this command.  All forms of completion are handled by
this method, that is, the &lt;TAB&gt; and &lt;M-?&gt; key bindings
(see <a href="Completion.html#Completion">Completion</a>), and the <code>complete</code> command (see <a href="Help.html#Help">complete</a>).

        <p>The arguments <var>text</var> and <var>word</var> are both strings; <var>text</var>
holds the complete command line up to the cursor's location, while
<var>word</var> holds the last word of the command line; this is computed
using a word-breaking heuristic.

        <p>The <code>complete</code> method can return several values:
          <ul>
<li>If the return value is a sequence, the contents of the sequence are
used as the completions.  It is up to <code>complete</code> to ensure that the
contents actually do complete the word.  A zero-length sequence is
allowed, it means that there were no completions available.  Only
string elements of the sequence are used; other elements in the
sequence are ignored.

          <li>If the return value is one of the &lsquo;<samp><span class="samp">COMPLETE_</span></samp>&rsquo; constants defined
below, then the corresponding <span class="sc">gdb</span>-internal completion
function is invoked, and its result is used.

          <li>All other results are treated as though there were no available
completions. 
</ul>
        </p></blockquote></div>

   <p>When a new command is registered, it must be declared as a member of
some general class of commands.  This is used to classify top-level
commands in the on-line help system; note that prefix commands are not
listed under their own category but rather that of their top-level
command.  The available classifications are represented by constants
defined in the <code>gdb</code> module:

     
<a name="index-COMMAND_005fNONE-2147"></a>
<a name="index-gdb_002eCOMMAND_005fNONE-2148"></a>
<dl><dt><code>gdb.COMMAND_NONE</code><dd>The command does not belong to any particular class.  A command in
this category will not be displayed in any of the help categories.

     <p><a name="index-COMMAND_005fRUNNING-2149"></a><a name="index-gdb_002eCOMMAND_005fRUNNING-2150"></a><br><dt><code>gdb.COMMAND_RUNNING</code><dd>The command is related to running the inferior.  For example,
<code>start</code>, <code>step</code>, and <code>continue</code> are in this category. 
Type <kbd>help running</kbd> at the <span class="sc">gdb</span> prompt to see a list of
commands in this category.

     <p><a name="index-COMMAND_005fDATA-2151"></a><a name="index-gdb_002eCOMMAND_005fDATA-2152"></a><br><dt><code>gdb.COMMAND_DATA</code><dd>The command is related to data or variables.  For example,
<code>call</code>, <code>find</code>, and <code>print</code> are in this category.  Type
<kbd>help data</kbd> at the <span class="sc">gdb</span> prompt to see a list of commands
in this category.

     <p><a name="index-COMMAND_005fSTACK-2153"></a><a name="index-gdb_002eCOMMAND_005fSTACK-2154"></a><br><dt><code>gdb.COMMAND_STACK</code><dd>The command has to do with manipulation of the stack.  For example,
<code>backtrace</code>, <code>frame</code>, and <code>return</code> are in this
category.  Type <kbd>help stack</kbd> at the <span class="sc">gdb</span> prompt to see a
list of commands in this category.

     <p><a name="index-COMMAND_005fFILES-2155"></a><a name="index-gdb_002eCOMMAND_005fFILES-2156"></a><br><dt><code>gdb.COMMAND_FILES</code><dd>This class is used for file-related commands.  For example,
<code>file</code>, <code>list</code> and <code>section</code> are in this category. 
Type <kbd>help files</kbd> at the <span class="sc">gdb</span> prompt to see a list of
commands in this category.

     <p><a name="index-COMMAND_005fSUPPORT-2157"></a><a name="index-gdb_002eCOMMAND_005fSUPPORT-2158"></a><br><dt><code>gdb.COMMAND_SUPPORT</code><dd>This should be used for &ldquo;support facilities&rdquo;, generally meaning
things that are useful to the user when interacting with <span class="sc">gdb</span>,
but not related to the state of the inferior.  For example,
<code>help</code>, <code>make</code>, and <code>shell</code> are in this category.  Type
<kbd>help support</kbd> at the <span class="sc">gdb</span> prompt to see a list of
commands in this category.

     <p><a name="index-COMMAND_005fSTATUS-2159"></a><a name="index-gdb_002eCOMMAND_005fSTATUS-2160"></a><br><dt><code>gdb.COMMAND_STATUS</code><dd>The command is an &lsquo;<samp><span class="samp">info</span></samp>&rsquo;-related command, that is, related to the
state of <span class="sc">gdb</span> itself.  For example, <code>info</code>, <code>macro</code>,
and <code>show</code> are in this category.  Type <kbd>help status</kbd> at the
<span class="sc">gdb</span> prompt to see a list of commands in this category.

     <p><a name="index-COMMAND_005fBREAKPOINTS-2161"></a><a name="index-gdb_002eCOMMAND_005fBREAKPOINTS-2162"></a><br><dt><code>gdb.COMMAND_BREAKPOINTS</code><dd>The command has to do with breakpoints.  For example, <code>break</code>,
<code>clear</code>, and <code>delete</code> are in this category.  Type <kbd>help
breakpoints</kbd> at the <span class="sc">gdb</span> prompt to see a list of commands in
this category.

     <p><a name="index-COMMAND_005fTRACEPOINTS-2163"></a><a name="index-gdb_002eCOMMAND_005fTRACEPOINTS-2164"></a><br><dt><code>gdb.COMMAND_TRACEPOINTS</code><dd>The command has to do with tracepoints.  For example, <code>trace</code>,
<code>actions</code>, and <code>tfind</code> are in this category.  Type
<kbd>help tracepoints</kbd> at the <span class="sc">gdb</span> prompt to see a list of
commands in this category.

     <p><a name="index-COMMAND_005fUSER-2165"></a><a name="index-gdb_002eCOMMAND_005fUSER-2166"></a><br><dt><code>gdb.COMMAND_USER</code><dd>The command is a general purpose command for the user, and typically
does not fit in one of the other categories. 
Type <kbd>help user-defined</kbd> at the <span class="sc">gdb</span> prompt to see
a list of commands in this category, as well as the list of gdb macros
(see <a href="Sequences.html#Sequences">Sequences</a>).

     <p><a name="index-COMMAND_005fOBSCURE-2167"></a><a name="index-gdb_002eCOMMAND_005fOBSCURE-2168"></a><br><dt><code>gdb.COMMAND_OBSCURE</code><dd>The command is only used in unusual circumstances, or is not of
general interest to users.  For example, <code>checkpoint</code>,
<code>fork</code>, and <code>stop</code> are in this category.  Type <kbd>help
obscure</kbd> at the <span class="sc">gdb</span> prompt to see a list of commands in this
category.

     <p><a name="index-COMMAND_005fMAINTENANCE-2169"></a><a name="index-gdb_002eCOMMAND_005fMAINTENANCE-2170"></a><br><dt><code>gdb.COMMAND_MAINTENANCE</code><dd>The command is only useful to <span class="sc">gdb</span> maintainers.  The
<code>maintenance</code> and <code>flushregs</code> commands are in this category. 
Type <kbd>help internals</kbd> at the <span class="sc">gdb</span> prompt to see a list of
commands in this category. 
</dl>

   <p>A new command can use a predefined completion function, either by
specifying it via an argument at initialization, or by returning it
from the <code>complete</code> method.  These predefined completion
constants are all defined in the <code>gdb</code> module:

     
<a name="index-COMPLETE_005fNONE-2171"></a>
<dl><dt><code>gdb.COMPLETE_NONE</code><a name="index-gdb_002eCOMPLETE_005fNONE-2172"></a><dd>This constant means that no completion should be done.

     <p><a name="index-COMPLETE_005fFILENAME-2173"></a><br><dt><code>gdb.COMPLETE_FILENAME</code><a name="index-gdb_002eCOMPLETE_005fFILENAME-2174"></a><dd>This constant means that filename completion should be performed.

     <p><a name="index-COMPLETE_005fLOCATION-2175"></a><br><dt><code>gdb.COMPLETE_LOCATION</code><a name="index-gdb_002eCOMPLETE_005fLOCATION-2176"></a><dd>This constant means that location completion should be done. 
See <a href="Specify-Location.html#Specify-Location">Specify Location</a>.

     <p><a name="index-COMPLETE_005fCOMMAND-2177"></a><br><dt><code>gdb.COMPLETE_COMMAND</code><a name="index-gdb_002eCOMPLETE_005fCOMMAND-2178"></a><dd>This constant means that completion should examine <span class="sc">gdb</span>
command names.

     <p><a name="index-COMPLETE_005fSYMBOL-2179"></a><br><dt><code>gdb.COMPLETE_SYMBOL</code><a name="index-gdb_002eCOMPLETE_005fSYMBOL-2180"></a><dd>This constant means that completion should be done using symbol names
as the source.

     <p><a name="index-COMPLETE_005fEXPRESSION-2181"></a><br><dt><code>gdb.COMPLETE_EXPRESSION</code><a name="index-gdb_002eCOMPLETE_005fEXPRESSION-2182"></a><dd>This constant means that completion should be done on expressions. 
Often this means completing on symbol names, but some language
parsers also have support for completing on field names. 
</dl>

   <p>The following code snippet shows how a trivial CLI command can be
implemented in Python:

<pre class="smallexample">     class HelloWorld (gdb.Command):
       """Greet the whole world."""
     
       def __init__ (self):
         super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
     
       def invoke (self, arg, from_tty):
         print "Hello, World!"
     
     HelloWorld ()
</pre>
   <p>The last line instantiates the class, and is necessary to trigger the
registration of the command with <span class="sc">gdb</span>.  Depending on how the
Python code is read into <span class="sc">gdb</span>, you may need to import the
<code>gdb</code> module explicitly.

   </body></html>