mingw/info/gdb/GDB-MI-Variable-Objects.html

   1 <html lang="en">
   2 <head>
   3 <title>Debugging with GDB</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="Debugging with GDB">
   6 <meta name="generator" content="makeinfo 4.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="GDB%2fMI%20Variable%20Objects">GDB/MI Variable Objects</a>,
  13 Previous:<a rel="previous" accesskey="p" href="GDB-MI-Tracepoint-Commands.html#GDB%2fMI%20Tracepoint%20Commands">GDB/MI Tracepoint Commands</a>,
  14 Up:<a rel="up" accesskey="u" href="GDB-MI.html#GDB%2fMI">GDB/MI</a>
  15 <hr><br>
  16 </div>
  17
  18 <h3 class="section"><small>GDB/MI</small> Variable Objects</h3>
  19
  20 <h4 class="subheading">Motivation for Variable Objects in <small>GDB/MI</small></h4>
  21
  22    <p>For the implementation of a variable debugger window (locals, watched
  23 expressions, etc.), we are proposing the adaptation of the existing code
  24 used by <code>Insight</code>.
  25
  26    <p>The two main reasons for that are:
  27
  28      <ol type=1 start=1>
  29 <li>It has been proven in practice (it is already on its second generation).
  30
  31      <li>It will shorten development time (needless to say how important it is
  32 now).
  33         </ol>
  34
  35    <p>The original interface was designed to be used by Tcl code, so it was
  36 slightly changed so it could be used through <small>GDB/MI</small>.  This section
  37 describes the <small>GDB/MI</small> operations that will be available and gives some
  38 hints about their use.
  39
  40    <p><em>Note</em>: In addition to the set of operations described here, we
  41 expect the <small>GUI</small> implementation of a variable window to require, at
  42 least, the following operations:
  43
  44      <ul>
  45 <li><code>-gdb-show</code> <code>output-radix</code>
  46 <li><code>-stack-list-arguments</code>
  47 <li><code>-stack-list-locals</code>
  48 <li><code>-stack-select-frame</code>
  49 </ul>
  50
  51 <h4 class="subheading">Introduction to Variable Objects in <small>GDB/MI</small></h4>
  52
  53    <p>The basic idea behind variable objects is the creation of a named object
  54 to represent a variable, an expression, a memory location or even a CPU
  55 register.  For each object created, a set of operations is available for
  56 examining or changing its properties.
  57
  58    <p>Furthermore, complex data types, such as C structures, are represented
  59 in a tree format.  For instance, the <code>struct</code> type variable is the
  60 root and the children will represent the struct members.  If a child
  61 is itself of a complex type, it will also have children of its own.
  62 Appropriate language differences are handled for C, C<tt>++</tt> and Java.
  63
  64    <p>When returning the actual values of the objects, this facility allows
  65 for the individual selection of the display format used in the result
  66 creation.  It can be chosen among: binary, decimal, hexadecimal, octal
  67 and natural.  Natural refers to a default format automatically
  68 chosen based on the variable type (like decimal for an <code>int</code>, hex
  69 for pointers, etc.).
  70
  71    <p>The following is the complete set of <small>GDB/MI</small> operations defined to
  72 access this functionality:
  73
  74    <p><table><tr align="left"><td valign="top"><strong>Operation</strong>
  75 </td><td valign="top"><strong>Description</strong>
  76
  77 <br></td></tr><tr align="left"><td valign="top"><code>-var-create</code>
  78 </td><td valign="top">create a variable object
  79 <br></td></tr><tr align="left"><td valign="top"><code>-var-delete</code>
  80 </td><td valign="top">delete the variable object and its children
  81 <br></td></tr><tr align="left"><td valign="top"><code>-var-set-format</code>
  82 </td><td valign="top">set the display format of this variable
  83 <br></td></tr><tr align="left"><td valign="top"><code>-var-show-format</code>
  84 </td><td valign="top">show the display format of this variable
  85 <br></td></tr><tr align="left"><td valign="top"><code>-var-info-num-children</code>
  86 </td><td valign="top">tells how many children this object has
  87 <br></td></tr><tr align="left"><td valign="top"><code>-var-list-children</code>
  88 </td><td valign="top">return a list of the object's children
  89 <br></td></tr><tr align="left"><td valign="top"><code>-var-info-type</code>
  90 </td><td valign="top">show the type of this variable object
  91 <br></td></tr><tr align="left"><td valign="top"><code>-var-info-expression</code>
  92 </td><td valign="top">print what this variable object represents
  93 <br></td></tr><tr align="left"><td valign="top"><code>-var-show-attributes</code>
  94 </td><td valign="top">is this variable editable? does it exist here?
  95 <br></td></tr><tr align="left"><td valign="top"><code>-var-evaluate-expression</code>
  96 </td><td valign="top">get the value of this variable
  97 <br></td></tr><tr align="left"><td valign="top"><code>-var-assign</code>
  98 </td><td valign="top">set the value of this variable
  99 <br></td></tr><tr align="left"><td valign="top"><code>-var-update</code>
 100 </td><td valign="top">update the variable and its children
 101    <br></td></tr></table>
 102
 103    <p>In the next subsection we describe each operation in detail and suggest
 104 how it can be used.
 105
 106 <h4 class="subheading">Description And Use of Operations on Variable Objects</h4>
 107
 108 <h4 class="subheading">The <code>-var-create</code> Command</h4>
 109
 110 <h5 class="subsubheading">Synopsis</h5>
 111
 112 <pre class="example">      -var-create {<var>name</var> | "-"}
 113          {<var>frame-addr</var> | "*"} <var>expression</var>
 114      </pre>
 115
 116    <p>This operation creates a variable object, which allows the monitoring of
 117 a variable, the result of an expression, a memory cell or a CPU
 118 register.
 119
 120    <p>The <var>name</var> parameter is the string by which the object can be
 121 referenced.  It must be unique.  If <code>-</code> is specified, the varobj
 122 system will generate a string "varNNNNNN" automatically.  It will be
 123 unique provided that one does not specify <var>name</var> on that format.
 124 The command fails if a duplicate name is found.
 125
 126    <p>The frame under which the expression should be evaluated can be
 127 specified by <var>frame-addr</var>.  A <code>*</code> indicates that the current
 128 frame should be used.
 129
 130    <p><var>expression</var> is any expression valid on the current language set (must not
 131 begin with a <code>*</code>), or one of the following:
 132
 133      <ul>
 134 <li><code>*</code><var>addr</var><code></code>, where <var>addr</var> is the address of a memory cell
 135
 136      <li><code>*</code><var>addr</var><code>-</code><var>addr</var><code></code> -- a memory address range (TBD)
 137
 138      <li><code>$</code><var>regname</var><code></code> -- a CPU register name
 139 </ul>
 140
 141 <h5 class="subsubheading">Result</h5>
 142
 143    <p>This operation returns the name, number of children and the type of the
 144 object created.  Type is returned as a string as the ones generated by
 145 the GDB CLI:
 146
 147 <pre class="example">      name="<var>name</var>",numchild="N",type="<var>type</var>"
 148      </pre>
 149
 150 <h4 class="subheading">The <code>-var-delete</code> Command</h4>
 151
 152 <h5 class="subsubheading">Synopsis</h5>
 153
 154 <pre class="example">      -var-delete <var>name</var>
 155      </pre>
 156
 157    <p>Deletes a previously created variable object and all of its children.
 158
 159    <p>Returns an error if the object <var>name</var> is not found.
 160
 161 <h4 class="subheading">The <code>-var-set-format</code> Command</h4>
 162
 163 <h5 class="subsubheading">Synopsis</h5>
 164
 165 <pre class="example">      -var-set-format <var>name</var> <var>format-spec</var>
 166      </pre>
 167
 168    <p>Sets the output format for the value of the object <var>name</var> to be
 169 <var>format-spec</var>.
 170
 171    <p>The syntax for the <var>format-spec</var> is as follows:
 172
 173 <pre class="example">      <var>format-spec</var> ==&gt;
 174       {binary | decimal | hexadecimal | octal | natural}
 175      </pre>
 176
 177 <h4 class="subheading">The <code>-var-show-format</code> Command</h4>
 178
 179 <h5 class="subsubheading">Synopsis</h5>
 180
 181 <pre class="example">      -var-show-format <var>name</var>
 182      </pre>
 183
 184    <p>Returns the format used to display the value of the object <var>name</var>.
 185
 186 <pre class="example">      <var>format</var> ==&gt;
 187       <var>format-spec</var>
 188      </pre>
 189
 190 <h4 class="subheading">The <code>-var-info-num-children</code> Command</h4>
 191
 192 <h5 class="subsubheading">Synopsis</h5>
 193
 194 <pre class="example">      -var-info-num-children <var>name</var>
 195      </pre>
 196
 197    <p>Returns the number of children of a variable object <var>name</var>:
 198
 199 <pre class="example">      numchild=<var>n</var>
 200      </pre>
 201
 202 <h4 class="subheading">The <code>-var-list-children</code> Command</h4>
 203
 204 <h5 class="subsubheading">Synopsis</h5>
 205
 206 <pre class="example">      -var-list-children <var>name</var>
 207      </pre>
 208
 209    <p>Returns a list of the children of the specified variable object:
 210
 211 <pre class="example">      numchild=<var>n</var>,children={{name=<var>name</var>,
 212       numchild=<var>n</var>,type=<var>type</var>},(repeats N times)}
 213      </pre>
 214
 215 <h4 class="subheading">The <code>-var-info-type</code> Command</h4>
 216
 217 <h5 class="subsubheading">Synopsis</h5>
 218
 219 <pre class="example">      -var-info-type <var>name</var>
 220      </pre>
 221
 222    <p>Returns the type of the specified variable <var>name</var>.  The type is
 223 returned as a string in the same format as it is output by the
 224 GDB CLI:
 225
 226 <pre class="example">      type=<var>typename</var>
 227      </pre>
 228
 229 <h4 class="subheading">The <code>-var-info-expression</code> Command</h4>
 230
 231 <h5 class="subsubheading">Synopsis</h5>
 232
 233 <pre class="example">      -var-info-expression <var>name</var>
 234      </pre>
 235
 236    <p>Returns what is represented by the variable object <var>name</var>:
 237
 238 <pre class="example">      lang=<var>lang-spec</var>,exp=<var>expression</var>
 239      </pre>
 240
 241 <p>where <var>lang-spec</var> is <code>{"C" | "C++" | "Java"}</code>.
 242
 243 <h4 class="subheading">The <code>-var-show-attributes</code> Command</h4>
 244
 245 <h5 class="subsubheading">Synopsis</h5>
 246
 247 <pre class="example">      -var-show-attributes <var>name</var>
 248      </pre>
 249
 250    <p>List attributes of the specified variable object <var>name</var>:
 251
 252 <pre class="example">      status=<var>attr</var> [ ( ,<var>attr</var> )* ]
 253      </pre>
 254
 255 <p>where <var>attr</var> is <code>{ { editable | noneditable } | TBD }</code>.
 256
 257 <h4 class="subheading">The <code>-var-evaluate-expression</code> Command</h4>
 258
 259 <h5 class="subsubheading">Synopsis</h5>
 260
 261 <pre class="example">      -var-evaluate-expression <var>name</var>
 262      </pre>
 263
 264    <p>Evaluates the expression that is represented by the specified variable
 265 object and returns its value as a string in the current format specified
 266 for the object:
 267
 268 <pre class="example">      value=<var>value</var>
 269      </pre>
 270
 271 <h4 class="subheading">The <code>-var-assign</code> Command</h4>
 272
 273 <h5 class="subsubheading">Synopsis</h5>
 274
 275 <pre class="example">      -var-assign <var>name</var> <var>expression</var>
 276      </pre>
 277
 278    <p>Assigns the value of <var>expression</var> to the variable object specified
 279 by <var>name</var>.  The object must be <code>editable</code>.
 280
 281 <h4 class="subheading">The <code>-var-update</code> Command</h4>
 282
 283 <h5 class="subsubheading">Synopsis</h5>
 284
 285 <pre class="example">      -var-update {<var>name</var> | "*"}
 286      </pre>
 287
 288    <p>Update the value of the variable object <var>name</var> by evaluating its
 289 expression after fetching all the new values from memory or registers.
 290 A <code>*</code> causes all existing variable objects to be updated.
 291
 292    </body></html>
 293