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

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.

Structured Output, The Explain Command

Structured Output, The `Explain` Command