gdb: Commands In Python
23.2.2.20 Commands In Python
............................
You can implement new GDB CLI commands in Python. A CLI command is
implemented using an instance of the 'gdb.Command' class, most commonly
using a subclass.
-- Function: Command.__init__ (name, COMMAND_CLASS [, COMPLETER_CLASS
[, PREFIX]])
The object initializer for 'Command' registers the new command with
GDB. This initializer is normally invoked from the subclass' own
'__init__' method.
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 'complete'
method (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.
-- Function: Command.dont_repeat ()
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_repeat' method. This is similar to the user
command 'dont-repeat', see 
dont-repeat Define.
-- Function: Command.invoke (argument, from_tty)
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 'error'
call. 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"]
-- Function: Command.complete (text, word)
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 (Completion), and
the 'complete' command (complete Help.).
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.
The 'complete' method 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 'complete'
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.
* 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 'gdb' module:
'gdb.COMMAND_NONE'
The command does not belong to any particular class. A command in
this category will not be displayed in any of the help categories.
'gdb.COMMAND_RUNNING'
The command is related to running the inferior. For example,
'start', 'step', and 'continue' are in this category. Type 'help
running' at the GDB prompt to see a list of commands in this
category.
'gdb.COMMAND_DATA'
The command is related to data or variables. For example, 'call',
'find', and 'print' are in this category. Type 'help data' at the
GDB prompt to see a list of commands in this category.
'gdb.COMMAND_STACK'
The command has to do with manipulation of the stack. For example,
'backtrace', 'frame', and 'return' are in this category. Type
'help stack' at the GDB prompt to see a list of commands in this
category.
'gdb.COMMAND_FILES'
This class is used for file-related commands. For example, 'file',
'list' and 'section' are in this category. Type 'help files' at
the GDB prompt to see a list of commands in this category.
'gdb.COMMAND_SUPPORT'
This should be used for "support facilities", generally meaning
things that are useful to the user when interacting with GDB, but
not related to the state of the inferior. For example, 'help',
'make', and 'shell' are in this category. Type 'help support' at
the GDB prompt to see a list of commands in this category.
'gdb.COMMAND_STATUS'
The command is an 'info'-related command, that is, related to the
state of GDB itself. For example, 'info', 'macro', and 'show' are
in this category. Type 'help status' at the GDB prompt to see a
list of commands in this category.
'gdb.COMMAND_BREAKPOINTS'
The command has to do with breakpoints. For example, 'break',
'clear', and 'delete' are in this category. Type 'help
breakpoints' at the GDB prompt to see a list of commands in this
category.
'gdb.COMMAND_TRACEPOINTS'
The command has to do with tracepoints. For example, 'trace',
'actions', and 'tfind' are in this category. Type 'help
tracepoints' at the GDB prompt to see a list of commands in this
category.
'gdb.COMMAND_USER'
The command is a general purpose command for the user, and
typically does not fit in one of the other categories. Type 'help
user-defined' at the GDB prompt to see a list of commands in this
category, as well as the list of gdb macros (Sequences).
'gdb.COMMAND_OBSCURE'
The command is only used in unusual circumstances, or is not of
general interest to users. For example, 'checkpoint', 'fork', and
'stop' are in this category. Type 'help obscure' at the GDB prompt
to see a list of commands in this category.
'gdb.COMMAND_MAINTENANCE'
The command is only useful to GDB maintainers. The 'maintenance'
and 'flushregs' commands 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 from
the 'complete' method. These predefined completion constants are all
defined in the 'gdb' module:
'gdb.COMPLETE_NONE'
This constant means that no completion should be done.
'gdb.COMPLETE_FILENAME'
This constant means that filename completion should be performed.
'gdb.COMPLETE_LOCATION'
This constant means that location completion should be done.
Specify Location.
'gdb.COMPLETE_COMMAND'
This constant means that completion should examine GDB command
names.
'gdb.COMPLETE_SYMBOL'
This constant means that completion should be done using symbol
names as the source.
'gdb.COMPLETE_EXPRESSION'
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.
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.
Info Catalog
gdb: Recordings In Python
gdb: Python API
gdb: Parameters In Python