24.12 GDB/MI Variable Objects

Introduction to Variable Objects

Variable objects are "object-oriented" MI interface for examining and changing values of expressions. Unlike some other MI interfaces that work with expressions, variable objects are specifically designed for simple and efficient presentation in the frontend. A variable object is identified by string name. When a variable object is created, the frontend specifies the expression for that variable object. The expression can be a simple variable, or it can be an arbitrary complex expression, and can even involve CPU registers. After creating a variable object, the frontend can invoke other variable object operations—for example to obtain or change the value of a variable object, or to change display format.

Variable objects have hierarchical tree structure. Any variable object that corresponds to a composite type, such as structure in C, has a number of child variable objects, for example corresponding to each element of a structure. A child variable object can itself have children, recursively. Recursion ends when we reach leaf variable objects, which always have built-in types. Child variable objects are created only by explicit request, so if a frontend is not interested in the children of a particular variable object, no child will be created.

For a leaf variable object it is possible to obtain its value as a string, or set the value from a string. String value can be also obtained for a non-leaf variable object, but it's generally a string that only indicates the type of the object, and does not list its contents. Assignment to a non-leaf variable object is not allowed.

A frontend does not need to read the values of all variable objects each time the program stops. Instead, MI provides an update command that lists all variable objects whose values has changed since the last update operation. This considerably reduces the amount of data that must be transferred to the frontend. As noted above, children variable objects are created on demand, and only leaf variable objects have a real value. As result, gdb will read target memory only for leaf variables that frontend has created.

The automatic update is not always desirable. For example, a frontend might want to keep a value of some expression for future reference, and never update it. For another example, fetching memory is relatively slow for embedded targets, so a frontend might want to disable automatic update for the variables that are either not visible on the screen, or “closed”. This is possible using so called “frozen variable objects”. Such variable objects are never implicitly updated.

The following is the complete set of GDB/MI operations defined to access this functionality:

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 No value for GDBN CLI:

 name="name",numchild="N",type="type"

The -var-delete Command

Synopsis

 -var-delete [ -c ] name

Deletes a previously created variable object and all of its children. With the ‘-c’ option, just deletes the 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 natural format is the default format choosen automatically based on the variable type (like decimal for an int, hex for pointers, etc.).

For a variable with children, the format is set only on the variable itself, and the children are not affected.

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

Return a list of the children of the specified variable object and create variable objects for them, if they do not already exist. With a single argument or if print-values has a value for of 0 or --no-values, print only the names of the variables; if print-values is 1 or --all-values, also print their values; and if it is 2 or --simple-values print the name and value for simple data types and just the name for arrays, structures and unions.

Example

(gdb)
 -var-list-children n
 ^done,numchild=n,children=[{name=name,
 numchild=n,type=type},(repeats N times)]
(gdb)
 -var-list-children --all-values n
 ^done,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 No value for GDBN CLI:

 type=typename

The -var-info-expression Command

Synopsis

 -var-info-expression name

Returns a string that is suitable for presenting this variable object in user interface. The string is generally not valid expression in the current language, and cannot be evaluated.

For example, if a is an array, and variable object A was created for a, then we'll get this output:

(gdb) -var-info-expression A.1
^done,lang="C",exp="1"

Here, the values of lang can be {"C" | "C++" | "Java"}.

Note that the output of the -var-list-children command also includes those expressions, so the -var-info-expression command is of limited use.

The -var-info-path-expression Command

Synopsis

 -var-info-path-expression name

Returns an expression that can be evaluated in the current context and will yield the same value that a variable object has. Compare this with the -var-info-expression command, which result can be used only for UI presentation. Typical use of the -var-info-path-expression command is creating a watchpoint from a variable object.

For example, suppose C is a C++ class, derived from class Base, and that the Base class has a member called m_size. Assume a variable c is has the type of C and a variable object C was created for variable c. Then, we'll get this output:

(gdb) -var-info-path-expression C.Base.public.m_size
^done,path_expr=((Base)c).m_size)

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. The format of the string can be changed using the -var-set-format command.

 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 [print-values] {name | "*"}

Reevaluate the expressions corresponding to the variable object name and all its direct and indirect children, and return the list of variable objects whose values have changed; name must be a root variable object. Here, “changed” means that the result of -var-evaluate-expression before and after the -var-update is different. If ‘*’ is used as the variable object names, all existing variable objects are updated, except for frozen ones (see -var-set-frozen). The option print-values determines whether both names and values, or just names are printed. The possible values of this options are the same as for -var-list-children (see -var-list-children). It is recommended to use the ‘--all-values’ option, to reduce the number of MI commands needed on each program stop.

Example

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

The field in_scope may take three values:

"true"

The variable object's current value is valid.

"false"

The variable object does not currently hold a valid value but it may hold one in the future if its associated expression comes back into scope.

"invalid"

The variable object no longer holds a valid value. This can occur when the executable file being debugged has changed, either through recompilation or by using the No value for GDBN file command. The front end should normally choose to delete these variable objects.

In the future new values may be added to this list so the front should be prepared for this possibility. See section GDB/MI Development and Front Ends.

The -var-set-frozen Command

Synopsis

 -var-set-frozen name flag

Set the frozenness flag on the variable object name. The flag parameter should be either ‘1’ to make the variable frozen or ‘0’ to make it unfrozen. If a variable object is frozen, then neither itself, nor any of its children, are implicitly updated by -var-update of a parent variable or by -var-update *. Only -var-update of the variable itself will update its value and values of its children. After a variable object is unfrozen, it is implicitly updated by all subsequent -var-update operations. Unfreezing a variable does not update it, only subsequent -var-update does.

Example

(gdb)
-var-set-frozen V 1
^done
(gdb)