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 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, dots, and underscores. It may also start with any predefined or user-defined 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.

`define-prefix` commandname
  Define or mark the command commandname as a user-defined prefix command. Once marked, commandname can be used as prefix command by the `define` command. Note that `define-prefix` can be used with a not yet defined commandname. In such a case, commandname is defined as an empty user-defined command. In case you redefine a command that was marked as a user-defined prefix command, the subcommands of the redefined command are kept (and gdb indicates so to the user).

  Example:

                (gdb) define-prefix abc
                (gdb) define-prefix abc def
                (gdb) define abc def
                Type commands for definition of "abc def".
                End with a line saying just "end".
                >echo command initial def\n
                >end
                (gdb) define abc def ghi
                Type commands for definition of "abc def ghi".
                End with a line saying just "end".
                >echo command ghi\n
                >end
                (gdb) define abc def
                Keeping subcommands of prefix command "def".
                Redefine command "def"? (y or n) y
                Type commands for definition of "abc def".
                End with a line saying just "end".
                >echo command def\n
                >end
                (gdb) abc def ghi
                command ghi
                (gdb) abc def
                command def
                (gdb)

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