annotate: Value Annotations
5 Values
********
_Value Annotations have been removed. GDB/MI instead provides Variable
Objects._
When a value is printed in various contexts, GDB uses annotations to
delimit the value from the surrounding text.
If a value is printed using 'print' and added to the value history,
the annotation looks like
^Z^Zvalue-history-begin HISTORY-NUMBER VALUE-FLAGS
HISTORY-STRING
^Z^Zvalue-history-value
THE-VALUE
^Z^Zvalue-history-end
where HISTORY-NUMBER is the number it is getting in the value history,
HISTORY-STRING is a string, such as '$5 = ', which introduces the value
to the user, THE-VALUE is the output corresponding to the value itself,
and VALUE-FLAGS is '*' for a value which can be dereferenced and '-' for
a value which cannot.
If the value is not added to the value history (it is an invalid
float or it is printed with the 'output' command), the annotation is
similar:
^Z^Zvalue-begin VALUE-FLAGS
THE-VALUE
^Z^Zvalue-end
When GDB prints an argument to a function (for example, in the output
from the 'backtrace' command), it annotates it as follows:
^Z^Zarg-begin
ARGUMENT-NAME
^Z^Zarg-name-end
SEPARATOR-STRING
^Z^Zarg-value VALUE-FLAGS
THE-VALUE
^Z^Zarg-end
where ARGUMENT-NAME is the name of the argument, SEPARATOR-STRING is
text which separates the name from the value for the user's benefit
(such as '='), and VALUE-FLAGS and THE-VALUE have the same meanings as
in a 'value-history-begin' annotation.
When printing a structure, GDB annotates it as follows:
^Z^Zfield-begin VALUE-FLAGS
FIELD-NAME
^Z^Zfield-name-end
SEPARATOR-STRING
^Z^Zfield-value
THE-VALUE
^Z^Zfield-end
where FIELD-NAME is the name of the field, SEPARATOR-STRING is text
which separates the name from the value for the user's benefit (such as
'='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a
'value-history-begin' annotation.
When printing an array, GDB annotates it as follows:
^Z^Zarray-section-begin ARRAY-INDEX VALUE-FLAGS
where ARRAY-INDEX is the index of the first element being annotated and
VALUE-FLAGS has the same meaning as in a 'value-history-begin'
annotation. This is followed by any number of elements, where is
element can be either a single element:
',' WHITESPACE ; omitted for the first element
THE-VALUE
^Z^Zelt
or a repeated element
',' WHITESPACE ; omitted for the first element
THE-VALUE
^Z^Zelt-rep NUMBER-OF-REPETITIONS
REPETITION-STRING
^Z^Zelt-rep-end
In both cases, THE-VALUE is the output for the value of the element
and WHITESPACE can contain spaces, tabs, and newlines. In the repeated
case, NUMBER-OF-REPETITIONS is the number of consecutive array elements
which contain that value, and REPETITION-STRING is a string which is
designed to convey to the user that repetition is being depicted.
Once all the array elements have been output, the array annotation is
ended with
^Z^Zarray-section-end