* gdb.texinfo: Update dates, bump to Eighth Edition (note
expectation of additional changes before release), update ISBN, add copy of top-level menu for @ifhtml, remove explicit node links, rephrase and/or shorten lines to fix formatting problem in both regular and @smallbook formats. * annotate.texi: Shorten lines in example, use smallexample consistently everywhere. * Makefile.in: Add comment about texinfo 4.0 html generation. (SFILES_INCLUDED): Add annotate.texi.
This commit is contained in:
Stan Shebs
parent
f25d2425f4
commit
6d2ebf8bcc
4 changed files with 432 additions and 328 deletions
|
|
@ -1,3 +1,15 @@
|
|||
2000-03-28 Stan Shebs <shebs@apple.com>
|
||||
|
||||
* gdb.texinfo: Update dates, bump to Eighth Edition (note
|
||||
expectation of additional changes before release), update
|
||||
ISBN, add copy of top-level menu for @ifhtml, remove explicit
|
||||
node links, rephrase and/or shorten lines to fix formatting
|
||||
problem in both regular and @smallbook formats.
|
||||
* annotate.texi: Shorten lines in example, use smallexample
|
||||
consistently everywhere.
|
||||
* Makefile.in: Add comment about texinfo 4.0 html generation.
|
||||
(SFILES_INCLUDED): Add annotate.texi.
|
||||
|
||||
2000-03-27 Daniel Berlin <dan@cgsoftware.com>
|
||||
|
||||
* gdb.texinfo (Debugging Output): Added new section, documenting
|
||||
|
|
|
|||
|
|
@ -40,6 +40,10 @@ TEXIDIR=${gdbdir}/../texinfo
|
|||
# where to find makeinfo, preferably one designed for texinfo-2
|
||||
MAKEINFO=makeinfo
|
||||
|
||||
# Note that texinfo 4.0's makeinfo --html can only generate a
|
||||
# single file, which would be too large, so continue to use
|
||||
# texi2html. -sts 2000-03-28
|
||||
|
||||
MAKEHTML = texi2html
|
||||
MAKEHTMLFLAGS = -glossary -menu -split_chapter
|
||||
|
||||
|
|
@ -83,7 +87,7 @@ TEXINDEX = texindex
|
|||
DVIPS = dvips
|
||||
|
||||
# Main GDB manual's source files
|
||||
SFILES_INCLUDED = gdb-cfg.texi
|
||||
SFILES_INCLUDED = gdb-cfg.texi $(srcdir)/annotate.texi
|
||||
|
||||
SFILES_LOCAL = $(srcdir)/gdb.texinfo GDBvn.texi $(SFILES_INCLUDED)
|
||||
|
||||
|
|
|
|||
|
|
@ -60,9 +60,9 @@
|
|||
@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
|
||||
|
|
@ -100,10 +100,11 @@ 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 @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:
|
||||
|
||||
|
|
@ -111,10 +112,12 @@ 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
|
||||
|
|
@ -126,19 +129,20 @@ quit
|
|||
$
|
||||
@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,
|
||||
|
|
@ -148,8 +152,8 @@ use the @code{output} command instead of the @code{print} command.
|
|||
@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
|
||||
|
|
@ -157,13 +161,13 @@ delimit the value from the surrounding text.
|
|||
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
|
||||
|
|
@ -176,11 +180,11 @@ a value which can be dereferenced and @samp{-} for a value which cannot.
|
|||
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
|
||||
|
|
@ -189,7 +193,7 @@ or it is printed with the @code{output} command), the annotation is similar:
|
|||
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
|
||||
|
|
@ -197,7 +201,7 @@ from the @code{backtrace} command), it annotates it as follows:
|
|||
^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
|
||||
|
|
@ -211,7 +215,7 @@ for the user's benefit (such as @samp{=}), and @var{value-flags} and
|
|||
@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
|
||||
|
|
@ -219,7 +223,7 @@ When printing a structure, @value{GDBN} annotates it as follows:
|
|||
^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
|
||||
|
|
@ -228,9 +232,9 @@ same meanings as in a @code{value-history-begin} annotation.
|
|||
|
||||
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
|
||||
|
|
@ -238,23 +242,23 @@ 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
|
||||
|
|
@ -267,9 +271,9 @@ user that repitition is being depicted.
|
|||
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
|
||||
|
|
@ -282,10 +286,10 @@ to frames printed when @value{GDBN} stops, output from commands such as
|
|||
@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
|
||||
|
|
@ -295,9 +299,9 @@ designed to convey the level to the user. @var{address} is in the form
|
|||
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
|
||||
|
|
@ -305,10 +309,10 @@ 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
|
||||
|
|
@ -316,10 +320,10 @@ function in the program being debugged.
|
|||
|
||||
@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
|
||||
|
|
@ -334,12 +338,12 @@ A normal frame.
|
|||
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
|
||||
|
|
@ -352,12 +356,12 @@ benefit.
|
|||
@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
|
||||
|
|
@ -371,7 +375,7 @@ individually as well, @pxref{Value Annotations}).
|
|||
@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
|
||||
|
|
@ -381,7 +385,7 @@ If source information is available, a reference to it is then printed:
|
|||
^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
|
||||
|
|
@ -393,10 +397,10 @@ 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
|
||||
@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
|
||||
|
|
@ -419,7 +423,7 @@ output, not in addition.
|
|||
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
|
||||
|
|
@ -433,7 +437,7 @@ the results of the display are annotated:
|
|||
^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,
|
||||
|
|
@ -459,11 +463,11 @@ 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
|
||||
@smallexample
|
||||
^Z^Zpre-prompt
|
||||
^Z^Zprompt
|
||||
^Z^Zpost-prompt
|
||||
@end example
|
||||
@end smallexample
|
||||
|
||||
The input types are
|
||||
|
||||
|
|
@ -508,16 +512,16 @@ presence of annotations.
|
|||
@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.
|
||||
|
||||
|
|
@ -532,9 +536,9 @@ to the top level.
|
|||
@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.
|
||||
|
|
@ -551,11 +555,11 @@ The output from the @code{info breakpoints} command is annotated as follows:
|
|||
|
||||
@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
|
||||
|
|
@ -566,7 +570,7 @@ of:
|
|||
|
||||
@findex record
|
||||
@findex field
|
||||
@example
|
||||
@smallexample
|
||||
^Z^Zrecord
|
||||
^Z^Zfield 0
|
||||
@var{number}
|
||||
|
|
@ -588,7 +592,7 @@ of:
|
|||
@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.
|
||||
|
|
@ -596,9 +600,9 @@ 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
|
||||
|
|
@ -630,15 +634,15 @@ deleted a breakpoint.
|
|||
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.
|
||||
|
|
@ -658,7 +662,7 @@ successful exit, otherwise nonzero).
|
|||
The program exited with a signal. After the @code{^Z^Zsignalled}, the
|
||||
annotation continues:
|
||||
|
||||
@example
|
||||
@smallexample
|
||||
@var{intro-text}
|
||||
^Z^Zsignal-name
|
||||
@var{name}
|
||||
|
|
@ -668,7 +672,7 @@ annotation continues:
|
|||
@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
|
||||
|
|
@ -698,9 +702,9 @@ The program hit watchpoint number @var{number}.
|
|||
@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
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
Loading…
Reference in a new issue