@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
+This chapter describes annotations in @value{GDBN}. 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
cannot contain newline characters.
Any output not beginning with a newline and two @samp{control-z}
-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.
+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 @value{GDBN} with annotations is:
$ gdb --annotate=2
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.
+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.
+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
$
@end smallexample
-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 @value{GDBN}.
+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 @value{GDBN}.
@node Server Prefix
@section The Server Prefix
@cindex server prefix for annotations
-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
-@value{GDBN}'s notion of which command to repeat if @key{RET} is pressed on a
-line by itself.
+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 @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,
@section Values
@cindex annotations for values
-When a value is printed in various contexts, @value{GDBN} uses annotations to
-delimit the value from the surrounding text.
+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
If a value is printed using @code{print} and added to the value history,
the annotation looks like
-@example
+@smallexample
^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
+@end smallexample
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
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
+@smallexample
^Z^Zvalue-begin @var{value-flags}
@var{the-value}
^Z^Zvalue-end
-@end example
+@end smallexample
@findex arg-begin
@findex arg-name-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
+@smallexample
^Z^Zarg-begin
@var{argument-name}
^Z^Zarg-name-end
^Z^Zarg-value @var{value-flags}
@var{the-value}
^Z^Zarg-end
-@end example
+@end smallexample
where @var{argument-name} is the name of the argument,
@var{separator-string} is text which separates the name from the value
@findex field-end
When printing a structure, @value{GDBN} annotates it as follows:
-@example
+@smallexample
^Z^Zfield-begin @var{value-flags}
@var{field-name}
^Z^Zfield-name-end
^Z^Zfield-value
@var{the-value}
^Z^Zfield-end
-@end example
+@end smallexample
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
When printing an array, @value{GDBN} annotates it as follows:
-@example
+@smallexample
^Z^Zarray-section-begin @var{array-index} @var{value-flags}
-@end example
+@end smallexample
where @var{array-index} is the index of the first element being
annotated and @var{value-flags} has the same meaning as in a
of elements, where is element can be either a single element:
@findex elt
-@example
+@smallexample
@samp{,} @var{whitespace} ; @r{omitted for the first element}
@var{the-value}
^Z^Zelt
-@end example
+@end smallexample
or a repeated element
@findex elt-rep
@findex elt-rep-end
-@example
+@smallexample
@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
+@end smallexample
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
Once all the array elements have been output, the array annotation is
ended with
-@example
+@smallexample
^Z^Zarray-section-end
-@end example
+@end smallexample
@node Frame Annotations
@section Frames
@findex frame-begin
The frame annotation begins with
-@example
+@smallexample
^Z^Zframe-begin @var{level} @var{address}
@var{level-string}
-@end example
+@end smallexample
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
does not depend on the language). The frame ends with
@findex frame-end
-@example
+@smallexample
^Z^Zframe-end
-@end example
+@end smallexample
Between these annotations is the main body of the frame, which can
consist of
@itemize @bullet
@item
@findex function-call
-@example
+@smallexample
^Z^Zfunction-call
@var{function-call-string}
-@end example
+@end smallexample
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
@item
@findex signal-handler-caller
-@example
+@smallexample
^Z^Zsignal-handler-caller
@var{signal-handler-caller-string}
-@end example
+@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
This can optionally (depending on whether this is thought of as
interesting information for the user to see) begin with
-@example
+@smallexample
^Z^Zframe-address
@var{address}
^Z^Zframe-address-end
@var{separator-string}
-@end example
+@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
@findex frame-args
Then comes
-@example
+@smallexample
^Z^Zframe-function-name
@var{function-name}
^Z^Zframe-args
@var{arguments}
-@end example
+@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
@findex frame-source-end
If source information is available, a reference to it is then printed:
-@example
+@smallexample
^Z^Zframe-source-begin
@var{source-intro-string}
^Z^Zframe-source-file
^Z^Zframe-source-line
@var{line-number}
^Z^Zframe-source-end
-@end example
+@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
library, which load segment, etc.; currently only done on the RS/6000),
it is annotated with
-@example
+@smallexample
^Z^Zframe-where
@var{information}
-@end example
+@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
When @value{GDBN} is told to display something using the @code{display} command,
the results of the display are annotated:
-@example
+@smallexample
^Z^Zdisplay-begin
@var{number}
^Z^Zdisplay-number-end
^Z^Zdisplay-value
@var{value}
^Z^Zdisplay-end
-@end example
+@end smallexample
where @var{number} is the number of the display, @var{number-separator}
is intended to separate the number from what follows for the user,
associated with the input. For example, the @code{prompt} input type
features the following annotations:
-@example
+@smallexample
^Z^Zpre-prompt
^Z^Zprompt
^Z^Zpost-prompt
-@end example
+@end smallexample
The input types are
@cindex annotations for errors, warnings and interrupts
@findex quit
-@example
+@smallexample
^Z^Zquit
-@end example
+@end smallexample
This annotation occurs right before @value{GDBN} responds to an interrupt.
@findex error
-@example
+@smallexample
^Z^Zerror
-@end example
+@end smallexample
This annotation occurs right before @value{GDBN} responds to an error.
@findex error-begin
A quit or error annotation may be preceded by
-@example
+@smallexample
^Z^Zerror-begin
-@end example
+@end smallexample
Any output between that and the quit or error annotation is the error
message.
@findex breakpoints-headers
@findex breakpoints-table
-@example
+@smallexample
^Z^Zbreakpoints-headers
@var{header-entry}
^Z^Zbreakpoints-table
-@end example
+@end smallexample
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
@findex record
@findex field
-@example
+@smallexample
^Z^Zrecord
^Z^Zfield 0
@var{number}
@var{ignore-count}
^Z^Zfield 9
@var{commands}
-@end example
+@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
-@example
+@smallexample
^Z^Zbreakpoints-table-end
-@end example
+@end smallexample
@node Invalidation
@section Invalidation Notices
When the program starts executing due to a @value{GDBN} command such as
@code{step} or @code{continue},
-@example
+@smallexample
^Z^Zstarting
-@end example
+@end smallexample
is output. When the program stops,
-@example
+@smallexample
^Z^Zstopped
-@end example
+@end smallexample
is output. Before the @code{stopped} annotation, a variety of
annotations describe how the program stopped.
The program exited with a signal. After the @code{^Z^Zsignalled}, the
annotation continues:
-@example
+@smallexample
@var{intro-text}
^Z^Zsignal-name
@var{name}
@var{string}
^Z^Zsignal-string-end
@var{end-text}
-@end example
+@end smallexample
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
@findex source
The following annotation is used instead of displaying source code:
-@example
+@smallexample
^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
-@end example
+@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
projects / thirdparty / binutils-gdb.git / blobdiff