A user-defined command is a sequence of gdb commands to
which you assign a new name as a command. This is done with the
define
command. User commands may accept an unlimited number of arguments
separated by whitespace. Arguments are accessed within the user command
via $arg0...$argN
. A trivial example:
define adder print $arg0 + $arg1 + $arg2 end
To execute the command use:
adder 1 2 3
This defines the command adder
, which prints the sum of
its three arguments. Note the arguments are text substitutions, so they may
reference variables, use complex expressions, or even perform inferior
functions calls.
In addition, $argc
may be used to find out how many arguments have
been passed.
define adder if $argc == 2 print $arg0 + $arg1 end if $argc == 3 print $arg0 + $arg1 + $arg2 end end
Combining with the eval
command (see eval) makes it easier
to process a variable number of arguments:
define adder set $i = 0 set $sum = 0 while $i < $argc eval "set $sum = $sum + $arg%d", $i set $i = $i + 1 end print $sum end
define
commandnameThe definition of the command is made up of other gdb command lines,
which are given following the define
command. The end of these
commands is marked by a line containing end
.
document
commandnamehelp
. The command commandname must already be
defined. This command reads lines of documentation just as define
reads the lines of the command definition, ending with end
.
After the document
command is finished, help
on command
commandname displays the documentation you have written.
You may use the document
command again to change the
documentation of a command. Redefining the command with define
does not change the documentation.
It is also possible to document user-defined aliases. The alias documentation
will then be used by the help
and apropos
commands
instead of the documentation of the aliased command.
Documenting a user-defined alias is particularly useful when defining
an alias as a set of nested with
commands
(see Command aliases default args).
define-prefix
commandnamedefine
command.
Note that define-prefix
can be used with a not yet defined
commandname. In such a case, commandname is defined as
an empty user-defined command.
In case you redefine a command that was marked as a user-defined
prefix command, the subcommands of the redefined command are kept
(and gdb indicates so to the user).
Example:
(gdb) define-prefix abc (gdb) define-prefix abc def (gdb) define abc def Type commands for definition of "abc def". End with a line saying just "end". >echo command initial def\n >end (gdb) define abc def ghi Type commands for definition of "abc def ghi". End with a line saying just "end". >echo command ghi\n >end (gdb) define abc def Keeping subcommands of prefix command "def". Redefine command "def"? (y or n) y Type commands for definition of "abc def". End with a line saying just "end". >echo command def\n >end (gdb) abc def ghi command ghi (gdb) abc def command def (gdb)
dont-repeat
help user-defined
show user
show user
commandnameshow max-user-call-depth
set max-user-call-depth
max-user-call-depth
controls how many recursion
levels are allowed in user-defined commands before gdb suspects an
infinite recursion and aborts the command.
This does not apply to user-defined python commands.
In addition to the above commands, user-defined commands frequently use control flow commands, described in Command Files.
When user-defined commands are executed, the commands of the definition are not printed. An error in any command stops execution of the user-defined command.
If used interactively, commands that would ask for confirmation proceed without asking when used inside a user-defined command. Many gdb commands that normally print messages to say what they are doing omit the messages when used in a user-defined command.