     [file gdb-cfg.texi not included]

This file documents GDBN's obsolete annotations.

Copyright © 1994--2020 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

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

This document describes the obsolete level two annotation interface implemented in older GDBN versions.

What is an Annotation?
**********************

To produce obsolete level two annotations, start GDBN 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 GDBN.  Currently there is no need 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.

A simple example of starting up GDBN 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 GDBN; the rest is output from GDBN.  The three lines beginning ^Z^Z (where ^Z denotes a control-z character) are annotations; the rest is output from GDBN.

Limitations of the Annotation Interface
***************************************

The level two annotations mechanism is known to have a number of technical and architectural limitations.  As a consequence, in 2001, with the release of GDBN 5.1 and the addition of GDB/MI, the annotation interface was marked as deprecated.

This chapter discusses the known problems.

Dependant on CLI output
=======================

The annotation interface works by interspersing markups with GDBN normal command-line interpreter output.  Unfortunately, this makes the annotation client dependant on not just the annotations, but also the CLI output.  This is because the client is forced to assume that specific GDBN commands provide specific information. Any change to GDBN's CLI output modifies or removes that information and, consequently, likely breaks the client.

Since the GDB/MI output is independent of the CLI, it does not have this problem.

Scalability
===========

The annotation interface relies on value annotations (see Value Annotations) and the display mechanism as a way of obtaining up-to-date value information.  These mechanisms are not scalable.

In a graphical environment, where many values can be displayed simultaneously, a serious performance problem occurs when the client tries to first extract from GDBN, and then re-display, all those values.  The client should instead only request and update the values that changed.

The GDB/MI Variable Objects provide just that mechanism.

Correctness
===========

The annotation interface assumes that a variable's value can only be changed when the target is running.  This assumption is not correct.  A single assignment to a single variable can result in the entire target, and all displayed values, needing an update.

The GDB/MI Variable Objects include a mechanism for efficiently reporting such changes.

Reliability
===========

The GDB/MI interface includes a dedicated test directory (gdb/gdb.mi), and any addition or fix to GDB/MI must include testsuite changes.

Maintainability
===============

The annotation mechanism was implemented by interspersing CLI print statements with various annotations.  As a consequence, any CLI output change can alter the annotation output.

Since the GDB/MI output is independent of the CLI, and the GDB/MI is increasingly implemented independent of the CLI code, its long term maintenance is much easier.

Migrating to GDB/MI
*******************

By using the interp mi command, it is possible for annotation clients to invoke GDB/MI commands, and hence access the GDB/MI.  By doing this, existing annotation clients have a migration path from this obsolete interface to GDB/MI.

The Server Prefix
*****************

To issue a command to GDBN 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 GDBN'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
******

Value Annotations have been removed.  GDB/MI instead provides Variable Objects.

When a value is printed in various contexts, GDBN 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 GDBN 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, GDBN 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, GDBN 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

Frames
******

Value Annotations have been removed.  GDB/MI instead provides a number of frame commands.

Frame annotations are no longer available.  The GDB/MI provides -stack-list-arguments, -stack-list-locals, and -stack-list-frames commands.

Whenever GDBN prints a frame, it annotates it.  For example, this applies to frames printed when GDBN stops, output from commands such as backtrace or up, etc.

The frame annotation begins with

     ^Z^Zframe-begin LEVEL ADDRESS
     LEVEL-STRING

where LEVEL is the number of the frame (0 is the innermost frame, and other frames have positive numbers), ADDRESS is the address of the code executing in that frame, and LEVEL-STRING is a string designed to convey the level to the user.  ADDRESS is in the form 0x followed by one or more lowercase hex digits (note that this does not depend on the language).  The frame ends with

     ^Z^Zframe-end

