[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 20. Canned Sequences of Commands

Aside from breakpoint commands (see section Breakpoint Command Lists), GDB provides two ways to store sequences of commands for execution as a unit: user-defined commands and command files.

> 20.1 User-defined Commands |  | How to define your own commands
> 20.2 User-defined Command Hooks |  | Hooks for user-defined commands
> 20.3 Command Files |  | How to write scripts of commands to be stored in a file
> 20.4 Commands for Controlled Output |  | Commands for controlled output

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 20.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 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 section repeat last command).

`help user-defined`
  List all user-defined commands, with the first line of the documentation (if any) for each.

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

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

In addition to the above commands, user-defined commands frequently use control flow commands, described in 20.3 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 20.2 User-defined Command Hooks

You may define hooks, which are a special kind of user-defined command. Whenever you run the command ``foo'`, if the user-defined command ``hook-foo'` exists, it is executed (with no arguments) before that command.

A hook may also be defined which is run after the command you executed. Whenever you run the command ``foo'`, if the user-defined command ``hookpost-foo'` exists, it is executed (with no arguments) after that command. Post-execution hooks may exist simultaneously with pre-execution hooks, for the same command.

It is valid for a hook to call the command which it hooks. If this occurs, the hook is not re-executed, thereby avoiding infinite recursion.

In addition, a pseudo-command, ``stop'` exists. Defining (``hook-stop'`) makes the associated commands execute every time execution stops in your program: before breakpoint commands are run, displays are printed, or the stack frame is printed.

For example, to ignore `SIGALRM` signals while single-stepping, but treat them normally during normal execution, you could define:

    define hook-stop
    handle SIGALRM nopass
    end

    define hook-run
    handle SIGALRM pass
    end

    define hook-continue
    handle SIGALRM pass
    end

As a further example, to hook at the beginning and end of the `echo` command, and to add extra text to the beginning and end of the message, you could define:

    define hook-echo
    echo <<<---
    end

    define hookpost-echo
    echo --->>>\n
    end

    (gdb) echo Hello World
    <<<---Hello World--->>>
    (gdb)

You can define a hook for any single-word command in GDB, but not for command aliases; you should define a hook for the basic command name, e.g. `backtrace` rather than `bt`. If an error occurs during the execution of your hook, execution of GDB commands stops and GDB issues a prompt (before the command that you actually typed had a chance to run).

If you try to define a hook which does not match any known command, you get a warning from the `define` command.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 20.3 Command Files

A command file for GDB is a text file made of lines that are GDB commands. Comments (lines starting with `#`) may also be included. An empty line in a command file does nothing; it does not mean to repeat the last command, as it would from the terminal.

You can request the execution of a command file with the `source` command:

`source [`-v`] filename`
  Execute the command file filename.

The lines in a command file are generally executed sequentially, unless the order of execution is changed by one of the flow-control commands described below. The commands are not printed as they are executed. An error in any command terminates execution of the command file and control is returned to the console.

