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:
It has been proven in practice (it is already on its second generation).
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-showoutput-radix
-stack-list-arguments
-stack-list-locals
-stack-select-frame
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:
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.
26.18.3. Description And Use of Operations on Variable Objects
This section describes the use of operations on variable objects.
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 nameformat-spec
Sets the output format for the value of the object name to be
format-spec.
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 nameexpression
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.
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.
