You can implement new gdb CLI commands in Python. A CLI
command is implemented using an instance of the
class, most commonly using a subclass.
The object initializer for
Commandregisters the new command with gdb. This initializer is normally invoked from the subclass' own
name is the name of the command. If name 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.
There is no support for multi-line commands.
command_class should be one of the ‘COMMAND_’ constants defined below. This argument tells gdb how to categorize the new command in the help system.
completer_class is an optional argument. If given, it should be one of the ‘COMPLETE_’ constants defined below. This argument tells gdb how to perform completion for this command. If not given, gdb will attempt to complete using the object's
completemethod (see below); if no such method is found, an error will occur when completion is attempted.
prefix is an optional argument. If
True, then the new command is a prefix command; sub-commands of this command may be registered.
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 “This command is not documented.” is used.
By default, a gdb command is repeated when the user enters a blank line at the command prompt. A command can suppress this behavior by invoking the
dont_repeatmethod. This is similar to the user command
dont-repeat, see dont-repeat.
This method is called by gdb when this command is invoked.
argument is a string. It is the argument to the command, after leading and trailing whitespace has been stripped.
from_tty 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.
If this method throws an exception, it is turned into a gdb
errorcall. Otherwise, the return value is ignored.
To break argument up into an argv-like string use
gdb.string_to_argv. This function behaves identically to gdb's internal argument lexer
buildargv. It is recommended to use this for consistency. Arguments are separated by spaces and may be quoted. Example:print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") ['1', '2 "3', '4 "5', "6 '7"]
This method is called by gdb when the user attempts completion on this command. All forms of completion are handled by this method, that is, the <TAB> and <M-?> key bindings (see Completion), and the
completecommand (see complete).
The arguments text and word are both strings; text holds the complete command line up to the cursor's location, while word holds the last word of the command line; this is computed using a word-breaking heuristic.
completemethod can return several values:
- If the return value is a sequence, the contents of the sequence are used as the completions. It is up to
completeto 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.
- If the return value is one of the ‘COMPLETE_’ constants defined below, then the corresponding gdb-internal completion function is invoked, and its result is used.
- All other results are treated as though there were no available completions.
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
continueare in this category. Type help running at the gdb prompt to see a list of commands in this category.
returnare in this category. Type help stack at the gdb prompt to see a list of commands in this category.
sectionare in this category. Type help files at the gdb prompt to see a list of commands in this category.
shellare in this category. Type help support at the gdb prompt to see a list of commands in this category.
showare in this category. Type help status at the gdb prompt to see a list of commands in this category.
deleteare in this category. Type help breakpoints at the gdb prompt to see a list of commands in this category.
tfindare in this category. Type help tracepoints at the gdb prompt to see a list of commands in this category.
stopare in this category. Type help obscure at the gdb prompt to see a list of commands in this category.
flushregscommands are in this category. Type help internals at the gdb prompt to see a list of commands in this category.
A new command can use a predefined completion function, either by
specifying it via an argument at initialization, or by returning it
complete method. These predefined completion
constants are all defined in the
The following code snippet shows how a trivial CLI command can be implemented in Python:
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 ()
The last line instantiates the class, and is necessary to trigger the
registration of the command with gdb. Depending on how the
Python code is read into gdb, you may need to import the
gdb module explicitly.