This is Info file annotate.info, produced by Makeinfo-1.64 from the
input file annotate.tex.

   This file documents GDB annotations.

   This is Edition 0.5, May 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.


File: annotate,  Node: Top,  Next: General,  Up: (dir)

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.5, May 1994.

* Menu:

* General::             What annotations are; the general syntax.
* Server::              Issuing a command without affecting user state.
* Values::              Values are marked as such.
* Frames::              Stack frames are annotated.
* Displays::            GDB can be told to display something periodically.
* Prompting::           Annotations marking GDB's need for input.
* Errors::              Annotations for error messages.
* Breakpoint Info::     Information on breakpoints.
* Invalidation::        Some annotations describe things now invalid.
* Running::             Whether the program is running, how it stopped, etc.
* Source::              Annotations describing source code.
* TODO::                Annotations which might be added in the future.
* Index::               Index


File: annotate,  Node: General,  Next: Server,  Prev: Top,  Up: Top

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.


File: annotate,  Node: Server,  Next: Values,  Prev: General,  Up: Top

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.


File: annotate,  Node: Values,  Next: Frames,  Prev: Server,  Up: Top

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


File: annotate,  Node: Frames,  Next: Displays,  Prev: Values,  Up: Top

Frames
******

   Whenever GDB prints a frame, it annotates it.  For example, this
applies to frames printed when GDB 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 GDB 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 *note Values::.).

     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 GDB 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 (*note Source::.) is
     displayed.  Unlike most annotations, this is output instead of the
     normal text which would be output, not in addition.


File: annotate,  Node: Displays,  Next: Prompting,  Prev: Frames,  Up: Top

Displays
********

   When GDB 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.


File: annotate,  Node: Prompting,  Next: Errors,  Prev: Displays,  Up: Top

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.


File: annotate,  Node: Errors,  Next: Breakpoint Info,  Prev: Prompting,  Up: Top

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.


File: annotate,  Node: Breakpoint Info,  Next: Invalidation,  Prev: Errors,  Up: Top

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

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

   The output ends with

     ^Z^Zbreakpoints-table-end


File: annotate,  Node: Invalidation,  Next: Running,  Prev: Breakpoint Info,  Up: Top

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.


File: annotate,  Node: Running,  Next: Source,  Prev: Invalidation,  Up: Top

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

   When the program starts executing due to a GDB 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 GDB 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.


File: annotate,  Node: Source,  Next: TODO,  Prev: Running,  Up: Top

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).


File: annotate,  Node: TODO,  Next: Index,  Prev: Source,  Up: Top

Annotations We Might Want in the Future
***************************************

    - target-invalid
      the target might have changed (registers, heap contents, or
      execution status).  For performance, we might eventually want
      to hit `registers-invalid' and `all-registers-invalid' with
      greater precision

    - systematic annotation for set/show parameters (including
      invalidation notices).

    - similarly, `info' returns a list of candidates for invalidation
      notices.


File: annotate,  Node: Index,  Prev: TODO,  Up: Top

Index
*****

* Menu:

* arg-begin:                            Values.
* arg-end:                              Values.
* arg-name-end:                         Values.
* arg-value:                            Values.
* array-section-end:                    Values.
* breakpoint:                           Running.
* breakpoints-headers:                  Breakpoint Info.
* breakpoints-invalid:                  Invalidation.
* breakpoints-table:                    Breakpoint Info.
* breakpoints-table-end:                Breakpoint Info.
* commands:                             Prompting.
* display-begin:                        Displays.
* display-end:                          Displays.
* display-expression:                   Displays.
* display-expression-end:               Displays.
* display-format:                       Displays.
* display-number-end:                   Displays.
* display-value:                        Displays.
* elt:                                  Values.
* elt-rep:                              Values.
* elt-rep-end:                          Values.
* error:                                Errors.
* error-begin:                          Errors.
* exited:                               Running.
* field:                                Breakpoint Info.
* field-begin:                          Values.
* field-end:                            Values.
* field-name-end:                       Values.
* field-value:                          Values.
* frame-address:                        Frames.
* frame-address-end:                    Frames.
* frame-args:                           Frames.
* frame-begin:                          Frames.
* frame-end:                            Frames.
* frame-function-name:                  Frames.
* frame-source-begin:                   Frames.
* frame-source-end:                     Frames.
* frame-source-file:                    Frames.
* frame-source-file-end:                Frames.
* frame-source-line:                    Frames.
* frame-where:                          Frames.
* frames-invalid:                       Invalidation.
* function-call:                        Frames.
* overload-choice:                      Prompting.
* post-commands:                        Prompting.
* post-overload-choice:                 Prompting.
* post-prompt:                          Prompting.
* post-prompt-for-continue:             Prompting.
* post-query:                           Prompting.
* pre-commands:                         Prompting.
* pre-overload-choice:                  Prompting.
* pre-prompt:                           Prompting.
* pre-prompt-for-continue:              Prompting.
* pre-query:                            Prompting.
* prompt:                               Prompting.
* prompt-for-continue:                  Prompting.
* query:                                Prompting.
* quit:                                 Errors.
* record:                               Breakpoint Info.
* signal:                               Running.
* signal-handler-caller:                Frames.
* signal-name:                          Running.
* signal-name-end:                      Running.
* signal-string:                        Running.
* signal-string-end:                    Running.
* signalled:                            Running.
* source:                               Source.
* starting:                             Running.
* stopping:                             Running.
* value-begin:                          Values.
* value-end:                            Values.
* value-history-begin:                  Values.
* value-history-end:                    Values.
* value-history-value:                  Values.
* watchpoint:                           Running.



Tag Table:
Node: Top804
Node: General1967
Node: Server3625
Node: Values4233
Node: Frames7293
Node: Displays10897
Node: Prompting11826
Node: Errors13323
Node: Breakpoint Info14204
Node: Invalidation15330
Node: Running15785
Node: Source17262
Node: TODO18157
Node: Index18733

End Tag Table
