Next: Hooks, Up: Sequences [Contents][Index]

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

Next: Hooks, Up: Sequences [Contents][Index]