* annotate.texi: New file, to document annotations.

[deliverable/binutils-gdb.git] / gdb / doc / annotate.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename annotate.info
@settitle GDB Annotations
@setchapternewpage off
@c %**end of header

@set EDITION 0.4
@set DATE April 1994

@ifinfo
This file documents GDB annotations.

This is Edition @value{EDITION}, @value{DATE}, of @cite{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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
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.
@end ifinfo

@titlepage
@title GDB Annotations
@subtitle Edition @value{EDITION}
@subtitle @value{DATE}
@author Cygnus Support
@page
@vskip 0pt plus 1filll
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.

Copyright @copyright{} 1994 Free Software Foundation
@end titlepage

@ifinfo
@node Top
@top 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 @value{EDITION}, @value{DATE}.

@menu
* General::             What annotations are; the general syntax.
* Server::              Issuing a command without affecting user state.
* Values::              Values are marked as such.
* Prompting::           GDB annotations marking GDB's need for input.
* Breakpoint Info::     Information on breakpoints.
* Invalidation::        Some annotations describe things now invalid.
* Source::              Annotations describing source code.
@end menu
@end ifinfo

@node General
@chapter What is an Annotation?

To produce annotations, start GDB with the @code{--annotate=2} option.

Annotations start with a newline character, two @samp{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 @samp{control-z}
characters denotes literal output from GDB.  Currently there is no need
for GDB to output a newline followed by two @samp{control-z} characters,
but if there was such a need, the annotations could be extended with an
@samp{escape} annotation which means those three characters as output.

A simple example of starting up GDB with annotations is:

@example
$ 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
$ 
@end example

Here @samp{quit} is input to GDB; the rest is output from GDB.  The three
lines beginning @samp{^Z^Z} (where @samp{^Z} denotes a @samp{control-z}
character) are annotations; the rest is output from GDB.

@node Server
@chapter The Server Prefix

To issue a command to GDB without affecting certain aspects of the state
which is seen by users, prefix it with @samp{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 @key{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 @code{output} command instead of the @code{print} command.

@node Values
@chapter 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 @code{print} and added to the value history,
the annotation looks like

@example
^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
@var{history-string}
^Z^Zvalue-history-value
@var{the-value}
^Z^Zvalue-history-end
@end example

where @var{history-number} is the number it is getting in the value
history, @var{history-string} is a string, such as @samp{$5 = }, which
introduces the value to the user, @var{the-value} is the output
corresponding to the value itself, and @var{value-flags} is @samp{*} for
a value which can be dereferenced and @samp{-} 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 @code{output} command), the annotation is similar:

@example
^Z^Zvalue-begin @var{value-flags}
@var{the-value}
^Z^Zvalue-end
@end example

When GDB prints an argument to a function (for example, in the output
from the @code{backtrace} command), it annotates it as follows:

@example
^Z^Zarg-begin
@var{argument-name}
^Z^Zarg-name-end
@var{separator-string}
^Z^Zarg-value @var{value-flags}
@var{the-value}
^Z^Zarg-end
@end example

where @var{argument-name} is the name of the argument,
@var{separator-string} is text which separates the name from the value
for the user's benefit (such as @samp{=}), and @var{value-flags} and
@var{the-value} have the same meanings as in a
@code{value-history-begin} annotation.

When printing a structure, GDB annotates it as follows:

@example
^Z^Zfield-begin @var{value-flags}
@var{field-name}
^Z^Zfield-name-end
@var{separator-string}
^Z^Zfield-value
@var{the-value}
^Z^Zfield-end
@end example

where @var{field-name} is the name of the field, @var{separator-string}
is text which separates the name from the value for the user's benefit
(such as @samp{=}), and @var{value-flags} and @var{the-value} have the
same meanings as in a @code{value-history-begin} annotation.

When printing an array, GDB annotates it as follows:

@example
^Z^Zarray-section-begin @var{array-index} @var{value-flags}
@end example

where @var{array-index} is the index of the first element being
annotated and @var{value-flags} has the same meaning as in a
@code{value-history-begin} annotation.  This is followed by any number
of elements, where is element can be either a single element:

@example
@samp{,} @var{whitespace}         ; @r{omitted for the first element}
@var{the-value}
^Z^Zelt
@end example

or a repeated element

@example
@samp{,} @var{whitespace}         ; @r{omitted for the first element}
@var{the-value}
^Z^Zelt-rep @var{number-of-repititions}
@var{repetition-string}
^Z^Zelt-rep-end
@end example

In both cases, @var{the-value} is the output for the value of the
element and @var{whitespace} can contain spaces, tabs, and newlines.  In
the repeated case, @var{number-of-repititons} is the number of
consecutive array elements which contain that value, and
@var{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

@example
^Z^Zarray-section-end
@end example

@node Prompting
@chapter 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 @dfn{input type}.  Each
input type has three annotations: a @code{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 @code{post-}
annotation which denotes the end of any echo which may (or may not) be
associated with the input.  For example, the @code{prompt} input type
features the following annotations:

@example
^Z^Zpre-prompt
^Z^Zprompt
^Z^Zpost-prompt
@end example

The input types are

@table @code
@item prompt
When GDB is prompting for a command (the main GDB prompt).

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

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

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

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

@node Breakpoint Info
@chapter Information on Breakpoints

The output from the @code{info breakpoints} command is annotated as follows:

@example
^Z^Zbreakpoints-headers
@var{headers}
^Z^Zbreakpoints-table
@end example

where @var{headers} is a string which is designed to convey to the user
the order and significance of the fields.  This is followed by any
number of entries.  Each entry beings with a @code{field 0} annotation.
Some fields can be omitted if they don't apply for this entry.  Fields
have trailing whitespace so that if they are printed in order in a
fixed-width font, they match up with the headers.  The fields for an
entry are:

@example
^Z^Zfield 0
@var{number}
^Z^Zfield 1
@var{type}
^Z^Zfield 2
@var{disposition}
^Z^Zfield 3
@var{enable}
^Z^Zfield 4
@var{address}
^Z^Zfield 5
@var{what}
^Z^Zfield 6
@var{frame}
^Z^Zfield 7
@var{condition}
^Z^Zfield 8
@var{ignore-count}
^Z^Zfield 9
@var{commands}
@end example

The output ends with

@example
^Z^Zbreakpoints-table-end
@end example

@node Invalidation
@chapter Invalidation Notices

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

@table @code
@item ^Z^Zframes-invalid

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

@item ^Z^Zbreakpoints-invalid

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

@node Source
@chapter Displaying Source

The following annotation is used instead of displaying source code:

@example
^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
@end example

where @var{filename} is an absolute file name indicating which source
file, @var{line} is the line number within that file (where 1 is the
first line in the file), @var{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),
@var{middle} is @samp{middle} if @var{addr} is in the middle of the
line, or @samp{beg} if @var{addr} is at the beginning of the line, and
@var{addr} is the address in the target program associated with the
source which is being displayed.

@bye