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 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 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 argument 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 define command. The end of these commands is marked by a line containing end.

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.

dont-repeat

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).

help user-defined

List all user-defined commands and all python commands defined in class COMAND_USER. The first line of the documentation or docstring is included (if any).

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. This does not work for user-defined python 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. 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.