annotate.texinfo

这个是LINUX下的GDB调度工具的源码

@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
@chapter Displays

@emph{Display Annotations have been removed.  @sc{gdb/mi} instead
provides Variable Objects.}

@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
@chapter Annotation for @value{GDBN} Input

@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.

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:

@smallexample
^Z^Zpre-prompt
^Z^Zprompt
^Z^Zpost-prompt
@end smallexample

The input types are

@table @code
@findex pre-prompt
@findex prompt
@findex post-prompt
@item 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 @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 @value{GDBN} wants the user to select between various overloaded functions.

@findex pre-query
@findex query
@findex post-query
@item query
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 @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
@cindex annotations for errors, warnings and interrupts

@findex quit
@smallexample
^Z^Zquit
@end smallexample

This annotation occurs right before @value{GDBN} responds to an interrupt.

@findex error
@smallexample
^Z^Zerror
@end smallexample

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

@smallexample
^Z^Zerror-begin
@end smallexample

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

@emph{Breakpoint Annotations have been removed.  @sc{gdb/mi} instead
provides breakpoint commands.}

@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
@chapter 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 Annotations for Running
@chapter 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}, 

@smallexample
^Z^Zstarting
@end smallexample

is output.  When the program stops, 

@smallexample
^Z^Zstopped
@end smallexample

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:

@smallexample
@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 smallexample

@noindent
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
@chapter Displaying Source
@cindex annotations for source display

@findex source
The following annotation is used instead of displaying source code:

@smallexample
^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
@end smallexample

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).

@raisesections
@include fdl.texi
@lowersections

@ignore
@node Index
@unnumbered Index

@printindex fn
@end ignore

@bye