Debugging with GDB Manual The GNU Source-Level Debugger (769148-001, March 2014)

20 GDB Annotations
This chapter describes annotations in GDB. Annotations are designed to interface GDB to graphical
user interfaces or other similar programs which want to interact with GDB at a relatively high level.
What is an annotation?
To produce annotations, start GDB with the --annotate=2 option.
Annotations start with a newline character, two control-z characters, and the name of the
annotation. If there is no additional information associated with this annotation, the name of the
annotation is followed immediately by a newline. If there is additional information, the name of
the annotation is followed by a space, the additional information, and a newline. The additional
information cannot contain newline characters.
Any output not beginning with a newline and two control-z characters denotes literal output
from GDB. Currently there is no need for GDB to output a newline followed by two control-z
characters, but if there was such a need, the annotations could be extended with an `escape'
annotation which means those three characters as output.
A simple example of starting up GDB with annotations is:
$ gdb --annotate=2
GNU GDB 5.0
Copyright 2000 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License,
and you are welcome to change it and/or distribute copies of it
under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty"
for details.
This GDB was configured as "sparc-sun-sunos4.1.3"
^Z^Zpre-prompt
(gdb)
^Z^Zprompt
quit
^Z^Zpost-prompt
$
Here quit is input to GDB; the rest is output from GDB. The three lines beginning `^Z^Z' (where
`^Z' denotes a control-z character) are annotations; the rest is output from GDB.
The server prefix
To issue a command to GDB without affecting certain aspects of the state which is seen by users,
prefix it with server. This means that this command will not affect the command history, nor will
it affect GDB's notion of which command to repeat if RET is pressed on a line by itself.
The server prefix does not affect the recording of values into the value history; to print a value
without recording it into the value history, use the output command instead of the print
command.
Values
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
226 GDB Annotations