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:
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.
`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.
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.