This file documents GDB annotations.

This is Edition 0.4, April 1994, of GDB
Annotations.  Copyright 1994 Free Software Foundation

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

GDB Annotations
***************

This file describes annotations in GDB, the GNU symbolic debugger. 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.

This is Edition 0.4, April 1994.

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
     GDB is free software and you are welcome to 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.
     GDB 4.12.3 (sparc-sun-sunos4.1.3),
     Copyright 1994 Free Software Foundation, Inc.

     ^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

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-REPITITIONS
     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-REPITITONS 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 repitition is being depicted.

Once all the array elements have been output, the array annotation is ended with

     ^Z^Zarray-section-end

Annotation for GDB Input
************************

When GDB prompts for input, it annotates this fact so it is possible to know when to send output, when the output from a given command is over, etc.

Different kinds of input each have a different input type.  Each input type has three annotations: a pre- annotation, which denotes the beginning of any prompt which is being output, a plain annotation, which denotes the end of the prompt, and then a post- annotation which denotes the end of any echo which may (or may not) be associated with the input.  For example, the prompt input type features the following annotations:

     ^Z^Zpre-prompt
     ^Z^Zprompt
     ^Z^Zpost-prompt

The input types are

prompt
     When GDB is prompting for a command (the main GDB prompt).

commands
     When GDB prompts for a set of commands, like in the commands command.  The annotations are repeated for each command which is input.

overload-choice
     When GDB wants the user to select between various overloaded functions.

query
     When GDB wants the user to confirm a potentially dangerous operation.

prompt-for-continue
     When GDB is asking the user to press return to continue.  Note: Don't expect this to work well; instead use set height 0 to disable prompting.  This is because the counting of lines is buggy in the presence of annotations.

Errors
******

     ^Z^Zquit

This annotation occurs right before GDB responds to an interrupt.

     ^Z^Zerror

This annotation occurs right before GDB responds to an error.

Quit and error annotations indicate that any annotations which GDB was in the middle of may end abruptly.  For example, if a value-history-begin annotation is followed by a error, one cannot expect to receive the matching value-history-end.  One cannot expect not to receive it either, however; an error annotation does not necessarily mean that GDB is immediately returning all the way to the top level.

A quit or error annotation may be preceded by

     ^Z^Zerror-begin

Any output between that and the quit or error annotation is the error message.

Warning messages are not yet annotated.

Information on Breakpoints
**************************

The output from the info breakpoints command is annotated as follows:

     ^Z^Zbreakpoints-headers
     HEADER-ENTRY
     ^Z^Zbreakpoints-table

where HEADER-ENTRY has the same syntax as an entry (see below) but instead of containing data, it contains strings which are intended to convey the meaning of each field to the user.  This is followed by any number of entries.  If a field does not apply for this entry, it is omitted.  Fields may contain trailing whitespace.  Each entry consists of:

     ^Z^Zrecord
     ^Z^Zfield 0
     NUMBER
     ^Z^Zfield 1
     TYPE
     ^Z^Zfield 2
     DISPOSITION
     ^Z^Zfield 3
     ENABLE
     ^Z^Zfield 4
     ADDRESS
     ^Z^Zfield 5
     WHAT
     ^Z^Zfield 6
     FRAME
     ^Z^Zfield 7
     CONDITION
     ^Z^Zfield 8
     IGNORE-COUNT
     ^Z^Zfield 9
     COMMANDS

The output ends with

     ^Z^Zbreakpoints-table-end

Invalidation Notices
********************

The following annotations say that certain pieces of state may have changed.

^Z^Zframes-invalid

     The frames (for example, output from the backtrace command) may have changed.

^Z^Zbreakpoints-invalid

     The breakpoints may have changed.  For example, the user just added or deleted a breakpoint.

Displaying Source
*****************

The following annotation is used instead of displaying source code:

     ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR

where FILENAME is an absolute file name indicating which source file, LINE is the line number within that file (where 1 is the first line in the file), CHARACTER is the character position within the file (where 0 is the first character in the file) (for most debug formats this will necessarily point to the beginning of a line), MIDDLE is middle if ADDR is in the middle of the line, or beg if ADDR is at the beginning of the line, and ADDR is the address in the target program associated with the source which is being displayed.