<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
<html>
|
<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc.
|
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being "Free Software" and "Free Software Needs
|
Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
|
and with the Back-Cover Texts as in (a) below.
|
|
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
|
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
developing GNU and promoting software freedom." -->
|
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
|
<head>
|
<title>Debugging with GDB: GDB/MI Variable Objects</title>
|
|
<meta name="description" content="Debugging with GDB: GDB/MI Variable Objects">
|
<meta name="keywords" content="Debugging with GDB: GDB/MI Variable Objects">
|
<meta name="resource-type" content="document">
|
<meta name="distribution" content="global">
|
<meta name="Generator" content="makeinfo">
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
<link href="index.html#Top" rel="start" title="Top">
|
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
<link href="GDB_002fMI.html#GDB_002fMI" rel="up" title="GDB/MI">
|
<link href="GDB_002fMI-Data-Manipulation.html#GDB_002fMI-Data-Manipulation" rel="next" title="GDB/MI Data Manipulation">
|
<link href="GDB_002fMI-Stack-Manipulation.html#GDB_002fMI-Stack-Manipulation" rel="previous" title="GDB/MI Stack Manipulation">
|
<style type="text/css">
|
<!--
|
a.summary-letter {text-decoration: none}
|
blockquote.smallquotation {font-size: smaller}
|
div.display {margin-left: 3.2em}
|
div.example {margin-left: 3.2em}
|
div.indentedblock {margin-left: 3.2em}
|
div.lisp {margin-left: 3.2em}
|
div.smalldisplay {margin-left: 3.2em}
|
div.smallexample {margin-left: 3.2em}
|
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
|
div.smalllisp {margin-left: 3.2em}
|
kbd {font-style:oblique}
|
pre.display {font-family: inherit}
|
pre.format {font-family: inherit}
|
pre.menu-comment {font-family: serif}
|
pre.menu-preformatted {font-family: serif}
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
pre.smallexample {font-size: smaller}
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
pre.smalllisp {font-size: smaller}
|
span.nocodebreak {white-space:nowrap}
|
span.nolinebreak {white-space:nowrap}
|
span.roman {font-family:serif; font-weight:normal}
|
span.sansserif {font-family:sans-serif; font-weight:normal}
|
ul.no-bullet {list-style: none}
|
-->
|
</style>
|
|
|
</head>
|
|
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
|
<a name="GDB_002fMI-Variable-Objects"></a>
|
<div class="header">
|
<p>
|
Next: <a href="GDB_002fMI-Data-Manipulation.html#GDB_002fMI-Data-Manipulation" accesskey="n" rel="next">GDB/MI Data Manipulation</a>, Previous: <a href="GDB_002fMI-Stack-Manipulation.html#GDB_002fMI-Stack-Manipulation" accesskey="p" rel="previous">GDB/MI Stack Manipulation</a>, Up: <a href="GDB_002fMI.html#GDB_002fMI" accesskey="u" rel="up">GDB/MI</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
|
</div>
|
<hr>
|
<a name="GDB_002fMI-Variable-Objects-1"></a>
|
<h3 class="section">27.15 <small>GDB/MI</small> Variable Objects</h3>
|
|
|
<a name="Introduction-to-Variable-Objects"></a>
|
<h4 class="subheading">Introduction to Variable Objects</h4>
|
|
<a name="index-variable-objects-in-GDB_002fMI"></a>
|
|
<p>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.
|
</p>
|
<p>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.
|
</p>
|
<p>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.
|
</p>
|
<p>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.
|
</p>
|
<p>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.
|
</p>
|
<p>Variable objects can be either <em>fixed</em> or <em>floating</em>. For the
|
fixed variable object, the expression is parsed when the variable
|
object is created, including associating identifiers to specific
|
variables. The meaning of expression never changes. For a floating
|
variable object the values of variables whose names appear in the
|
expressions are re-evaluated every time in the context of the current
|
frame. Consider this example:
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample">void do_work(...)
|
{
|
struct work_state state;
|
|
if (...)
|
do_work(...);
|
}
|
</pre></div>
|
|
<p>If a fixed variable object for the <code>state</code> variable is created in
|
this function, and we enter the recursive call, the variable
|
object will report the value of <code>state</code> in the top-level
|
<code>do_work</code> invocation. On the other hand, a floating variable
|
object will report the value of <code>state</code> in the current frame.
|
</p>
|
<p>If an expression specified when creating a fixed variable object
|
refers to a local variable, the variable object becomes bound to the
|
thread and frame in which the variable object is created. When such
|
variable object is updated, <small>GDB</small> makes sure that the
|
thread/frame combination the variable object is bound to still exists,
|
and re-evaluates the variable object in context of that thread/frame.
|
</p>
|
<p>The following is the complete set of <small>GDB/MI</small> operations defined to
|
access this functionality:
|
</p>
|
<table>
|
<tr><td width="40%"><strong>Operation</strong></td><td width="60%"><strong>Description</strong></td></tr>
|
<tr><td width="40%"><code>-enable-pretty-printing</code></td><td width="60%">enable Python-based pretty-printing</td></tr>
|
<tr><td width="40%"><code>-var-create</code></td><td width="60%">create a variable object</td></tr>
|
<tr><td width="40%"><code>-var-delete</code></td><td width="60%">delete the variable object and/or its children</td></tr>
|
<tr><td width="40%"><code>-var-set-format</code></td><td width="60%">set the display format of this variable</td></tr>
|
<tr><td width="40%"><code>-var-show-format</code></td><td width="60%">show the display format of this variable</td></tr>
|
<tr><td width="40%"><code>-var-info-num-children</code></td><td width="60%">tells how many children this object has</td></tr>
|
<tr><td width="40%"><code>-var-list-children</code></td><td width="60%">return a list of the object’s children</td></tr>
|
<tr><td width="40%"><code>-var-info-type</code></td><td width="60%">show the type of this variable object</td></tr>
|
<tr><td width="40%"><code>-var-info-expression</code></td><td width="60%">print parent-relative expression that this variable object represents</td></tr>
|
<tr><td width="40%"><code>-var-info-path-expression</code></td><td width="60%">print full expression that this variable object represents</td></tr>
|
<tr><td width="40%"><code>-var-show-attributes</code></td><td width="60%">is this variable editable? does it exist here?</td></tr>
|
<tr><td width="40%"><code>-var-evaluate-expression</code></td><td width="60%">get the value of this variable</td></tr>
|
<tr><td width="40%"><code>-var-assign</code></td><td width="60%">set the value of this variable</td></tr>
|
<tr><td width="40%"><code>-var-update</code></td><td width="60%">update the variable and its children</td></tr>
|
<tr><td width="40%"><code>-var-set-frozen</code></td><td width="60%">set frozenness attribute</td></tr>
|
<tr><td width="40%"><code>-var-set-update-range</code></td><td width="60%">set range of children to display on update</td></tr>
|
</table>
|
|
<p>In the next subsection we describe each operation in detail and suggest
|
how it can be used.
|
</p>
|
<a name="Description-and-Use-of-Operations-on-Variable-Objects"></a>
|
<h4 class="subheading">Description and Use of Operations on Variable Objects</h4>
|
|
<a name="The-_002denable_002dpretty_002dprinting-Command"></a>
|
<h4 class="subheading">The <code>-enable-pretty-printing</code> Command</h4>
|
<a name="index-_002denable_002dpretty_002dprinting"></a>
|
|
<div class="smallexample">
|
<pre class="smallexample">-enable-pretty-printing
|
</pre></div>
|
|
<p><small>GDB</small> allows Python-based visualizers to affect the output of the
|
MI variable object commands. However, because there was no way to
|
implement this in a fully backward-compatible way, a front end must
|
request that this functionality be enabled.
|
</p>
|
<p>Once enabled, this feature cannot be disabled.
|
</p>
|
<p>Note that if Python support has not been compiled into <small>GDB</small>,
|
this command will still succeed (and do nothing).
|
</p>
|
<p>This feature is currently (as of <small>GDB</small> 7.0) experimental, and
|
may work differently in future versions of <small>GDB</small>.
|
</p>
|
<a name="The-_002dvar_002dcreate-Command"></a>
|
<h4 class="subheading">The <code>-var-create</code> Command</h4>
|
<a name="index-_002dvar_002dcreate"></a>
|
|
<a name="Synopsis-48"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-create {<var>name</var> | "-"}
|
{<var>frame-addr</var> | "*" | "@"} <var>expression</var>
|
</pre></div>
|
|
<p>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.
|
</p>
|
<p>The <var>name</var> parameter is the string by which the object can be
|
referenced. It must be unique. If ‘<samp>-</samp>’ is specified, the varobj
|
system will generate a string “varNNNNNN” automatically. It will be
|
unique provided that one does not specify <var>name</var> of that format.
|
The command fails if a duplicate name is found.
|
</p>
|
<p>The frame under which the expression should be evaluated can be
|
specified by <var>frame-addr</var>. A ‘<samp>*</samp>’ indicates that the current
|
frame should be used. A ‘<samp>@</samp>’ indicates that a floating variable
|
object must be created.
|
</p>
|
<p><var>expression</var> is any expression valid on the current language set (must not
|
begin with a ‘<samp>*</samp>’), or one of the following:
|
</p>
|
<ul>
|
<li> ‘<samp>*<var>addr</var></samp>’, where <var>addr</var> is the address of a memory cell
|
|
</li><li> ‘<samp>*<var>addr</var>-<var>addr</var></samp>’ — a memory address range (TBD)
|
|
</li><li> ‘<samp>$<var>regname</var></samp>’ — a CPU register name
|
</li></ul>
|
|
<a name="index-dynamic-varobj"></a>
|
<p>A varobj’s contents may be provided by a Python-based pretty-printer. In this
|
case the varobj is known as a <em>dynamic varobj</em>. Dynamic varobjs
|
have slightly different semantics in some cases. If the
|
<code>-enable-pretty-printing</code> command is not sent, then <small>GDB</small>
|
will never create a dynamic varobj. This ensures backward
|
compatibility for existing clients.
|
</p>
|
<a name="Result-5"></a>
|
<h4 class="subsubheading">Result</h4>
|
|
<p>This operation returns attributes of the newly-created varobj. These
|
are:
|
</p>
|
<dl compact="compact">
|
<dt>‘<samp>name</samp>’</dt>
|
<dd><p>The name of the varobj.
|
</p>
|
</dd>
|
<dt>‘<samp>numchild</samp>’</dt>
|
<dd><p>The number of children of the varobj. This number is not necessarily
|
reliable for a dynamic varobj. Instead, you must examine the
|
‘<samp>has_more</samp>’ attribute.
|
</p>
|
</dd>
|
<dt>‘<samp>value</samp>’</dt>
|
<dd><p>The varobj’s scalar value. For a varobj whose type is some sort of
|
aggregate (e.g., a <code>struct</code>), or for a dynamic varobj, this value
|
will not be interesting.
|
</p>
|
</dd>
|
<dt>‘<samp>type</samp>’</dt>
|
<dd><p>The varobj’s type. This is a string representation of the type, as
|
would be printed by the <small>GDB</small> CLI. If ‘<samp>print object</samp>’
|
(see <a href="Print-Settings.html#Print-Settings">set print object</a>) is set to <code>on</code>, the
|
<em>actual</em> (derived) type of the object is shown rather than the
|
<em>declared</em> one.
|
</p>
|
</dd>
|
<dt>‘<samp>thread-id</samp>’</dt>
|
<dd><p>If a variable object is bound to a specific thread, then this is the
|
thread’s global identifier.
|
</p>
|
</dd>
|
<dt>‘<samp>has_more</samp>’</dt>
|
<dd><p>For a dynamic varobj, this indicates whether there appear to be any
|
children available. For a non-dynamic varobj, this will be 0.
|
</p>
|
</dd>
|
<dt>‘<samp>dynamic</samp>’</dt>
|
<dd><p>This attribute will be present and have the value ‘<samp>1</samp>’ if the
|
varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
|
then this attribute will not be present.
|
</p>
|
</dd>
|
<dt>‘<samp>displayhint</samp>’</dt>
|
<dd><p>A dynamic varobj can supply a display hint to the front end. The
|
value comes directly from the Python pretty-printer object’s
|
<code>display_hint</code> method. See <a href="Pretty-Printing-API.html#Pretty-Printing-API">Pretty Printing API</a>.
|
</p></dd>
|
</dl>
|
|
<p>Typical output will look like this:
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample"> name="<var>name</var>",numchild="<var>N</var>",type="<var>type</var>",thread-id="<var>M</var>",
|
has_more="<var>has_more</var>"
|
</pre></div>
|
|
|
<a name="The-_002dvar_002ddelete-Command"></a>
|
<h4 class="subheading">The <code>-var-delete</code> Command</h4>
|
<a name="index-_002dvar_002ddelete"></a>
|
|
<a name="Synopsis-49"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-delete [ -c ] <var>name</var>
|
</pre></div>
|
|
<p>Deletes a previously created variable object and all of its children.
|
With the ‘<samp>-c</samp>’ option, just deletes the children.
|
</p>
|
<p>Returns an error if the object <var>name</var> is not found.
|
</p>
|
|
<a name="The-_002dvar_002dset_002dformat-Command"></a>
|
<h4 class="subheading">The <code>-var-set-format</code> Command</h4>
|
<a name="index-_002dvar_002dset_002dformat"></a>
|
|
<a name="Synopsis-50"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-set-format <var>name</var> <var>format-spec</var>
|
</pre></div>
|
|
<p>Sets the output format for the value of the object <var>name</var> to be
|
<var>format-spec</var>.
|
</p>
|
<a name="g_t_002dvar_002dset_002dformat"></a><p>The syntax for the <var>format-spec</var> is as follows:
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample"> <var>format-spec</var> →
|
{binary | decimal | hexadecimal | octal | natural | zero-hexadecimal}
|
</pre></div>
|
|
<p>The natural format is the default format choosen automatically
|
based on the variable type (like decimal for an <code>int</code>, hex
|
for pointers, etc.).
|
</p>
|
<p>The zero-hexadecimal format has a representation similar to hexadecimal
|
but with padding zeroes to the left of the value. For example, a 32-bit
|
hexadecimal value of 0x1234 would be represented as 0x00001234 in the
|
zero-hexadecimal format.
|
</p>
|
<p>For a variable with children, the format is set only on the
|
variable itself, and the children are not affected.
|
</p>
|
<a name="The-_002dvar_002dshow_002dformat-Command"></a>
|
<h4 class="subheading">The <code>-var-show-format</code> Command</h4>
|
<a name="index-_002dvar_002dshow_002dformat"></a>
|
|
<a name="Synopsis-51"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-show-format <var>name</var>
|
</pre></div>
|
|
<p>Returns the format used to display the value of the object <var>name</var>.
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample"> <var>format</var> →
|
<var>format-spec</var>
|
</pre></div>
|
|
|
<a name="The-_002dvar_002dinfo_002dnum_002dchildren-Command"></a>
|
<h4 class="subheading">The <code>-var-info-num-children</code> Command</h4>
|
<a name="index-_002dvar_002dinfo_002dnum_002dchildren"></a>
|
|
<a name="Synopsis-52"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-info-num-children <var>name</var>
|
</pre></div>
|
|
<p>Returns the number of children of a variable object <var>name</var>:
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample"> numchild=<var>n</var>
|
</pre></div>
|
|
<p>Note that this number is not completely reliable for a dynamic varobj.
|
It will return the current number of children, but more children may
|
be available.
|
</p>
|
|
<a name="The-_002dvar_002dlist_002dchildren-Command"></a>
|
<h4 class="subheading">The <code>-var-list-children</code> Command</h4>
|
<a name="index-_002dvar_002dlist_002dchildren"></a>
|
|
<a name="Synopsis-53"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-list-children [<var>print-values</var>] <var>name</var> [<var>from</var> <var>to</var>]
|
</pre></div>
|
<a name="g_t_002dvar_002dlist_002dchildren"></a>
|
<p>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 <var>print-values</var> has a value of 0 or
|
<code>--no-values</code>, print only the names of the variables; if
|
<var>print-values</var> is 1 or <code>--all-values</code>, also print their
|
values; and if it is 2 or <code>--simple-values</code> print the name and
|
value for simple data types and just the name for arrays, structures
|
and unions.
|
</p>
|
<p><var>from</var> and <var>to</var>, if specified, indicate the range of children
|
to report. If <var>from</var> or <var>to</var> is less than zero, the range is
|
reset and all children will be reported. Otherwise, children starting
|
at <var>from</var> (zero-based) and up to and excluding <var>to</var> will be
|
reported.
|
</p>
|
<p>If a child range is requested, it will only affect the current call to
|
<code>-var-list-children</code>, but not future calls to <code>-var-update</code>.
|
For this, you must instead use <code>-var-set-update-range</code>. The
|
intent of this approach is to enable a front end to implement any
|
update approach it likes; for example, scrolling a view may cause the
|
front end to request more children with <code>-var-list-children</code>, and
|
then the front end could call <code>-var-set-update-range</code> with a
|
different range to ensure that future updates are restricted to just
|
the visible items.
|
</p>
|
<p>For each child the following results are returned:
|
</p>
|
<dl compact="compact">
|
<dt><var>name</var></dt>
|
<dd><p>Name of the variable object created for this child.
|
</p>
|
</dd>
|
<dt><var>exp</var></dt>
|
<dd><p>The expression to be shown to the user by the front end to designate this child.
|
For example this may be the name of a structure member.
|
</p>
|
<p>For a dynamic varobj, this value cannot be used to form an
|
expression. There is no way to do this at all with a dynamic varobj.
|
</p>
|
<p>For C/C<tt>++</tt> structures there are several pseudo children returned to
|
designate access qualifiers. For these pseudo children <var>exp</var> is
|
‘<samp>public</samp>’, ‘<samp>private</samp>’, or ‘<samp>protected</samp>’. In this case the
|
type and value are not present.
|
</p>
|
<p>A dynamic varobj will not report the access qualifying
|
pseudo-children, regardless of the language. This information is not
|
available at all with a dynamic varobj.
|
</p>
|
</dd>
|
<dt><var>numchild</var></dt>
|
<dd><p>Number of children this child has. For a dynamic varobj, this will be
|
0.
|
</p>
|
</dd>
|
<dt><var>type</var></dt>
|
<dd><p>The type of the child. If ‘<samp>print object</samp>’
|
(see <a href="Print-Settings.html#Print-Settings">set print object</a>) is set to <code>on</code>, the
|
<em>actual</em> (derived) type of the object is shown rather than the
|
<em>declared</em> one.
|
</p>
|
</dd>
|
<dt><var>value</var></dt>
|
<dd><p>If values were requested, this is the value.
|
</p>
|
</dd>
|
<dt><var>thread-id</var></dt>
|
<dd><p>If this variable object is associated with a thread, this is the
|
thread’s global thread id. Otherwise this result is not present.
|
</p>
|
</dd>
|
<dt><var>frozen</var></dt>
|
<dd><p>If the variable object is frozen, this variable will be present with a value of 1.
|
</p>
|
</dd>
|
<dt><var>displayhint</var></dt>
|
<dd><p>A dynamic varobj can supply a display hint to the front end. The
|
value comes directly from the Python pretty-printer object’s
|
<code>display_hint</code> method. See <a href="Pretty-Printing-API.html#Pretty-Printing-API">Pretty Printing API</a>.
|
</p>
|
</dd>
|
<dt><var>dynamic</var></dt>
|
<dd><p>This attribute will be present and have the value ‘<samp>1</samp>’ if the
|
varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
|
then this attribute will not be present.
|
</p>
|
</dd>
|
</dl>
|
|
<p>The result may have its own attributes:
|
</p>
|
<dl compact="compact">
|
<dt>‘<samp>displayhint</samp>’</dt>
|
<dd><p>A dynamic varobj can supply a display hint to the front end. The
|
value comes directly from the Python pretty-printer object’s
|
<code>display_hint</code> method. See <a href="Pretty-Printing-API.html#Pretty-Printing-API">Pretty Printing API</a>.
|
</p>
|
</dd>
|
<dt>‘<samp>has_more</samp>’</dt>
|
<dd><p>This is an integer attribute which is nonzero if there are children
|
remaining after the end of the selected range.
|
</p></dd>
|
</dl>
|
|
<a name="Example-46"></a>
|
<h4 class="subsubheading">Example</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample">(gdb)
|
-var-list-children n
|
^done,numchild=<var>n</var>,children=[child={name=<var>name</var>,exp=<var>exp</var>,
|
numchild=<var>n</var>,type=<var>type</var>},<span class="roman">(repeats N times)</span>]
|
(gdb)
|
-var-list-children --all-values n
|
^done,numchild=<var>n</var>,children=[child={name=<var>name</var>,exp=<var>exp</var>,
|
numchild=<var>n</var>,value=<var>value</var>,type=<var>type</var>},<span class="roman">(repeats N times)</span>]
|
</pre></div>
|
|
|
<a name="The-_002dvar_002dinfo_002dtype-Command"></a>
|
<h4 class="subheading">The <code>-var-info-type</code> Command</h4>
|
<a name="index-_002dvar_002dinfo_002dtype"></a>
|
|
<a name="Synopsis-54"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-info-type <var>name</var>
|
</pre></div>
|
|
<p>Returns the type of the specified variable <var>name</var>. The type is
|
returned as a string in the same format as it is output by the
|
<small>GDB</small> CLI:
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample"> type=<var>typename</var>
|
</pre></div>
|
|
|
<a name="The-_002dvar_002dinfo_002dexpression-Command"></a>
|
<h4 class="subheading">The <code>-var-info-expression</code> Command</h4>
|
<a name="index-_002dvar_002dinfo_002dexpression"></a>
|
|
<a name="Synopsis-55"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-info-expression <var>name</var>
|
</pre></div>
|
|
<p>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.
|
</p>
|
<p>For example, if <code>a</code> is an array, and variable object
|
<code>A</code> was created for <code>a</code>, then we’ll get this output:
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample">(gdb) -var-info-expression A.1
|
^done,lang="C",exp="1"
|
</pre></div>
|
|
<p>Here, the value of <code>lang</code> is the language name, which can be
|
found in <a href="Supported-Languages.html#Supported-Languages">Supported Languages</a>.
|
</p>
|
<p>Note that the output of the <code>-var-list-children</code> command also
|
includes those expressions, so the <code>-var-info-expression</code> command
|
is of limited use.
|
</p>
|
<a name="The-_002dvar_002dinfo_002dpath_002dexpression-Command"></a>
|
<h4 class="subheading">The <code>-var-info-path-expression</code> Command</h4>
|
<a name="index-_002dvar_002dinfo_002dpath_002dexpression"></a>
|
|
<a name="Synopsis-56"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-info-path-expression <var>name</var>
|
</pre></div>
|
|
<p>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 <code>-var-info-expression</code> command, which
|
result can be used only for UI presentation. Typical use of
|
the <code>-var-info-path-expression</code> command is creating a
|
watchpoint from a variable object.
|
</p>
|
<p>This command is currently not valid for children of a dynamic varobj,
|
and will give an error when invoked on one.
|
</p>
|
<p>For example, suppose <code>C</code> is a C<tt>++</tt> class, derived from class
|
<code>Base</code>, and that the <code>Base</code> class has a member called
|
<code>m_size</code>. Assume a variable <code>c</code> is has the type of
|
<code>C</code> and a variable object <code>C</code> was created for variable
|
<code>c</code>. Then, we’ll get this output:
|
</p><div class="smallexample">
|
<pre class="smallexample">(gdb) -var-info-path-expression C.Base.public.m_size
|
^done,path_expr=((Base)c).m_size)
|
</pre></div>
|
|
<a name="The-_002dvar_002dshow_002dattributes-Command"></a>
|
<h4 class="subheading">The <code>-var-show-attributes</code> Command</h4>
|
<a name="index-_002dvar_002dshow_002dattributes"></a>
|
|
<a name="Synopsis-57"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-show-attributes <var>name</var>
|
</pre></div>
|
|
<p>List attributes of the specified variable object <var>name</var>:
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample"> status=<var>attr</var> [ ( ,<var>attr</var> )* ]
|
</pre></div>
|
|
<p>where <var>attr</var> is <code>{ { editable | noneditable } | TBD }</code>.
|
</p>
|
<a name="The-_002dvar_002devaluate_002dexpression-Command"></a>
|
<h4 class="subheading">The <code>-var-evaluate-expression</code> Command</h4>
|
<a name="index-_002dvar_002devaluate_002dexpression"></a>
|
|
<a name="Synopsis-58"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-evaluate-expression [-f <var>format-spec</var>] <var>name</var>
|
</pre></div>
|
|
<p>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 specified with the ‘<samp>-f</samp>’ option. The possible values of
|
this option are the same as for <code>-var-set-format</code>
|
(see <a href="#g_t_002dvar_002dset_002dformat">-var-set-format</a>). If the ‘<samp>-f</samp>’ option is not specified,
|
the current display format will be used. The current display format
|
can be changed using the <code>-var-set-format</code> command.
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample"> value=<var>value</var>
|
</pre></div>
|
|
<p>Note that one must invoke <code>-var-list-children</code> for a variable
|
before the value of a child variable can be evaluated.
|
</p>
|
<a name="The-_002dvar_002dassign-Command"></a>
|
<h4 class="subheading">The <code>-var-assign</code> Command</h4>
|
<a name="index-_002dvar_002dassign"></a>
|
|
<a name="Synopsis-59"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-assign <var>name</var> <var>expression</var>
|
</pre></div>
|
|
<p>Assigns the value of <var>expression</var> to the variable object specified
|
by <var>name</var>. The object must be ‘<samp>editable</samp>’. If the variable’s
|
value is altered by the assign, the variable will show up in any
|
subsequent <code>-var-update</code> list.
|
</p>
|
<a name="Example-47"></a>
|
<h4 class="subsubheading">Example</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample">(gdb)
|
-var-assign var1 3
|
^done,value="3"
|
(gdb)
|
-var-update *
|
^done,changelist=[{name="var1",in_scope="true",type_changed="false"}]
|
(gdb)
|
</pre></div>
|
|
<a name="The-_002dvar_002dupdate-Command"></a>
|
<h4 class="subheading">The <code>-var-update</code> Command</h4>
|
<a name="index-_002dvar_002dupdate"></a>
|
|
<a name="Synopsis-60"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-update [<var>print-values</var>] {<var>name</var> | "*"}
|
</pre></div>
|
|
<p>Reevaluate the expressions corresponding to the variable object
|
<var>name</var> and all its direct and indirect children, and return the
|
list of variable objects whose values have changed; <var>name</var> must
|
be a root variable object. Here, “changed” means that the result of
|
<code>-var-evaluate-expression</code> before and after the
|
<code>-var-update</code> is different. If ‘<samp>*</samp>’ is used as the variable
|
object names, all existing variable objects are updated, except
|
for frozen ones (see <a href="#g_t_002dvar_002dset_002dfrozen">-var-set-frozen</a>). The option
|
<var>print-values</var> determines whether both names and values, or just
|
names are printed. The possible values of this option are the same
|
as for <code>-var-list-children</code> (see <a href="#g_t_002dvar_002dlist_002dchildren">-var-list-children</a>). It is
|
recommended to use the ‘<samp>--all-values</samp>’ option, to reduce the
|
number of MI commands needed on each program stop.
|
</p>
|
<p>With the ‘<samp>*</samp>’ parameter, if a variable object is bound to a
|
currently running thread, it will not be updated, without any
|
diagnostic.
|
</p>
|
<p>If <code>-var-set-update-range</code> was previously used on a varobj, then
|
only the selected range of children will be reported.
|
</p>
|
<p><code>-var-update</code> reports all the changed varobjs in a tuple named
|
‘<samp>changelist</samp>’.
|
</p>
|
<p>Each item in the change list is itself a tuple holding:
|
</p>
|
<dl compact="compact">
|
<dt>‘<samp>name</samp>’</dt>
|
<dd><p>The name of the varobj.
|
</p>
|
</dd>
|
<dt>‘<samp>value</samp>’</dt>
|
<dd><p>If values were requested for this update, then this field will be
|
present and will hold the value of the varobj.
|
</p>
|
</dd>
|
<dt>‘<samp>in_scope</samp>’</dt>
|
<dd><a name="g_t_002dvar_002dupdate"></a><p>This field is a string which may take one of three values:
|
</p>
|
<dl compact="compact">
|
<dt><code>"true"</code></dt>
|
<dd><p>The variable object’s current value is valid.
|
</p>
|
</dd>
|
<dt><code>"false"</code></dt>
|
<dd><p>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.
|
</p>
|
</dd>
|
<dt><code>"invalid"</code></dt>
|
<dd><p>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 <small>GDB</small> <code>file</code>
|
command. The front end should normally choose to delete these variable
|
objects.
|
</p></dd>
|
</dl>
|
|
<p>In the future new values may be added to this list so the front should
|
be prepared for this possibility. See <a href="GDB_002fMI-Development-and-Front-Ends.html#GDB_002fMI-Development-and-Front-Ends"><small>GDB/MI</small> Development and Front Ends</a>.
|
</p>
|
</dd>
|
<dt>‘<samp>type_changed</samp>’</dt>
|
<dd><p>This is only present if the varobj is still valid. If the type
|
changed, then this will be the string ‘<samp>true</samp>’; otherwise it will
|
be ‘<samp>false</samp>’.
|
</p>
|
<p>When a varobj’s type changes, its children are also likely to have
|
become incorrect. Therefore, the varobj’s children are automatically
|
deleted when this attribute is ‘<samp>true</samp>’. Also, the varobj’s update
|
range, when set using the <code>-var-set-update-range</code> command, is
|
unset.
|
</p>
|
</dd>
|
<dt>‘<samp>new_type</samp>’</dt>
|
<dd><p>If the varobj’s type changed, then this field will be present and will
|
hold the new type.
|
</p>
|
</dd>
|
<dt>‘<samp>new_num_children</samp>’</dt>
|
<dd><p>For a dynamic varobj, if the number of children changed, or if the
|
type changed, this will be the new number of children.
|
</p>
|
<p>The ‘<samp>numchild</samp>’ field in other varobj responses is generally not
|
valid for a dynamic varobj – it will show the number of children that
|
<small>GDB</small> knows about, but because dynamic varobjs lazily
|
instantiate their children, this will not reflect the number of
|
children which may be available.
|
</p>
|
<p>The ‘<samp>new_num_children</samp>’ attribute only reports changes to the
|
number of children known by <small>GDB</small>. This is the only way to
|
detect whether an update has removed children (which necessarily can
|
only happen at the end of the update range).
|
</p>
|
</dd>
|
<dt>‘<samp>displayhint</samp>’</dt>
|
<dd><p>The display hint, if any.
|
</p>
|
</dd>
|
<dt>‘<samp>has_more</samp>’</dt>
|
<dd><p>This is an integer value, which will be 1 if there are more children
|
available outside the varobj’s update range.
|
</p>
|
</dd>
|
<dt>‘<samp>dynamic</samp>’</dt>
|
<dd><p>This attribute will be present and have the value ‘<samp>1</samp>’ if the
|
varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
|
then this attribute will not be present.
|
</p>
|
</dd>
|
<dt>‘<samp>new_children</samp>’</dt>
|
<dd><p>If new children were added to a dynamic varobj within the selected
|
update range (as set by <code>-var-set-update-range</code>), then they will
|
be listed in this attribute.
|
</p></dd>
|
</dl>
|
|
<a name="Example-48"></a>
|
<h4 class="subsubheading">Example</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample">(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)
|
</pre></div>
|
|
<a name="The-_002dvar_002dset_002dfrozen-Command"></a>
|
<h4 class="subheading">The <code>-var-set-frozen</code> Command</h4>
|
<a name="index-_002dvar_002dset_002dfrozen"></a>
|
<a name="g_t_002dvar_002dset_002dfrozen"></a>
|
<a name="Synopsis-61"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-set-frozen <var>name</var> <var>flag</var>
|
</pre></div>
|
|
<p>Set the frozenness flag on the variable object <var>name</var>. The
|
<var>flag</var> parameter should be either ‘<samp>1</samp>’ to make the variable
|
frozen or ‘<samp>0</samp>’ to make it unfrozen. If a variable object is
|
frozen, then neither itself, nor any of its children, are
|
implicitly updated by <code>-var-update</code> of
|
a parent variable or by <code>-var-update *</code>. Only
|
<code>-var-update</code> 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 <code>-var-update</code> operations.
|
Unfreezing a variable does not update it, only subsequent
|
<code>-var-update</code> does.
|
</p>
|
<a name="Example-49"></a>
|
<h4 class="subsubheading">Example</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample">(gdb)
|
-var-set-frozen V 1
|
^done
|
(gdb)
|
</pre></div>
|
|
<a name="The-_002dvar_002dset_002dupdate_002drange-command"></a>
|
<h4 class="subheading">The <code>-var-set-update-range</code> command</h4>
|
<a name="index-_002dvar_002dset_002dupdate_002drange"></a>
|
<a name="g_t_002dvar_002dset_002dupdate_002drange"></a>
|
<a name="Synopsis-62"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-set-update-range <var>name</var> <var>from</var> <var>to</var>
|
</pre></div>
|
|
<p>Set the range of children to be returned by future invocations of
|
<code>-var-update</code>.
|
</p>
|
<p><var>from</var> and <var>to</var> indicate the range of children to report. If
|
<var>from</var> or <var>to</var> is less than zero, the range is reset and all
|
children will be reported. Otherwise, children starting at <var>from</var>
|
(zero-based) and up to and excluding <var>to</var> will be reported.
|
</p>
|
<a name="Example-50"></a>
|
<h4 class="subsubheading">Example</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample">(gdb)
|
-var-set-update-range V 1 2
|
^done
|
</pre></div>
|
|
<a name="The-_002dvar_002dset_002dvisualizer-Command"></a>
|
<h4 class="subheading">The <code>-var-set-visualizer</code> Command</h4>
|
<a name="index-_002dvar_002dset_002dvisualizer"></a>
|
<a name="g_t_002dvar_002dset_002dvisualizer"></a>
|
<a name="Synopsis-63"></a>
|
<h4 class="subsubheading">Synopsis</h4>
|
|
<div class="smallexample">
|
<pre class="smallexample"> -var-set-visualizer <var>name</var> <var>visualizer</var>
|
</pre></div>
|
|
<p>Set a visualizer for the variable object <var>name</var>.
|
</p>
|
<p><var>visualizer</var> is the visualizer to use. The special value
|
‘<samp>None</samp>’ means to disable any visualizer in use.
|
</p>
|
<p>If not ‘<samp>None</samp>’, <var>visualizer</var> must be a Python expression.
|
This expression must evaluate to a callable object which accepts a
|
single argument. <small>GDB</small> will call this object with the value of
|
the varobj <var>name</var> as an argument (this is done so that the same
|
Python pretty-printing code can be used for both the CLI and MI).
|
When called, this object must return an object which conforms to the
|
pretty-printing interface (see <a href="Pretty-Printing-API.html#Pretty-Printing-API">Pretty Printing API</a>).
|
</p>
|
<p>The pre-defined function <code>gdb.default_visualizer</code> may be used to
|
select a visualizer by following the built-in process
|
(see <a href="Selecting-Pretty_002dPrinters.html#Selecting-Pretty_002dPrinters">Selecting Pretty-Printers</a>). This is done automatically when
|
a varobj is created, and so ordinarily is not needed.
|
</p>
|
<p>This feature is only available if Python support is enabled. The MI
|
command <code>-list-features</code> (see <a href="GDB_002fMI-Support-Commands.html#GDB_002fMI-Support-Commands">GDB/MI Support Commands</a>)
|
can be used to check this.
|
</p>
|
<a name="Example-51"></a>
|
<h4 class="subsubheading">Example</h4>
|
|
<p>Resetting the visualizer:
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample">(gdb)
|
-var-set-visualizer V None
|
^done
|
</pre></div>
|
|
<p>Reselecting the default (type-based) visualizer:
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample">(gdb)
|
-var-set-visualizer V gdb.default_visualizer
|
^done
|
</pre></div>
|
|
<p>Suppose <code>SomeClass</code> is a visualizer class. A lambda expression
|
can be used to instantiate this class for a varobj:
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample">(gdb)
|
-var-set-visualizer V "lambda val: SomeClass()"
|
^done
|
</pre></div>
|
|
<hr>
|
<div class="header">
|
<p>
|
Next: <a href="GDB_002fMI-Data-Manipulation.html#GDB_002fMI-Data-Manipulation" accesskey="n" rel="next">GDB/MI Data Manipulation</a>, Previous: <a href="GDB_002fMI-Stack-Manipulation.html#GDB_002fMI-Stack-Manipulation" accesskey="p" rel="previous">GDB/MI Stack Manipulation</a>, Up: <a href="GDB_002fMI.html#GDB_002fMI" accesskey="u" rel="up">GDB/MI</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
|
</div>
|
|
|
|
</body>
|
</html>
|
