2003-08-06 Andrew Cagney <cagney@redhat.com>
* gdb.texinfo (Mode Options): Mention that level three is the highest available and that level 2 is deprecated. (Annotations Overview): Mention annotation levels. Cross reference to "Limitations of the Annotation Interface" in annotate.texi. (TODO, Value Annotations, Frame Annotations): Delete section. (Displays, Breakpoint Info): Delete.
This commit is contained in:
Andrew Cagney
parent
97b639ba81
commit
086432e254
|
|
@ -1,3 +1,12 @@
|
|||
2003-08-06 Andrew Cagney <cagney@redhat.com>
|
||||
|
||||
* gdb.texinfo (Mode Options): Mention that level three is the
|
||||
highest available and that level 2 is deprecated.
|
||||
(Annotations Overview): Mention annotation levels. Cross reference
|
||||
to "Limitations of the Annotation Interface" in annotate.texi.
|
||||
(TODO, Value Annotations, Frame Annotations): Delete section.
|
||||
(Displays, Breakpoint Info): Delete.
|
||||
|
||||
2003-08-04 Andrew Cagney <cagney@redhat.com>
|
||||
|
||||
* agentexpr.texi: Delete @bye.
|
||||
|
|
|
|||
|
|
@ -1054,12 +1054,15 @@ separate window.
|
|||
@cindex @code{--annotate}
|
||||
This option sets the @dfn{annotation level} inside @value{GDBN}. Its
|
||||
effect is identical to using @samp{set annotate @var{level}}
|
||||
(@pxref{Annotations}).
|
||||
Annotation level controls how much information does @value{GDBN} print
|
||||
together with its prompt, values of expressions, source lines, and other
|
||||
types of output. Level 0 is the normal, level 1 is for use when
|
||||
@value{GDBN} is run as a subprocess of @sc{gnu} Emacs, level 2 is the
|
||||
maximum annotation suitable for programs that control @value{GDBN}.
|
||||
(@pxref{Annotations}). The annotation @var{level} controls how much
|
||||
information @value{GDBN} prints together with its prompt, values of
|
||||
expressions, source lines, and other types of output. Level 0 is the
|
||||
normal, level 1 is for use when @value{GDBN} is run as a subprocess of
|
||||
@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
|
||||
that control @value{GDBN}, and level 2 has been deprecated.
|
||||
|
||||
The annotation mechanism has largely been superseeded by @sc{gdb/mi}
|
||||
(@pxref{GDB/MI}).
|
||||
|
||||
@item -async
|
||||
@cindex @code{--async}
|
||||
|
|
@ -18200,11 +18203,14 @@ A @samp{*} causes all existing variable objects to be updated.
|
|||
@node Annotations
|
||||
@chapter @value{GDBN} Annotations
|
||||
|
||||
This chapter describes annotations in @value{GDBN}. Annotations are
|
||||
designed to interface @value{GDBN} to graphical user interfaces or
|
||||
other similar programs which want to interact with @value{GDBN} at a
|
||||
This chapter describes annotations in @value{GDBN}. Annotations were
|
||||
designed to interface @value{GDBN} to graphical user interfaces or other
|
||||
similar programs which want to interact with @value{GDBN} at a
|
||||
relatively high level.
|
||||
|
||||
The annotation mechanism has largely been superseeded by @sc{gdb/mi}
|
||||
(@pxref{GDB/MI}).
|
||||
|
||||
@ignore
|
||||
This is Edition @value{EDITION}, @value{DATE}.
|
||||
@end ignore
|
||||
|
|
@ -18212,25 +18218,18 @@ This is Edition @value{EDITION}, @value{DATE}.
|
|||
@menu
|
||||
* Annotations Overview:: What annotations are; the general syntax.
|
||||
* Server Prefix:: Issuing a command without affecting user state.
|
||||
* Value Annotations:: Values are marked as such.
|
||||
* Frame Annotations:: Stack frames are annotated.
|
||||
* Displays:: @value{GDBN} can be told to display something periodically.
|
||||
* Prompting:: Annotations marking @value{GDBN}'s need for input.
|
||||
* Errors:: Annotations for error messages.
|
||||
* Breakpoint Info:: Information on breakpoints.
|
||||
* Invalidation:: Some annotations describe things now invalid.
|
||||
* Annotations for Running::
|
||||
Whether the program is running, how it stopped, etc.
|
||||
* Source Annotations:: Annotations describing source code.
|
||||
* TODO:: Annotations which might be added in the future.
|
||||
@end menu
|
||||
|
||||
@node Annotations Overview
|
||||
@section What is an Annotation?
|
||||
@cindex annotations
|
||||
|
||||
To produce annotations, start @value{GDBN} 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
|
||||
|
|
@ -18246,24 +18245,35 @@ no need for @value{GDBN} to output a newline followed by two
|
|||
annotations could be extended with an @samp{escape} annotation which
|
||||
means those three characters as output.
|
||||
|
||||
The annotation @var{level}, which is specified using the
|
||||
@option{--annotate} command line option (@pxref{Mode Options}), controls
|
||||
how much information @value{GDBN} prints together with its prompt,
|
||||
values of expressions, source lines, and other types of output. Level 0
|
||||
is for no anntations, level 1 is for use when @value{GDBN} is run as a
|
||||
subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable
|
||||
for programs that control @value{GDBN}, and level 2 annotations have
|
||||
been made obsolete (@pxref{Limitations, , Limitations of the Annotation
|
||||
Interface, annotate, GDB's Obsolete Annotations}). This chapter
|
||||
describes level 3 annotations.
|
||||
|
||||
A simple example of starting up @value{GDBN} with annotations is:
|
||||
|
||||
@smallexample
|
||||
$ gdb --annotate=2
|
||||
GNU GDB 5.0
|
||||
Copyright 2000 Free Software Foundation, Inc.
|
||||
$ @kbd{gdb --annotate=3}
|
||||
GNU gdb 6.0
|
||||
Copyright 2003 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"
|
||||
This GDB was configured as "i386-pc-linux-gnu"
|
||||
|
||||
^Z^Zpre-prompt
|
||||
(gdb)
|
||||
^Z^Zprompt
|
||||
quit
|
||||
@kbd{quit}
|
||||
|
||||
^Z^Zpost-prompt
|
||||
$
|
||||
|
|
@ -18288,311 +18298,6 @@ 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 Value Annotations
|
||||
@section Values
|
||||
|
||||
@cindex annotations for values
|
||||
When a value is printed in various contexts, @value{GDBN} uses
|
||||
annotations to delimit the value from the surrounding text.
|
||||
|
||||
@findex value-history-begin
|
||||
@findex value-history-value
|
||||
@findex value-history-end
|
||||
If a value is printed using @code{print} and added to the value history,
|
||||
the annotation looks like
|
||||
|
||||
@smallexample
|
||||
^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 smallexample
|
||||
|
||||
@noindent
|
||||
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.
|
||||
|
||||
@findex value-begin
|
||||
@findex value-end
|
||||
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:
|
||||
|
||||
@smallexample
|
||||
^Z^Zvalue-begin @var{value-flags}
|
||||
@var{the-value}
|
||||
^Z^Zvalue-end
|
||||
@end smallexample
|
||||
|
||||
@findex arg-begin
|
||||
@findex arg-name-end
|
||||
@findex arg-value
|
||||
@findex arg-end
|
||||
When @value{GDBN} prints an argument to a function (for example, in the output
|
||||
from the @code{backtrace} command), it annotates it as follows:
|
||||
|
||||
@smallexample
|
||||
^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 smallexample
|
||||
|
||||
@noindent
|
||||
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.
|
||||
|
||||
@findex field-begin
|
||||
@findex field-name-end
|
||||
@findex field-value
|
||||
@findex field-end
|
||||
When printing a structure, @value{GDBN} annotates it as follows:
|
||||
|
||||
@smallexample
|
||||
^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 smallexample
|
||||
|
||||
@noindent
|
||||
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, @value{GDBN} annotates it as follows:
|
||||
|
||||
@smallexample
|
||||
^Z^Zarray-section-begin @var{array-index} @var{value-flags}
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
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:
|
||||
|
||||
@findex elt
|
||||
@smallexample
|
||||
@samp{,} @var{whitespace} ; @r{omitted for the first element}
|
||||
@var{the-value}
|
||||
^Z^Zelt
|
||||
@end smallexample
|
||||
|
||||
or a repeated element
|
||||
|
||||
@findex elt-rep
|
||||
@findex elt-rep-end
|
||||
@smallexample
|
||||
@samp{,} @var{whitespace} ; @r{omitted for the first element}
|
||||
@var{the-value}
|
||||
^Z^Zelt-rep @var{number-of-repetitions}
|
||||
@var{repetition-string}
|
||||
^Z^Zelt-rep-end
|
||||
@end smallexample
|
||||
|
||||
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-repetitions} 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 repetition is being depicted.
|
||||
|
||||
@findex array-section-end
|
||||
Once all the array elements have been output, the array annotation is
|
||||
ended with
|
||||
|
||||
@smallexample
|
||||
^Z^Zarray-section-end
|
||||
@end smallexample
|
||||
|
||||
@node Frame Annotations
|
||||
@section Frames
|
||||
|
||||
@cindex annotations for frames
|
||||
Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
|
||||
to frames printed when @value{GDBN} stops, output from commands such as
|
||||
@code{backtrace} or @code{up}, etc.
|
||||
|
||||
@findex frame-begin
|
||||
The frame annotation begins with
|
||||
|
||||
@smallexample
|
||||
^Z^Zframe-begin @var{level} @var{address}
|
||||
@var{level-string}
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
where @var{level} is the number of the frame (0 is the innermost frame,
|
||||
and other frames have positive numbers), @var{address} is the address of
|
||||
the code executing in that frame, and @var{level-string} is a string
|
||||
designed to convey the level to the user. @var{address} is in the form
|
||||
@samp{0x} followed by one or more lowercase hex digits (note that this
|
||||
does not depend on the language). The frame ends with
|
||||
|
||||
@findex frame-end
|
||||
@smallexample
|
||||
^Z^Zframe-end
|
||||
@end smallexample
|
||||
|
||||
Between these annotations is the main body of the frame, which can
|
||||
consist of
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
@findex function-call
|
||||
@smallexample
|
||||
^Z^Zfunction-call
|
||||
@var{function-call-string}
|
||||
@end smallexample
|
||||
|
||||
where @var{function-call-string} is text designed to convey to the user
|
||||
that this frame is associated with a function call made by @value{GDBN} to a
|
||||
function in the program being debugged.
|
||||
|
||||
@item
|
||||
@findex signal-handler-caller
|
||||
@smallexample
|
||||
^Z^Zsignal-handler-caller
|
||||
@var{signal-handler-caller-string}
|
||||
@end smallexample
|
||||
|
||||
where @var{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).
|
||||
|
||||
@item
|
||||
A normal frame.
|
||||
|
||||
@findex frame-address
|
||||
@findex frame-address-end
|
||||
This can optionally (depending on whether this is thought of as
|
||||
interesting information for the user to see) begin with
|
||||
|
||||
@smallexample
|
||||
^Z^Zframe-address
|
||||
@var{address}
|
||||
^Z^Zframe-address-end
|
||||
@var{separator-string}
|
||||
@end smallexample
|
||||
|
||||
where @var{address} is the address executing in the frame (the same
|
||||
address as in the @code{frame-begin} annotation, but printed in a form
|
||||
which is intended for user consumption---in particular, the syntax varies
|
||||
depending on the language), and @var{separator-string} is a string
|
||||
intended to separate this address from what follows for the user's
|
||||
benefit.
|
||||
|
||||
@findex frame-function-name
|
||||
@findex frame-args
|
||||
Then comes
|
||||
|
||||
@smallexample
|
||||
^Z^Zframe-function-name
|
||||
@var{function-name}
|
||||
^Z^Zframe-args
|
||||
@var{arguments}
|
||||
@end smallexample
|
||||
|
||||
where @var{function-name} is the name of the function executing in the
|
||||
frame, or @samp{??} if not known, and @var{arguments} are the arguments
|
||||
to the frame, with parentheses around them (each argument is annotated
|
||||
individually as well, @pxref{Value Annotations}).
|
||||
|
||||
@findex frame-source-begin
|
||||
@findex frame-source-file
|
||||
@findex frame-source-file-end
|
||||
@findex frame-source-line
|
||||
@findex frame-source-end
|
||||
If source information is available, a reference to it is then printed:
|
||||
|
||||
@smallexample
|
||||
^Z^Zframe-source-begin
|
||||
@var{source-intro-string}
|
||||
^Z^Zframe-source-file
|
||||
@var{filename}
|
||||
^Z^Zframe-source-file-end
|
||||
:
|
||||
^Z^Zframe-source-line
|
||||
@var{line-number}
|
||||
^Z^Zframe-source-end
|
||||
@end smallexample
|
||||
|
||||
where @var{source-intro-string} separates for the user's benefit the
|
||||
reference from the text which precedes it, @var{filename} is the name of
|
||||
the source file, and @var{line-number} is the line number within that
|
||||
file (the first line is line 1).
|
||||
|
||||
@findex frame-where
|
||||
If @value{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
|
||||
|
||||
@smallexample
|
||||
^Z^Zframe-where
|
||||
@var{information}
|
||||
@end smallexample
|
||||
|
||||
Then, if source is to actually be displayed for this frame (for example,
|
||||
this is not true for output from the @code{backtrace} command), then a
|
||||
@code{source} annotation (@pxref{Source Annotations}) is displayed. Unlike
|
||||
most annotations, this is output instead of the normal text which would be
|
||||
output, not in addition.
|
||||
@end itemize
|
||||
|
||||
@node Displays
|
||||
@section Displays
|
||||
|
||||
@findex display-begin
|
||||
@findex display-number-end
|
||||
@findex display-format
|
||||
@findex display-expression
|
||||
@findex display-expression-end
|
||||
@findex display-value
|
||||
@findex display-end
|
||||
@cindex annotations for display
|
||||
When @value{GDBN} is told to display something using the @code{display} command,
|
||||
the results of the display are annotated:
|
||||
|
||||
@smallexample
|
||||
^Z^Zdisplay-begin
|
||||
@var{number}
|
||||
^Z^Zdisplay-number-end
|
||||
@var{number-separator}
|
||||
^Z^Zdisplay-format
|
||||
@var{format}
|
||||
^Z^Zdisplay-expression
|
||||
@var{expression}
|
||||
^Z^Zdisplay-expression-end
|
||||
@var{expression-separator}
|
||||
^Z^Zdisplay-value
|
||||
@var{value}
|
||||
^Z^Zdisplay-end
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
where @var{number} is the number of the display, @var{number-separator}
|
||||
is intended to separate the number from what follows for the user,
|
||||
@var{format} includes information such as the size, format, or other
|
||||
information about how the value is being displayed, @var{expression} is
|
||||
the expression being displayed, @var{expression-separator} is intended
|
||||
to separate the expression from the text that follows for the user,
|
||||
and @var{value} is the actual value being displayed.
|
||||
|
||||
@node Prompting
|
||||
@section Annotation for @value{GDBN} Input
|
||||
|
||||
|
|
@ -18693,64 +18398,6 @@ Warning messages are not yet annotated.
|
|||
@c If we want to change that, need to fix warning(), type_error(),
|
||||
@c range_error(), and possibly other places.
|
||||
|
||||
@node Breakpoint Info
|
||||
@section Information on Breakpoints
|
||||
|
||||
@cindex annotations for breakpoints
|
||||
The output from the @code{info breakpoints} command is annotated as follows:
|
||||
|
||||
@findex breakpoints-headers
|
||||
@findex breakpoints-table
|
||||
@smallexample
|
||||
^Z^Zbreakpoints-headers
|
||||
@var{header-entry}
|
||||
^Z^Zbreakpoints-table
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
where @var{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:
|
||||
|
||||
@findex record
|
||||
@findex field
|
||||
@smallexample
|
||||
^Z^Zrecord
|
||||
^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 smallexample
|
||||
|
||||
Note that @var{address} is intended for user consumption---the syntax
|
||||
varies depending on the language.
|
||||
|
||||
The output ends with
|
||||
|
||||
@findex breakpoints-table-end
|
||||
@smallexample
|
||||
^Z^Zbreakpoints-table-end
|
||||
@end smallexample
|
||||
|
||||
@node Invalidation
|
||||
@section Invalidation Notices
|
||||
|
||||
|
|
@ -18866,23 +18513,6 @@ source which is being displayed. @var{addr} is in the form @samp{0x}
|
|||
followed by one or more lowercase hex digits (note that this does not
|
||||
depend on the language).
|
||||
|
||||
@node TODO
|
||||
@section Annotations We Might Want in the Future
|
||||
|
||||
@format
|
||||
- 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.
|
||||
@end format
|
||||
|
||||
@node GDB Bugs
|
||||
@chapter Reporting Bugs in @value{GDBN}
|
||||
@cindex bugs in @value{GDBN}
|
||||
|
|
|
|||
Loading…
Reference in New Issue