* annotate.texi: Change edition to 0.5 and date to May 1994.
Add index. (Frames): New node, for frame annotation. (Displays): New node, for display annotation.
This commit is contained in:
Jim Kingdon
parent
731dca9461
commit
f710410bf9
@ -1,5 +1,10 @@
|
||||
Wed May 4 06:26:11 1994 Jim Kingdon (kingdon@lioth.cygnus.com)
|
||||
|
||||
* annotate.texi: Change edition to 0.5 and date to May 1994.
|
||||
Add index.
|
||||
(Frames): New node, for frame annotation.
|
||||
(Displays): New node, for display annotation.
|
||||
|
||||
* remote.texi (MIPS Remote): Say that set timeout doesn't apply
|
||||
when waiting for your program to stop.
|
||||
|
||||
|
||||
@ -5,8 +5,8 @@
|
||||
@setchapternewpage off
|
||||
@c %**end of header
|
||||
|
||||
@set EDITION 0.4
|
||||
@set DATE April 1994
|
||||
@set EDITION 0.5
|
||||
@set DATE May 1994
|
||||
|
||||
@ifinfo
|
||||
This file documents GDB annotations.
|
||||
@ -63,11 +63,15 @@ This is Edition @value{EDITION}, @value{DATE}.
|
||||
* 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.
|
||||
* 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.
|
||||
* Index:: Index
|
||||
@end menu
|
||||
@end ifinfo
|
||||
|
||||
@ -132,6 +136,9 @@ use the @code{output} command instead of the @code{print} command.
|
||||
When a value is printed in various contexts, GDB 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
|
||||
|
||||
@ -149,6 +156,8 @@ 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:
|
||||
|
||||
@ -158,6 +167,10 @@ or it is printed with the @code{output} command), the annotation is similar:
|
||||
^Z^Zvalue-end
|
||||
@end example
|
||||
|
||||
@findex arg-begin
|
||||
@findex arg-name-end
|
||||
@findex arg-value
|
||||
@findex arg-end
|
||||
When GDB prints an argument to a function (for example, in the output
|
||||
from the @code{backtrace} command), it annotates it as follows:
|
||||
|
||||
@ -177,6 +190,10 @@ 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, GDB annotates it as follows:
|
||||
|
||||
@example
|
||||
@ -205,6 +222,7 @@ 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
|
||||
@example
|
||||
@samp{,} @var{whitespace} ; @r{omitted for the first element}
|
||||
@var{the-value}
|
||||
@ -213,6 +231,8 @@ of elements, where is element can be either a single element:
|
||||
|
||||
or a repeated element
|
||||
|
||||
@findex elt-rep
|
||||
@findex elt-rep-end
|
||||
@example
|
||||
@samp{,} @var{whitespace} ; @r{omitted for the first element}
|
||||
@var{the-value}
|
||||
@ -228,6 +248,7 @@ 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.
|
||||
|
||||
@findex array-section-end
|
||||
Once all the array elements have been output, the array annotation is
|
||||
ended with
|
||||
|
||||
@ -235,6 +256,172 @@ ended with
|
||||
^Z^Zarray-section-end
|
||||
@end example
|
||||
|
||||
@node Frames
|
||||
@chapter Frames
|
||||
|
||||
Whenever GDB prints a frame, it annotates it. For example, this applies
|
||||
to frames printed when GDB stops, output from commands such as
|
||||
@code{backtrace} or @code{up}, etc.
|
||||
|
||||
@findex frame-begin
|
||||
The frame annotation begins with
|
||||
|
||||
@example
|
||||
^Z^Zframe-begin @var{level} @var{address}
|
||||
@var{level-string}
|
||||
@end example
|
||||
|
||||
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. The frame ends with
|
||||
|
||||
@findex frame-end
|
||||
@example
|
||||
^Z^Zframe-end
|
||||
@end example
|
||||
|
||||
Between these annotations is the main body of the frame, which can
|
||||
consist of
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
@findex function-call
|
||||
@example
|
||||
^Z^Zfunction-call
|
||||
@var{function-call-string}
|
||||
@end example
|
||||
|
||||
where @var{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.
|
||||
|
||||
@item
|
||||
@findex signal-handler-caller
|
||||
@example
|
||||
^Z^Zsignal-handler-caller
|
||||
@var{signal-handler-caller-string}
|
||||
@end example
|
||||
|
||||
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
|
||||
|
||||
@example
|
||||
^Z^Zframe-address
|
||||
@var{address}
|
||||
^Z^Zframe-address-end
|
||||
@var{separator-string}
|
||||
@end example
|
||||
|
||||
where @var{address} is the address executing in the frame (the same
|
||||
address as in the @code{frame-begin} annotation), 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
|
||||
|
||||
@example
|
||||
^Z^Zframe-function-name
|
||||
@var{function-name}
|
||||
^Z^Zframe-args
|
||||
@var{arguments}
|
||||
@end example
|
||||
|
||||
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{Values}).
|
||||
|
||||
@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:
|
||||
|
||||
@example
|
||||
^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 example
|
||||
|
||||
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 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
|
||||
|
||||
@example
|
||||
^Z^Zframe-where
|
||||
@var{information}
|
||||
@end example
|
||||
|
||||
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}) is displayed. Unlike most
|
||||
annotations, this is output instead of the normal text which would be
|
||||
output, not in addition.
|
||||
@end itemize
|
||||
|
||||
@node Displays
|
||||
@chapter Displays
|
||||
|
||||
@findex display-begin
|
||||
@findex display-number-end
|
||||
@findex display-format
|
||||
@findex display-expression
|
||||
@findex display-expression-end
|
||||
@findex display-value
|
||||
@findex display-end
|
||||
When GDB is told to display something using the @code{display} command,
|
||||
the results of the display are annotated:
|
||||
|
||||
@example
|
||||
^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 example
|
||||
|
||||
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
|
||||
@chapter Annotation for GDB Input
|
||||
|
||||
@ -259,19 +446,34 @@ features the following annotations:
|
||||
The input types are
|
||||
|
||||
@table @code
|
||||
@findex pre-prompt
|
||||
@findex prompt
|
||||
@findex post-prompt
|
||||
@item prompt
|
||||
When GDB is prompting for a command (the main GDB prompt).
|
||||
|
||||
@findex pre-commands
|
||||
@findex commands
|
||||
@findex post-commands
|
||||
@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.
|
||||
|
||||
@findex pre-overload-choice
|
||||
@findex overload-choice
|
||||
@findex post-overload-choice
|
||||
@item overload-choice
|
||||
When GDB wants the user to select between various overloaded functions.
|
||||
|
||||
@findex pre-query
|
||||
@findex query
|
||||
@findex post-query
|
||||
@item query
|
||||
When GDB wants the user to confirm a potentially dangerous operation.
|
||||
|
||||
@findex pre-prompt-for-continue
|
||||
@findex prompt-for-continue
|
||||
@findex post-prompt-for-continue
|
||||
@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
|
||||
@ -282,12 +484,14 @@ presence of annotations.
|
||||
@node Errors
|
||||
@chapter Errors
|
||||
|
||||
@findex quit
|
||||
@example
|
||||
^Z^Zquit
|
||||
@end example
|
||||
|
||||
This annotation occurs right before GDB responds to an interrupt.
|
||||
|
||||
@findex error
|
||||
@example
|
||||
^Z^Zerror
|
||||
@end example
|
||||
@ -302,6 +506,7 @@ 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.
|
||||
|
||||
@findex error-begin
|
||||
A quit or error annotation may be preceded by
|
||||
|
||||
@example
|
||||
@ -320,6 +525,8 @@ Warning messages are not yet annotated.
|
||||
|
||||
The output from the @code{info breakpoints} command is annotated as follows:
|
||||
|
||||
@findex breakpoints-headers
|
||||
@findex breakpoints-table
|
||||
@example
|
||||
^Z^Zbreakpoints-headers
|
||||
@var{header-entry}
|
||||
@ -333,6 +540,8 @@ 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
|
||||
@example
|
||||
^Z^Zrecord
|
||||
^Z^Zfield 0
|
||||
@ -359,6 +568,7 @@ of:
|
||||
|
||||
The output ends with
|
||||
|
||||
@findex breakpoints-table-end
|
||||
@example
|
||||
^Z^Zbreakpoints-table-end
|
||||
@end example
|
||||
@ -370,20 +580,92 @@ The following annotations say that certain pieces of state may have
|
||||
changed.
|
||||
|
||||
@table @code
|
||||
@findex frames-invalid
|
||||
@item ^Z^Zframes-invalid
|
||||
|
||||
The frames (for example, output from the @code{backtrace} command) may
|
||||
have changed.
|
||||
|
||||
@findex breakpoints-invalid
|
||||
@item ^Z^Zbreakpoints-invalid
|
||||
|
||||
The breakpoints may have changed. For example, the user just added or
|
||||
deleted a breakpoint.
|
||||
@end table
|
||||
|
||||
@node Running
|
||||
@chapter Running the Program
|
||||
|
||||
@findex starting
|
||||
@findex stopping
|
||||
When the program starts executing due to a GDB command such as
|
||||
@code{step} or @code{continue},
|
||||
|
||||
@example
|
||||
^Z^Zstarting
|
||||
@end example
|
||||
|
||||
is output. When the program stops,
|
||||
|
||||
@example
|
||||
^Z^Zstopped
|
||||
@end example
|
||||
|
||||
is output. Before the @code{stopped} annotation, a variety of
|
||||
annotations describe how the program stopped.
|
||||
|
||||
@table @code
|
||||
@findex exited
|
||||
@item ^Z^Zexited @var{exit-status}
|
||||
The program exited, and @var{exit-status} is the exit status (zero for
|
||||
successful exit, otherwise nonzero).
|
||||
|
||||
@findex signalled
|
||||
@findex signal-name
|
||||
@findex signal-name-end
|
||||
@findex signal-string
|
||||
@findex signal-string-end
|
||||
@item ^Z^Zsignalled
|
||||
The program exited with a signal. After the @code{^Z^Zsignalled}, the
|
||||
annotation continues:
|
||||
|
||||
@example
|
||||
@var{intro-text}
|
||||
^Z^Zsignal-name
|
||||
@var{name}
|
||||
^Z^Zsignal-name-end
|
||||
@var{middle-text}
|
||||
^Z^Zsignal-string
|
||||
@var{string}
|
||||
^Z^Zsignal-string-end
|
||||
@var{end-text}
|
||||
@end example
|
||||
|
||||
where @var{name} is the name of the signal, such as @code{SIGILL} or
|
||||
@code{SIGSEGV}, and @var{string} is the explanation of the signal, such
|
||||
as @code{Illegal Instruction} or @code{Segmentation fault}.
|
||||
@var{intro-text}, @var{middle-text}, and @var{end-text} are for the
|
||||
user's benefit and have no particular format.
|
||||
|
||||
@findex signal
|
||||
@item ^Z^Zsignal
|
||||
The syntax of this annotation is just like @code{signalled}, but GDB is
|
||||
just saying that the program received the signal, not that it was
|
||||
terminated with it.
|
||||
|
||||
@findex breakpoint
|
||||
@item ^Z^Zbreakpoint @var{number}
|
||||
The program hit breakpoint number @var{number}.
|
||||
|
||||
@findex watchpoint
|
||||
@item ^Z^Zwatchpoint @var{number}
|
||||
The program hit watchpoint number @var{number}.
|
||||
@end table
|
||||
|
||||
@node Source
|
||||
@chapter Displaying Source
|
||||
|
||||
@findex source
|
||||
The following annotation is used instead of displaying source code:
|
||||
|
||||
@example
|
||||
@ -400,4 +682,9 @@ 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.
|
||||
|
||||
@node Index
|
||||
@unnumbered Index
|
||||
|
||||
@printindex fn
|
||||
|
||||
@bye
|
||||
|
||||
Loading…
Reference in New Issue
Block a user