mirror of
https://github.com/bminor/binutils-gdb.git
synced 2025-12-27 17:40:49 +00:00
* gdb.texinfo (main menu): Add Annotations.
(File Options): Add @cindex entries for each command-line option.
Document --epoch, --annotate, --async, --interpreter, --write,
--statistics, and --version.
* annotate.texi: Convert to a chapter. Use @value{GDBN} instead
of GDB.
This commit is contained in:
Eli Zaretskii
@@ -1,85 +1,93 @@
|
||||
\input texinfo @c -*-texinfo-*-
|
||||
@c %**start of header
|
||||
@setfilename annotate.info
|
||||
@settitle GDB Annotations
|
||||
@setchapternewpage off
|
||||
@c %**end of header
|
||||
@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
|
||||
|
||||
@set EDITION 0.5
|
||||
@set DATE May 1994
|
||||
@c @set EDITION 0.5
|
||||
@c @set DATE May 1994
|
||||
|
||||
@ifinfo
|
||||
This file documents GDB annotations.
|
||||
@c @ifinfo
|
||||
@c This file documents GDB annotations.
|
||||
|
||||
This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB
|
||||
Annotations}. Copyright 1994 Free Software Foundation
|
||||
@c This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB
|
||||
@c 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.
|
||||
@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
|
||||
|
||||
@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).
|
||||
@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).
|
||||
|
||||
@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.
|
||||
@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.
|
||||
|
||||
Permission is granted to copy and distribute translations of this manual
|
||||
into another language, under the above conditions for modified versions.
|
||||
@end ifinfo
|
||||
@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
|
||||
|
||||
@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.
|
||||
@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.
|
||||
|
||||
Copyright @copyright{} 1994 Free Software Foundation
|
||||
@end titlepage
|
||||
@c Copyright @copyright{} 1994 Free Software Foundation
|
||||
@c @end titlepage
|
||||
|
||||
@ifinfo
|
||||
@node Top
|
||||
@top GDB Annotations
|
||||
@c @ifinfo
|
||||
@c @node Top
|
||||
@c @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
|
||||
@syncodeindex fn cp
|
||||
|
||||
@node Annotations
|
||||
@chapter @value{GDBN} Annotations
|
||||
|
||||
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.
|
||||
* Frames:: Stack frames are annotated.
|
||||
* Displays:: GDB can be told to display something periodically.
|
||||
* Prompting:: 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.
|
||||
* Running:: Whether the program is running, how it stopped, etc.
|
||||
* 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.
|
||||
* Index:: Index
|
||||
@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
|
||||
@@ -90,20 +98,22 @@ 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,
|
||||
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)
|
||||
@@ -112,29 +122,31 @@ quit
|
||||
|
||||
^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
|
||||
@@ -172,7 +184,7 @@ or it is printed with the @code{output} command), the annotation is similar:
|
||||
@findex arg-name-end
|
||||
@findex arg-value
|
||||
@findex arg-end
|
||||
When GDB prints an argument to a function (for example, in the output
|
||||
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
|
||||
@@ -195,7 +207,7 @@ for the user's benefit (such as @samp{=}), and @var{value-flags} and
|
||||
@findex field-name-end
|
||||
@findex field-value
|
||||
@findex field-end
|
||||
When printing a structure, GDB annotates it as follows:
|
||||
When printing a structure, @value{GDBN} annotates it as follows:
|
||||
|
||||
@example
|
||||
^Z^Zfield-begin @var{value-flags}
|
||||
@@ -212,7 +224,7 @@ 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:
|
||||
When printing an array, @value{GDBN} annotates it as follows:
|
||||
|
||||
@example
|
||||
^Z^Zarray-section-begin @var{array-index} @var{value-flags}
|
||||
@@ -257,11 +269,12 @@ ended with
|
||||
^Z^Zarray-section-end
|
||||
@end example
|
||||
|
||||
@node Frames
|
||||
@chapter Frames
|
||||
@node Frame Annotations
|
||||
@section Frames
|
||||
|
||||
Whenever GDB prints a frame, it annotates it. For example, this applies
|
||||
to frames printed when GDB stops, output from commands such as
|
||||
@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
|
||||
@@ -296,7 +309,7 @@ consist of
|
||||
@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
|
||||
that this frame is associated with a function call made by @value{GDBN} to a
|
||||
function in the program being debugged.
|
||||
|
||||
@item
|
||||
@@ -347,7 +360,7 @@ Then comes
|
||||
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}).
|
||||
individually as well, @pxref{Value Annotations}).
|
||||
|
||||
@findex frame-source-begin
|
||||
@findex frame-source-file
|
||||
@@ -374,7 +387,7 @@ 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
|
||||
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
|
||||
|
||||
@@ -391,7 +404,7 @@ output, not in addition.
|
||||
@end itemize
|
||||
|
||||
@node Displays
|
||||
@chapter Displays
|
||||
@section Displays
|
||||
|
||||
@findex display-begin
|
||||
@findex display-number-end
|
||||
@@ -400,7 +413,8 @@ output, not in addition.
|
||||
@findex display-expression-end
|
||||
@findex display-value
|
||||
@findex display-end
|
||||
When GDB is told to display something using the @code{display} command,
|
||||
@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
|
||||
@@ -428,9 +442,10 @@ 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.
|
||||
|
||||
@@ -455,60 +470,61 @@ The input types are
|
||||
@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}
|
||||
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. Note: Don't
|
||||
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
|
||||
@chapter Errors
|
||||
@section Errors
|
||||
@cindex annotations for errors, warnings and interrupts
|
||||
|
||||
@findex quit
|
||||
@example
|
||||
^Z^Zquit
|
||||
@end example
|
||||
|
||||
This annotation occurs right before GDB responds to an interrupt.
|
||||
This annotation occurs right before @value{GDBN} responds to an interrupt.
|
||||
|
||||
@findex error
|
||||
@example
|
||||
^Z^Zerror
|
||||
@end example
|
||||
|
||||
This annotation occurs right before GDB responds to an error.
|
||||
This annotation occurs right before @value{GDBN} responds to an error.
|
||||
|
||||
Quit and error annotations indicate that any annotations which GDB was
|
||||
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 GDB is immediately returning all the way
|
||||
does not necessarily mean that @value{GDBN} is immediately returning all the way
|
||||
to the top level.
|
||||
|
||||
@findex error-begin
|
||||
@@ -526,8 +542,9 @@ Warning messages are not yet annotated.
|
||||
@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
|
||||
@@ -582,8 +599,9 @@ The output ends with
|
||||
@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.
|
||||
|
||||
@@ -601,12 +619,13 @@ The breakpoints may have changed. For example, the user just added or
|
||||
deleted a breakpoint.
|
||||
@end table
|
||||
|
||||
@node Running
|
||||
@chapter Running the Program
|
||||
@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 GDB command such as
|
||||
When the program starts executing due to a @value{GDBN} command such as
|
||||
@code{step} or @code{continue},
|
||||
|
||||
@example
|
||||
@@ -657,7 +676,7 @@ 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
|
||||
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.
|
||||
|
||||
@@ -670,8 +689,9 @@ The program hit breakpoint number @var{number}.
|
||||
The program hit watchpoint number @var{number}.
|
||||
@end table
|
||||
|
||||
@node Source
|
||||
@chapter Displaying Source
|
||||
@node Source Annotations
|
||||
@section Displaying Source
|
||||
@cindex annotations for source display
|
||||
|
||||
@findex source
|
||||
The following annotation is used instead of displaying source code:
|
||||
@@ -693,7 +713,7 @@ followed by one or more lowercase hex digits (note that this does not
|
||||
depend on the language).
|
||||
|
||||
@node TODO
|
||||
@chapter Annotations We Might Want in the Future
|
||||
@section Annotations We Might Want in the Future
|
||||
|
||||
@format
|
||||
- target-invalid
|
||||
@@ -709,9 +729,11 @@ depend on the language).
|
||||
notices.
|
||||
@end format
|
||||
|
||||
@ignore
|
||||
@node Index
|
||||
@unnumbered Index
|
||||
|
||||
@printindex fn
|
||||
@end ignore
|
||||
|
||||
@bye
|
||||
@c @bye
|
||||
|
||||
Reference in New Issue
Block a user