gdb.info: GDB/MI Variable Objects

Go backward to GDB/MI Tracepoint Commands
Go up to GDB/MI
Go to the top op gdb

GDB/MI Variable Objects

Motivation for Variable Objects in GDB/MI

For the implementation of a variable debugger window (locals, watched
expressions, etc.), we are proposing the adaptation of the existing code
used by `Insight'.
   The two main reasons for that are:
  1. It has been proven in practice (it is already on its second
     generation).
  2. It will shorten development time (needless to say how important it
     is now).
   The original interface was designed to be used by Tcl code, so it was
slightly changed so it could be used through GDB/MI.  This section
describes the GDB/MI operations that will be available and gives some
hints about their use.
   _Note_: In addition to the set of operations described here, we
expect the GUI implementation of a variable window to require, at
least, the following operations:
   * `-gdb-show' `output-radix'
   * `-stack-list-arguments'
   * `-stack-list-locals'
   * `-stack-select-frame'

Introduction to Variable Objects in GDB/MI

The basic idea behind variable objects is the creation of a named object
to represent a variable, an expression, a memory location or even a CPU
register.  For each object created, a set of operations is available for
examining or changing its properties.
   Furthermore, complex data types, such as C structures, are
represented in a tree format.  For instance, the `struct' type variable
is the root and the children will represent the struct members.  If a
child is itself of a complex type, it will also have children of its
own.  Appropriate language differences are handled for C, C++ and Java.
   When returning the actual values of the objects, this facility allows
for the individual selection of the display format used in the result
creation.  It can be chosen among: binary, decimal, hexadecimal, octal
and natural.  Natural refers to a default format automatically chosen
based on the variable type (like decimal for an `int', hex for
pointers, etc.).
   The following is the complete set of GDB/MI operations defined to
access this functionality:
*Operation*                   *Description*
`-var-create'                 create a variable object
`-var-delete'                 delete the variable object and its children
`-var-set-format'             set the display format of this variable
`-var-show-format'            show the display format of this variable
`-var-info-num-children'      tells how many children this object has
`-var-list-children'          return a list of the object's children
`-var-info-type'              show the type of this variable object
`-var-info-expression'        print what this variable object represents
`-var-show-attributes'        is this variable editable? does it exist
                              here?
`-var-evaluate-expression'    get the value of this variable
`-var-assign'                 set the value of this variable
`-var-update'                 update the variable and its children
   In the next subsection we describe each operation in detail and
suggest how it can be used.

Description And Use of Operations on Variable Objects

The `-var-create' Command

Synopsis

      -var-create {NAME | "-"}
         {FRAME-ADDR | "*"} EXPRESSION
   This operation creates a variable object, which allows the
monitoring of a variable, the result of an expression, a memory cell or
a CPU register.
   The NAME parameter is the string by which the object can be
referenced.  It must be unique.  If `-' is specified, the varobj system
will generate a string "varNNNNNN" automatically.  It will be unique
provided that one does not specify NAME on that format.  The command
fails if a duplicate name is found.
   The frame under which the expression should be evaluated can be
specified by FRAME-ADDR.  A `*' indicates that the current frame should
be used.
   EXPRESSION is any expression valid on the current language set (must
not begin with a `*'), or one of the following:
   * `*ADDR', where ADDR is the address of a memory cell
   * `*ADDR-ADDR' -- a memory address range (TBD)
   * `$REGNAME' -- a CPU register name

Result

This operation returns the name, number of children and the type of the
object created.  Type is returned as a string as the ones generated by
the GDB CLI:
      name="NAME",numchild="N",type="TYPE"

The `-var-delete' Command

Synopsis

      -var-delete NAME
   Deletes a previously created variable object and all of its children.
   Returns an error if the object NAME is not found.

The `-var-set-format' Command

Synopsis

      -var-set-format NAME FORMAT-SPEC
   Sets the output format for the value of the object NAME to be
FORMAT-SPEC.
   The syntax for the FORMAT-SPEC is as follows:
      FORMAT-SPEC ==>
      {binary | decimal | hexadecimal | octal | natural}

The `-var-show-format' Command

Synopsis

      -var-show-format NAME
   Returns the format used to display the value of the object NAME.
      FORMAT ==>
      FORMAT-SPEC

The `-var-info-num-children' Command

Synopsis

      -var-info-num-children NAME
   Returns the number of children of a variable object NAME:
      numchild=N

The `-var-list-children' Command

Synopsis

      -var-list-children [PRINT-VALUES] NAME
   Returns a list of the children of the specified variable object.
With just the variable object name as an argument or with an optional
preceding argument of 0 or `--no-values', prints only the names of the
variables.  With an optional preceding argument of 1 or `--all-values',
also prints their values.

Example

     (gdb)
      -var-list-children n
      numchild=N,children=[{name=NAME,
      numchild=N,type=TYPE},(repeats N times)]
     (gdb)
      -var-list-children --all-values n
      numchild=N,children=[{name=NAME,
      numchild=N,value=VALUE,type=TYPE},(repeats N times)]

The `-var-info-type' Command

Synopsis

      -var-info-type NAME
   Returns the type of the specified variable NAME.  The type is
returned as a string in the same format as it is output by the GDB CLI:
      type=TYPENAME

The `-var-info-expression' Command

Synopsis

      -var-info-expression NAME
   Returns what is represented by the variable object NAME:
      lang=LANG-SPEC,exp=EXPRESSION
where LANG-SPEC is `{"C" | "C++" | "Java"}'.

The `-var-show-attributes' Command

Synopsis

      -var-show-attributes NAME
   List attributes of the specified variable object NAME:
      status=ATTR [ ( ,ATTR )* ]
where ATTR is `{ { editable | noneditable } | TBD }'.

The `-var-evaluate-expression' Command

Synopsis

      -var-evaluate-expression NAME
   Evaluates the expression that is represented by the specified
variable object and returns its value as a string in the current format
specified for the object:
      value=VALUE
   Note that one must invoke `-var-list-children' for a variable before
the value of a child variable can be evaluated.

The `-var-assign' Command

Synopsis

      -var-assign NAME EXPRESSION
   Assigns the value of EXPRESSION to the variable object specified by
NAME.  The object must be `editable'.  If the variable's value is
altered by the assign, the variable will show up in any subsequent
`-var-update' list.

Example

     (gdb)
     -var-assign var1 3
     ^done,value="3"
     (gdb)
     -var-update *
     ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}]
     (gdb)

The `-var-update' Command

Synopsis

      -var-update {NAME | "*"}
   Update the value of the variable object NAME by evaluating its
expression after fetching all the new values from memory or registers.
A `*' causes all existing variable objects to be updated.