26.18. gdb/mi Variable Objects

26.18.1. 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:

26.18.2. 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:

OperationDescription
-var-createcreate a variable object
-var-deletedelete the variable object and its children
-var-set-formatset the display format of this variable
-var-show-formatshow the display format of this variable
-var-info-num-childrentells how many children this object has
-var-list-childrenreturn a list of the object's children
-var-info-typeshow the type of this variable object
-var-info-expressionprint what this variable object represents
-var-show-attributesis this variable editable? does it exist here?
-var-evaluate-expressionget the value of this variable
-var-assignset the value of this variable
-var-updateupdate the variable and its children

In the next subsection we describe each operation in detail and suggest how it can be used.

26.18.3. Description And Use of Operations on Variable Objects

This section describes the use of operations on variable objects.

26.18.4. The -var-createCommand

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

26.18.4.2. 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"

26.18.5. The -var-deleteCommand

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

26.18.6. The -var-set-formatCommand

26.18.6.1. 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}

26.18.7. The -var-show-formatCommand

26.18.7.1. Synopsis

 -var-show-format name

Returns the format used to display the value of the object name.

 format ==>
 format-spec

26.18.8. The -var-info-num-childrenCommand

26.18.8.1. Synopsis

 -var-info-num-children name

Returns the number of children of a variable object name:

 numchild=n

26.18.9. The -var-list-childrenCommand

26.18.9.1. Synopsis

 -var-list-children name

Returns a list of the children of the specified variable object:

 numchild=n,children=[{name=name,
 numchild=n,type=type},(repeats N times)]

26.18.10. The -var-info-typeCommand

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

26.18.11. The -var-info-expressionCommand

26.18.11.1. 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"}.

26.18.12. The -var-show-attributes Command

26.18.12.1. Synopsis

 -var-show-attributes name

List attributes of the specified variable object name:

 status=attr [ ( ,attr )* ]

where attr is { { editable | noneditable } | TBD }.

26.18.13. The -var-evaluate-expression Command

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

26.18.14. The -var-assignCommand

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

26.18.14.2. Example

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

26.18.15. The -var-updateCommand

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