22.1. User-defined commands
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 up to 10 arguments
separated by whitespace. Arguments are accessed within the user command
via $arg0…$arg9. A trivial example:
define adder
print $arg0 + $arg1 + $arg2 |
To execute the command use:
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.
- define commandname
Define a command named commandname. If there is already a command
by that name, you are asked to confirm that you want to redefine it.
The 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.
- if
Takes a single argument, which is an expression to evaluate.
It is followed by a series of commands that are executed
only if the expression is true (nonzero).
There can then optionally be a line else, followed
by a series of commands that are only executed if the expression
was false. The end of the list is marked by a line containing end.
- while
The syntax is similar to if: the command takes a single argument,
which is an expression to evaluate, and must be followed by the commands to
execute, one per line, terminated by an end.
The commands are executed repeatedly as long as the expression
evaluates to true.
- document commandname
Document the user-defined command commandname, so that it can be
accessed by help. 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.
- help user-defined
List all user-defined commands, with the first line of the documentation
(if any) for each.
- show user, show user commandname
Display the gdb commands used to define commandname (but
not its documentation). If no commandname is given, display the
definitions for all user-defined commands.
- show max-user-call-depth, set max-user-call-depth
The value of 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.
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.