GDB searches for filename in the current directory and then on the search path (specified with the ``directory'` command).

If `-v`, for verbose mode, is given then GDB displays each command as it is executed. The option must be given before filename, and is interpreted as part of the filename anywhere else.

Commands that would ask for confirmation if used interactively proceed without asking when used in a command file. Many GDB commands that normally print messages to say what they are doing omit the messages when called from command files.

GDB also accepts command input from standard input. In this mode, normal output goes to standard output and error output goes to standard error. Errors in a command file supplied on standard input do not terminate execution of the command file--execution continues with the next command.

    gdb < cmds > log 2>&1

(The syntax above will vary depending on the shell used.) This example will execute commands from the file ``cmds'`. All output and errors would be directed to ``log'`.

Since commands stored on command files tend to be more general than commands typed interactively, they frequently need to deal with complicated situations, such as different or unexpected values of variables and symbols, changes in how the program being debugged is built, etc. GDB provides a set of flow-control commands to deal with these complexities. Using these commands, you can write complex scripts that loop over data structures, execute commands conditionally, etc.

`if`
`else`
  This command allows to include in your script conditionally executed commands. The `if` command 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 (its value is nonzero). There can then optionally be an `else` line, followed by a series of commands that are only executed if the expression was false. The end of the list is marked by a line containing `end`.

`while`
  This command allows to write loops. Its 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`. These commands are called the body of the loop. The commands in the body of `while` are executed repeatedly as long as the expression evaluates to true.

`loop_break`
  This command exits the `while` loop in whose body it is included. Execution of the script continues after that `while`s `end` line.

`loop_continue`
  This command skips the execution of the rest of the body of commands in the `while` loop in whose body it is included. Execution branches to the beginning of the `while` loop, where it evaluates the controlling expression.

`end`
  Terminate the block of commands that are the body of `if`, `else`, or `while` flow-control commands.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 20.4 Commands for Controlled Output

During the execution of a command file or a user-defined command, normal GDB output is suppressed; the only output that appears is what is explicitly printed by the commands in the definition. This section describes three commands useful for generating exactly the output you want.

`echo text`
  Print text. Nonprinting characters can be included in text using C escape sequences, such as ``\n'` to print a newline. No newline is printed unless you specify one. In addition to the standard C escape sequences, a backslash followed by a space stands for a space. This is useful for displaying a string with spaces at the beginning or the end, since leading and trailing spaces are otherwise trimmed from all arguments. To print `` and foo = '`, use the command ``echo \ and foo = \ '`.

  A backslash at the end of text can be used, as in C, to continue the command onto subsequent lines. For example,

      echo This is some text\n\
      which is continued\n\
      onto several lines.\n

  produces the same output as

      echo This is some text\n
      echo which is continued\n
      echo onto several lines.\n

`output expression`
  Print the value of expression and nothing but that value: no newlines, no ``$nn = '`. The value is not entered in the value history either. See section Expressions, for more information on expressions.

`output/fmt expression`
  Print the value of expression in format fmt. You can use the same formats as for `print`. See section Output Formats, for more information.

`printf template, expressions...`
  Print the values of one or more expressions under the control of the string template. To print several values, make expressions be a comma-separated list of individual expressions, which may be either numbers or pointers. Their values are printed as specified by template, exactly as a C program would do by executing the code below:

      printf (template, expressions...);

  As in `C` `printf`, ordinary characters in template are printed verbatim, while conversion specification introduced by the ``%'` character cause subsequent expressions to be evaluated, their values converted and formatted according to type and style information encoded in the conversion specifications, and then printed.

  For example, you can print two values in hex like this:

      printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo

  `printf` supports all the standard `C` conversion specifications, including the flags and modifiers between the ``%'` character and the conversion letter, with the following exceptions:

  - The argument-ordering modifiers, such as ``2$'`, are not supported.

  - The modifier ``*'` is not supported for specifying precision or width.

  - The ``''` flag (for separation of digits into groups according to `LC_NUMERIC'`) is not supported.

  - The type modifiers ``hh'`, ``j'`, ``t'`, and ``z'` are not supported.

  - The conversion letter ``n'` (as in ``%n'`) is not supported.

  - The conversion letters ``a'` and ``A'` are not supported.

  Note that the ``ll'` type modifier is supported only if the underlying `C` implementation used to build GDB supports the `long long int` type, and the ``L'` type modifier is supported only if `long double` type is available.

  As in `C`, `printf` supports simple backslash-escape sequences, such as `\n`, ``\t'`, ``\\'`, ``\"'`, ``\a'`, and ``\f'`, that consist of backslash followed by a single character. Octal and hexadecimal escape sequences are not supported.

  Additionally, `printf` supports conversion specifications for DFP (Decimal Floating Point) types using the following length modifiers together with a floating point specifier. letters:

  - ``H'` for printing `Decimal32` types.

  - ``D'` for printing `Decimal64` types.

  - ``DD'` for printing `Decimal128` types.

  If the underlying `C` implementation used to build GDB has support for the three length modifiers for DFP types, other modifiers such as width and precision will also be available for GDB to use.

  In case there is no such `C` support, no additional modifiers will be available and the value will be printed in the standard way.

  Here's an example of printing DFP types using the above conversion letters:

      printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GDB Administrator on March, 27 2008 using texi2html