* annotate.texi: New file, to document annotations.
This commit is contained in:
Jim Kingdon
parent
4dd876ac2e
commit
a936321888
3 changed files with 367 additions and 0 deletions
|
|
@ -32,6 +32,7 @@ ChangeLog
|
|||
Makefile.in
|
||||
a4rc.sed
|
||||
all-cfg.texi
|
||||
annotate.texi
|
||||
configure.in
|
||||
libgdb.texinfo
|
||||
gdb.texinfo
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
Thu Apr 28 07:44:28 1994 Jim Kingdon (kingdon@lioth.cygnus.com)
|
||||
|
||||
* annotate.texi: New file, to document annotations.
|
||||
|
||||
Thu Apr 21 14:20:51 1994 Jim Kingdon (kingdon@lioth.cygnus.com)
|
||||
|
||||
* Makefile.in (clean): Don't remove GDBvn.texi (apparently on Jan
|
||||
|
|
|
|||
|
|
@ -0,0 +1,362 @@
|
|||
\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}
|
||||
@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.
|
||||
|
||||
@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.
|
||||
@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
|
||||
Loading…
Reference in a new issue