mingw/info/gdb/Value-Annotations.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="Value%20Annotations">Value Annotations</a>,
  13 Next:<a rel="next" accesskey="n" href="Frame-Annotations.html#Frame%20Annotations">Frame Annotations</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Server-Prefix.html#Server%20Prefix">Server Prefix</a>,
  15 Up:<a rel="up" accesskey="u" href="Annotations.html#Annotations">Annotations</a>
  16 <hr><br>
  17 </div>
  18
  19 <h3 class="section">Values</h3>
  20
  21    <p>When a value is printed in various contexts, GDB uses
  22 annotations to delimit the value from the surrounding text.
  23
  24    <p>If a value is printed using <code>print</code> and added to the value history,
  25 the annotation looks like
  26
  27 <pre class="smallexample">     ^Z^Zvalue-history-begin <var>history-number</var> <var>value-flags</var>
  28      <var>history-string</var>
  29      ^Z^Zvalue-history-value
  30      <var>the-value</var>
  31      ^Z^Zvalue-history-end
  32      </pre>
  33
  34 <p>where <var>history-number</var> is the number it is getting in the value
  35 history, <var>history-string</var> is a string, such as <code>$5 = </code>, which
  36 introduces the value to the user, <var>the-value</var> is the output
  37 corresponding to the value itself, and <var>value-flags</var> is <code>*</code> for
  38 a value which can be dereferenced and <code>-</code> for a value which cannot.
  39
  40    <p>If the value is not added to the value history (it is an invalid float
  41 or it is printed with the <code>output</code> command), the annotation is similar:
  42
  43 <pre class="smallexample">     ^Z^Zvalue-begin <var>value-flags</var>
  44      <var>the-value</var>
  45      ^Z^Zvalue-end
  46      </pre>
  47
  48    <p>When GDB prints an argument to a function (for example, in the output
  49 from the <code>backtrace</code> command), it annotates it as follows:
  50
  51 <pre class="smallexample">     ^Z^Zarg-begin
  52      <var>argument-name</var>
  53      ^Z^Zarg-name-end
  54      <var>separator-string</var>
  55      ^Z^Zarg-value <var>value-flags</var>
  56      <var>the-value</var>
  57      ^Z^Zarg-end
  58      </pre>
  59
  60 <p>where <var>argument-name</var> is the name of the argument,
  61 <var>separator-string</var> is text which separates the name from the value
  62 for the user's benefit (such as <code>=</code>), and <var>value-flags</var> and
  63 <var>the-value</var> have the same meanings as in a
  64 <code>value-history-begin</code> annotation.
  65
  66    <p>When printing a structure, GDB annotates it as follows:
  67
  68 <pre class="smallexample">     ^Z^Zfield-begin <var>value-flags</var>
  69      <var>field-name</var>
  70      ^Z^Zfield-name-end
  71      <var>separator-string</var>
  72      ^Z^Zfield-value
  73      <var>the-value</var>
  74      ^Z^Zfield-end
  75      </pre>
  76
  77 <p>where <var>field-name</var> is the name of the field, <var>separator-string</var>
  78 is text which separates the name from the value for the user's benefit
  79 (such as <code>=</code>), and <var>value-flags</var> and <var>the-value</var> have the
  80 same meanings as in a <code>value-history-begin</code> annotation.
  81
  82    <p>When printing an array, GDB annotates it as follows:
  83
  84 <pre class="smallexample">     ^Z^Zarray-section-begin <var>array-index</var> <var>value-flags</var>
  85      </pre>
  86
  87 <p>where <var>array-index</var> is the index of the first element being
  88 annotated and <var>value-flags</var> has the same meaning as in a
  89 <code>value-history-begin</code> annotation.  This is followed by any number
  90 of elements, where is element can be either a single element:
  91
  92 <pre class="smallexample">     <code>,</code> <var>whitespace</var>         ; omitted for the first element
  93      <var>the-value</var>
  94      ^Z^Zelt
  95      </pre>
  96
  97    <p>or a repeated element
  98
  99 <pre class="smallexample">     <code>,</code> <var>whitespace</var>         ; omitted for the first element
 100      <var>the-value</var>
 101      ^Z^Zelt-rep <var>number-of-repititions</var>
 102      <var>repetition-string</var>
 103      ^Z^Zelt-rep-end
 104      </pre>
 105
 106    <p>In both cases, <var>the-value</var> is the output for the value of the
 107 element and <var>whitespace</var> can contain spaces, tabs, and newlines.  In
 108 the repeated case, <var>number-of-repititons</var> is the number of
 109 consecutive array elements which contain that value, and
 110 <var>repetition-string</var> is a string which is designed to convey to the
 111 user that repitition is being depicted.
 112
 113    <p>Once all the array elements have been output, the array annotation is
 114 ended with
 115
 116 <pre class="smallexample">     ^Z^Zarray-section-end
 117      </pre>
 118
 119    </body></html>
 120