23.1.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
$arg0...$arg9. 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
define adder if $argc == 2 print $arg0 + $arg1 end if $argc == 3 print $arg0 + $arg1 + $arg2 end end
- 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.
commandname may be a bare command name consisting of letters,
numbers, dashes, and underscores. It may also start with any predefined
prefix command. For example, define target my-target creates
a user-defined target my-target command.
The definition of the command is made up of other gdb command lines, which are given following the
definecommand. The end of these commands is marked by a line containing
- Document the user-defined command commandname, so that it can be
help. The command commandname must already be defined. This command reads lines of documentation just as
definereads the lines of the command definition, ending with
end. After the
documentcommand is finished,
helpon command commandname displays the documentation you have written.
You may use the
documentcommand again to change the documentation of a command. Redefining the command with
definedoes not change the documentation.
- Used inside a user-defined command, this tells gdb that this command should not be repeated when the user hits <RET> (see repeat last command).
- List all user-defined commands, with the first line of the documentation (if any) for each.
- 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.
- The value of
max-user-call-depthcontrols how many recursion levels are allowed in user-defined commands before gdb suspects an infinite recursion and aborts the command.
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.