Debugging with GDB (February 2008)

Chapter 18: Canned Sequences of Commands 255
18 Canned Sequences of Commands
In addition to breakpoint commands (see Section 5.1.6 [Breakpoint command lists],
page 41), GDB provides the following two ways to store sequence of commands for execution
as a unit:
• user-defined commands
• command files
18.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. The following example illustrates the use of canned sequence
of commands:
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 further functions calls.
The following contructs can be used to create canned sequence of commands:
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).
The if clause can be followed by an optional else clause. You can add a list of
commands to the else clause which get executed only if the expression is false.
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 ac-
cessed 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 fin-
ished, help on command commandname displays the documentation you have
written.