Go to the first, previous, next, last section, table of contents.

# Debugger Commands for Libgdb Applications

The debugger commands available to libgdb applications are the same commands available interactively via GDB. This section is an overview of the commands newly created as part of libgdb.

This section is not by any means a complete reference to the GDB command language. See the GDB manual for such a reference.

- Command Hooks: Setting Hooks to Execute With Debugger Commands.
- View Commands: View Commands Mirror Show Commands
- Breakpoints: The Application Can Have Its Own Breakpoints

## Setting Hooks to Execute With Debugger Commands.

Debugger commands support hooks. A command hook is executed just before the interpreter invokes the hooked command.

There are two hooks allowed for every command. By convention, one hook is for use by users, the other is for use by the application.

A user hook is created for a command XYZZY by using `define-command` to create a command called `hook-XYZZY`.

An application hook is created for a command XYZZY by using `define-command` to create a command called `apphook-XYZZY`.

Application hooks are useful for interfaces which wish to continuously monitor certain aspects of debugger state. The application can set a hook on all commands that might modify the watched state. When the hook is executed, it can use i/o redirection to notify parts of the application that previous data may be out of date. After the top-level loop resumes, the application can recompute any values that may have changed. (See section How the Server's I/O Can be Used.)

## View Commands Mirror Show Commands

The GDB command language contains many `set` and `show` commands. These commands are used to modify or examine parameters to the debugger.

It is difficult to get the current state of a parameter from the `show` command because `show` is very verbose.

    (gdb) show check type
    Type checking is "auto; currently off".
    (gdb) show width
    Number of characters gdb thinks are in a line is 80.

For every `show` command, libgdb includes a `view` command. `view` is like `show` without the verbose commentary:

    (gdb) view check type
    auto; currently off
    (gdb) view width
    80

(The precise format of the ouput from `view` is subject to change. In particular, `view` may one-day print values which can be used as arguments to the corresponding `set` command.)

## The Application Can Have Its Own Breakpoints

The GDB breakpoint commands were written with a strong presumption that all breakpoints are managed by a human user. Therefore, the command language contains commands like `delete' which affect all breakpoints without discrimination.

In libgdb, there is added support for breakpoints and watchpoints which are set by the application and which should not be affected by ordinary, indiscriminate commands. These are called protected breakpoints.

Debugger Command: break-protected ...
Debugger Command: watch-protected ...
  These work like `break` and `watch` except that the resulting breakpoint is given a negative number. Negative numbered breakpoints do not appear in the output of `info breakpoints` but do in that of `info all-breakpoints`. Negative numbered breakpoints are not affected by commands which ordinarily affect `all' breakpoints (e.g. `delete` with no arguments).

  Note that libgdb itself creates protected breakpoints, so programs should not rely on being able to allocate particular protected breakpoint numbers for themselves.

More than one breakpoint may be set at a given location. Libgdb adds the concept of priority to breakpoints. A priority is an integer, assigned to each breakpoint. When a breakpoint is reached, the conditions of all breakpoints at the same location are evaluated in order of ascending priority. When breakpoint commands are executed, they are also executed in ascending priority (until all have been executed, an error occurs, or one set of commands continues the target).

Debugger Command: priority n bplist
  Set the priority for breakpoints bplist to n. By default, breakpoints are assigned a priority of zero.

## Structured Output, The `Explain` Command

(This section may be subject to considerable revision.)

When GDB prints a the value of an expression, the printed representation contains information that can be usefully fed back into future commands and expressions. For example,

    (gdb) print foo
    $16 = {v = 0x38ae0, v_length = 40}

On the basis of this output, a user knows, for example, that `$16.v` refers to a pointer valued `0x38ae0`

A new output command helps to make information like this available to the application.

Debugger Command: explain expression
Debugger Command: explain /format expression
  Print the value of expression in the manner of the `print` command, but embed that output in a list syntax containing information about the structure of the output.

As an example, `explain argv` might produce this output:

    (exp-attribute
       ((expression "$19")
        (type "char **")
        (address "48560")
        (deref-expression "*$19"))
       "$19 = 0x3800\n")

The syntax of output from `explain` is:

    <explanation> :=    <quoted-string>
                      | (exp-concat <explanation> <explanation>*)
                      | (exp-attribute <property-list> <explanation>)

    <property-list> := ( <property-pair>* )

    <property-pair> := ( <property-name> <quoted-string> )

The string-concatenation of all of the `<quoted-string>` (except those in property lists) yields the output generated by the equivalent `print` command. Quoted strings may contain quotes and backslashes if they are escaped by backslash. "\n" in a quoted string stands for newline; unescaped newlines do not occur within the strings output by `explain`.

Property names are made up of alphabetic characters, dashes, and underscores.

The set of properties is open-ended. As GDB acquires support for new source languages and other new capabilities, new property types may be added to the output of this command. Future commands may offer applications some selectivity concerning which properties are reported.

The initial set of properties defined includes:

- `expression` This is an expression, such as `$42` or `$42.x`. The expression can be used to refer to the value printed in the attributed part of the string.
- `type` This is a user-readable name for the type of the attributed value.
- `address` If the value is stored in a target register, this is a register number. If the value is stored in a GDB convenience variable, this is an integer that is unique among all the convenience variables. Otherwise, this is the address in the target where the value is stored.
- `deref-expression` If the attributed value is a pointer type, this is an expression that refers to the dereferenced value.

Here is a larger example, using the same object passed to `print` in an earlier example of this section.

    (gdb) explain foo
    (exp-attribute
      ( (expression "$16")
        (type "struct bytecode_vector")
        (address 14336) )
      (exp-concat
        "$16 = {"
        (exp-attribute
          ( (expression "$16.v")
            (type "char *")
            (address 14336)
            (deref-expression "*$16.v") )
          "v = 0x38ae0")
        (exp-attribute
          ( (expression "$16.v_length")
            (type "int")
            (address 14340) )
          ", v_length = 40")
         "}\n"))

It is undefined how libgdb will indent these lines of output or where newlines will be included.

Go to the first, previous, next, last section, table of contents.