Between these annotations is the main body of the frame, which can consist of

  * ^Z^Zfunction-call
          FUNCTION-CALL-STRING

     where FUNCTION-CALL-STRING is text designed to convey to the user that this frame is associated with a function call made by GDBN to a function in the program being debugged.

  * ^Z^Zsignal-handler-caller
          SIGNAL-HANDLER-CALLER-STRING

     where SIGNAL-HANDLER-CALLER-STRING is text designed to convey to the user that this frame is associated with whatever mechanism is used by this operating system to call a signal handler (it is the frame which calls the signal handler, not the frame for the signal handler itself).

  * A normal frame.

     This can optionally (depending on whether this is thought of as interesting information for the user to see) begin with

          ^Z^Zframe-address
          ADDRESS
          ^Z^Zframe-address-end
          SEPARATOR-STRING

     where ADDRESS is the address executing in the frame (the same address as in the frame-begin annotation, but printed in a form which is intended for user consumption---in particular, the syntax varies depending on the language), and SEPARATOR-STRING is a string intended to separate this address from what follows for the user's benefit.

     Then comes

          ^Z^Zframe-function-name
          FUNCTION-NAME
          ^Z^Zframe-args
          ARGUMENTS

     where FUNCTION-NAME is the name of the function executing in the frame, or ?? if not known, and ARGUMENTS are the arguments to the frame, with parentheses around them (each argument is annotated individually as well, see Value Annotations).

     If source information is available, a reference to it is then printed:

          ^Z^Zframe-source-begin
          SOURCE-INTRO-STRING
          ^Z^Zframe-source-file
          FILENAME
          ^Z^Zframe-source-file-end
          :
          ^Z^Zframe-source-line
          LINE-NUMBER
          ^Z^Zframe-source-end

     where SOURCE-INTRO-STRING separates for the user's benefit the reference from the text which precedes it, FILENAME is the name of the source file, and LINE-NUMBER is the line number within that file (the first line is line 1).

     If GDBN prints some information about where the frame is from (which library, which load segment, etc.; currently only done on the RS/6000), it is annotated with

          ^Z^Zframe-where
          INFORMATION

     Then, if source is to actually be displayed for this frame (for example, this is not true for output from the backtrace command), then a source annotation (see Source Annotations) is displayed.  Unlike most annotations, this is output instead of the normal text which would be output, not in addition.

Displays
********

Display Annotations have been removed.  GDB/MI instead provides Variable Objects.

When GDBN is told to display something using the display command, the results of the display are annotated:

     ^Z^Zdisplay-begin
     NUMBER
     ^Z^Zdisplay-number-end
     NUMBER-SEPARATOR
     ^Z^Zdisplay-format
     FORMAT
     ^Z^Zdisplay-expression
     EXPRESSION
     ^Z^Zdisplay-expression-end
     EXPRESSION-SEPARATOR
     ^Z^Zdisplay-value
     VALUE
     ^Z^Zdisplay-end

where NUMBER is the number of the display, NUMBER-SEPARATOR is intended to separate the number from what follows for the user, FORMAT includes information such as the size, format, or other information about how the value is being displayed, EXPRESSION is the expression being displayed, EXPRESSION-SEPARATOR is intended to separate the expression from the text that follows for the user, and VALUE is the actual value being displayed.

Annotation for GDBN Input
*************************

When GDBN 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 GDBN is prompting for a command (the main GDBN prompt).

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

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

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

prompt-for-continue
     When GDBN 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 GDBN responds to an interrupt.

     ^Z^Zerror

This annotation occurs right before GDBN responds to an error.

Quit and error annotations indicate that any annotations which GDBN 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 GDBN 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
**************************

Breakpoint Annotations have been removed.  GDB/MI instead provides breakpoint commands.

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

Note that ADDRESS is intended for user consumption---the syntax varies depending on the language.

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.

Running the Program
*******************

When the program starts executing due to a GDBN command such as step or continue,

     ^Z^Zstarting

is output.  When the program stops,

     ^Z^Zstopped

is output.  Before the stopped annotation, a variety of annotations describe how the program stopped.

^Z^Zexited EXIT-STATUS
     The program exited, and EXIT-STATUS is the exit status (zero for successful exit, otherwise nonzero).

^Z^Zsignalled
     The program exited with a signal.  After the ^Z^Zsignalled, the annotation continues:

          INTRO-TEXT
          ^Z^Zsignal-name
          NAME
          ^Z^Zsignal-name-end
          MIDDLE-TEXT
          ^Z^Zsignal-string
          STRING
          ^Z^Zsignal-string-end
          END-TEXT

     where NAME is the name of the signal, such as SIGILL or SIGSEGV, and STRING is the explanation of the signal, such as Illegal Instruction or Segmentation fault. INTRO-TEXT, MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no particular format.

^Z^Zsignal
     The syntax of this annotation is just like signalled, but GDBN is just saying that the program received the signal, not that it was terminated with it.

^Z^Zbreakpoint NUMBER
     The program hit breakpoint number NUMBER.

^Z^Zwatchpoint NUMBER
     The program hit watchpoint number NUMBER.

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.  ADDR is in the form 0x followed by one or more lowercase hex digits (note that this does not depend on the language).

Multi-threaded Applications
***************************

The following annotations report thread related changes of state.

^Z^Znew-thread

     This annotation is issued once for each thread that is created apart from the main thread, which is not reported.

^Z^Zthread-changed

     The selected thread has changed.  This may occur at the request of the user with the thread command, or as a result of execution, e.g., another thread hits a breakpoint.

^Z^Zthread-exited,id="ID",group-id="GID"

     This annotation is issued once for each thread that exits.  The ID field contains the global GDBN identifier of the thread.  The GID field identifies the thread group this thread belongs to.

GNU Free Documentation License
******************************

     [file fdl.texi not included]