Next: Hooks, Up: Sequences

#### 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 via `$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 functions calls.

In addition, `$argc` may be used to find out how many arguments have been passed. This expands to a number in the range 0...10.

         define adder
           if $argc == 2
             print $arg0 + $arg1
           end
           if $argc == 3
             print $arg0 + $arg1 + $arg2
           end
         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.