25.1 What is an Annotation?

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 No value for GDBN. Currently there is no need for No value for GDBN 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.

The annotation level, which is specified using the ‘--annotate’ command line option (see section Choosing Modes), controls how much information No value for GDBN prints together with its prompt, values of expressions, source lines, and other types of output. Level 0 is for no annotations, level 1 is for use when No value for GDBN is run as a subprocess of GNU Emacs, level 3 is the maximum annotation suitable for programs that control No value for GDBN, and level 2 annotations have been made obsolete (see (annotate)Limitations section `Limitations of the Annotation Interface' in GDB's Obsolete Annotations).

set annotate level

The No value for GDBN command set annotate sets the level of annotations to the specified level.

show annotate

Show the current annotation level.

This chapter describes level 3 annotations.

A simple example of starting up No value for GDBN with annotations is:

$ gdb --annotate=3
GNU gdb 6.0
Copyright 2003 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 "i386-pc-linux-gnu"

^Z^Zpre-prompt
(No value for GDBP)
^Z^Zprompt
quit

^Z^Zpost-prompt
$

Here ‘quit’ is input to No value for GDBN; the rest is output from No value for GDBN. The three lines beginning ‘^Z^Z’ (where ‘^Z’ denotes a ‘control-z’ character) are annotations; the rest is output from No value for GDBN.