-\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
+@c \input texinfo @c -*-texinfo-*-
+@c @c %**start of header
+@c @setfilename annotate.info
+@c @settitle GDB Annotations
+@c @setchapternewpage off
+@c @c %**end of header
+
+@c @set EDITION 0.5
+@c @set DATE May 1994
+
+@c @ifinfo
+@c This file documents GDB annotations.
+
+@c This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB
+@c Annotations}. Copyright 1994 Free Software Foundation
+
+@c Permission is granted to make and distribute verbatim copies of
+@c this manual provided the copyright notice and this permission notice
+@c are preserved on all copies.
+@c @end ignore
+
+@c @ignore
+@c Permission is granted to process this file through TeX and print the
+@c results, provided the printed document carries copying permission
+@c notice identical to this one except for the removal of this paragraph
+@c (this paragraph not being relevant to the printed manual).
+
+@c @end ignore
+@c Permission is granted to copy and distribute modified versions of this
+@c manual under the conditions for verbatim copying, provided also that the
+@c entire resulting derived work is distributed under the terms of a
+@c permission notice identical to this one.
+
+@c Permission is granted to copy and distribute translations of this manual
+@c into another language, under the above conditions for modified versions.
+@c @end ifinfo
+
+@c @titlepage
+@c @title GDB Annotations
+@c @subtitle Edition @value{EDITION}
+@c @subtitle @value{DATE}
+@c @author Cygnus Support
+@c @page
+@c @vskip 0pt plus 1filll
+@c Permission is granted to make and distribute verbatim copies of
+@c this manual provided the copyright notice and this permission notice
+@c are preserved on all copies.
+
+@c Copyright @copyright{} 1994 Free Software Foundation
+@c @end titlepage
+
+@c @ifinfo
+@c @node Top
+@c @top GDB Annotations
+
+@syncodeindex fn cp
+
+@ifclear GDBN
+@node Annotations
+@chapter @value{GDBN} Annotations
+@end ifclear
+
+This chapter describes annotations in @value{GDBN}, the GNU symbolic debugger.
+Annotations are 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.
+@ignore
This is Edition @value{EDITION}, @value{DATE}.
+@end ignore
@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.
+* 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.
-* Source:: Annotations describing source code.
+* 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
-@end ifinfo
-@node General
-@chapter What is an Annotation?
+@node Annotations Overview
+@section What is an Annotation?
+@cindex annotations
-To produce annotations, start GDB with the @code{--annotate=2} option.
+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
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,
+characters denotes literal output from @value{GDBN}. Currently there is no need
+for @value{GDBN} 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:
+A simple example of starting up @value{GDBN} with annotations is:
-@example
+@smallexample
$ 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.
+GNU GDB 5.0
+Copyright 2000 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"
^Z^Zpre-prompt
(gdb)
^Z^Zpost-prompt
$
-@end example
+@end smallexample
-Here @samp{quit} is input to GDB; the rest is output from GDB. The three
+Here @samp{quit} is input to @value{GDBN}; the rest is output from @value{GDBN}. The three
lines beginning @samp{^Z^Z} (where @samp{^Z} denotes a @samp{control-z}
-character) are annotations; the rest is output from GDB.
+character) are annotations; the rest is output from @value{GDBN}.
-@node Server
-@chapter The Server Prefix
+@node Server Prefix
+@section The Server Prefix
+@cindex server prefix for annotations
-To issue a command to GDB without affecting certain aspects of the state
+To issue a command to @value{GDBN} 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
+@value{GDBN}'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
+@node Value Annotations
+@section Values
-When a value is printed in various contexts, GDB uses annotations to
+@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
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:
^Z^Zvalue-end
@end example
-When GDB prints an argument to a function (for example, in the output
+@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:
@example
@var{the-value} have the same meanings as in a
@code{value-history-begin} annotation.
-When printing a structure, GDB annotates it as follows:
+@findex field-begin
+@findex field-name-end
+@findex field-value
+@findex field-end
+When printing a structure, @value{GDBN} annotates it as follows:
@example
^Z^Zfield-begin @var{value-flags}
(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:
+When printing an array, @value{GDBN} annotates it as follows:
@example
^Z^Zarray-section-begin @var{array-index} @var{value-flags}
@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}
or a repeated element
+@findex elt-rep
+@findex elt-rep-end
@example
@samp{,} @var{whitespace} ; @r{omitted for the first element}
@var{the-value}
@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
^Z^Zarray-section-end
@end example
+@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
+
+@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. @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
+@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 @value{GDBN} 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, 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
+
+@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{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:
+
+@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 @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
+
+@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
+@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:
+
+@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
+@section Annotation for @value{GDBN} Input
-When GDB prompts for input, it annotates this fact so it is possible
+@cindex annotations for prompts
+When @value{GDBN} 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.
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).
+When @value{GDBN} is prompting for a command (the main @value{GDBN} 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.
+When @value{GDBN} 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.
+When @value{GDBN} 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.
+When @value{GDBN} 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.
+When @value{GDBN} 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 Errors
+@section Errors
+@cindex annotations for errors, warnings and interrupts
+
+@findex quit
+@example
+^Z^Zquit
+@end example
+
+This annotation occurs right before @value{GDBN} responds to an interrupt.
+
+@findex error
+@example
+^Z^Zerror
+@end example
+
+This annotation occurs right before @value{GDBN} responds to an error.
+
+Quit and error annotations indicate that any annotations which @value{GDBN} was
+in the middle of may end abruptly. For example, if a
+@code{value-history-begin} annotation is followed by a @code{error}, one
+cannot expect to receive the matching @code{value-history-end}. One
+cannot expect not to receive it either, however; an error annotation
+does not necessarily mean that @value{GDBN} is immediately returning all the way
+to the top level.
+
+@findex error-begin
+A quit or error annotation may be preceded by
+
+@example
+^Z^Zerror-begin
+@end example
+
+Any output between that and the quit or error annotation is the error
+message.
+
+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
-@chapter Information on Breakpoints
+@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
@example
^Z^Zbreakpoints-headers
-@var{headers}
+@var{header-entry}
^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:
+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
@example
+^Z^Zrecord
^Z^Zfield 0
@var{number}
^Z^Zfield 1
@var{commands}
@end example
+Note that @var{address} is intended for user consumption---the syntax
+varies depending on the language.
+
The output ends with
+@findex breakpoints-table-end
@example
^Z^Zbreakpoints-table-end
@end example
@node Invalidation
-@chapter Invalidation Notices
+@section Invalidation Notices
+@cindex annotations for invalidation messages
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 Source
-@chapter Displaying Source
+@node Annotations for Running
+@section Running the Program
+@cindex annotations for running programs
+@findex starting
+@findex stopping
+When the program starts executing due to a @value{GDBN} 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 @value{GDBN} 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 Annotations
+@section Displaying Source
+@cindex annotations for source display
+
+@findex source
The following annotation is used instead of displaying source code:
@example
@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.
+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
+
+@ignore
+@node Index
+@unnumbered Index
+
+@printindex fn
+@end ignore
-@bye
+@c @bye
projects / deliverable / binutils-gdb.git / blobdiff