Initial creation of sourceware repository

1 files changed, 0 insertions, 717 deletions

diff --git a/gdb/doc/annotate.texi b/gdb/doc/annotate.texi
deleted file mode 100644
index 9d5850d..0000000
--- a/gdb/doc/annotate.texi
+++ /dev/null
@@ -1,717 +0,0 @@
-\input texinfo   @c -*-texinfo-*-
-@c %**start of header
-@setfilename annotate.info
-@settitle GDB Annotations
-@setchapternewpage off
-@c %**end of header
-
-@set EDITION 0.5
-@set DATE May 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}
-@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.
-
-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.
-* 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.
-* TODO::                Annotations which might be added in the future.
-* Index::               Index
-@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.
-
-@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
-
-@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.
-
-@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:
-
-@example
-^Z^Zvalue-begin @var{value-flags}
-@var{the-value}
-^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:
-
-@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.
-
-@findex field-begin
-@findex field-name-end
-@findex field-value
-@findex field-end
-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:
-
-@findex elt
-@example
-@samp{,} @var{whitespace}         ; @r{omitted for the first element}
-@var{the-value}
-^Z^Zelt
-@end example
-
-or a repeated element
-
-@findex elt-rep
-@findex elt-rep-end
-@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.
-
-@findex array-section-end
-Once all the array elements have been output, the array annotation is
-ended with
-
-@example
-^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.  @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 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, 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{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
-
-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
-@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
-prompting.  This is because the counting of lines is buggy in the
-presence of annotations.
-@end table
-
-@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
-
-This annotation occurs right before GDB responds to an error.
-
-Quit and error annotations indicate that any annotations which GDB 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
-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
-
-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}
-^Z^Zbreakpoints-table
-@end example
-
-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{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
-
-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
-
-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
-^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.  @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
-@chapter 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 Index
-@unnumbered Index
-
-@printindex fn
-
-@bye