From f710410bf9cfca2eea187eb9d114325a45f59575 Mon Sep 17 00:00:00 2001 From: Jim Kingdon Date: Thu, 5 May 1994 04:25:03 +0000 Subject: [PATCH] * annotate.texi: Change edition to 0.5 and date to May 1994. Add index. (Frames): New node, for frame annotation. (Displays): New node, for display annotation. --- gdb/doc/ChangeLog | 5 + gdb/doc/annotate.texi | 293 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 295 insertions(+), 3 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 35c01ca9c71..b17deb5688a 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,5 +1,10 @@ Wed May 4 06:26:11 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + * annotate.texi: Change edition to 0.5 and date to May 1994. + Add index. + (Frames): New node, for frame annotation. + (Displays): New node, for display annotation. + * remote.texi (MIPS Remote): Say that set timeout doesn't apply when waiting for your program to stop. diff --git a/gdb/doc/annotate.texi b/gdb/doc/annotate.texi index b05657febde..e4f085b8287 100644 --- a/gdb/doc/annotate.texi +++ b/gdb/doc/annotate.texi @@ -5,8 +5,8 @@ @setchapternewpage off @c %**end of header -@set EDITION 0.4 -@set DATE April 1994 +@set EDITION 0.5 +@set DATE May 1994 @ifinfo This file documents GDB annotations. @@ -63,11 +63,15 @@ This is Edition @value{EDITION}, @value{DATE}. * General:: What annotations are; the general syntax. * Server:: Issuing a command without affecting user state. * Values:: Values are marked as such. -* Prompting:: GDB annotations marking GDB's need for input. +* 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. +* Index:: Index @end menu @end ifinfo @@ -132,6 +136,9 @@ use the @code{output} command instead of the @code{print} command. 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 @@ -149,6 +156,8 @@ 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: @@ -158,6 +167,10 @@ or it is printed with the @code{output} command), the annotation is similar: ^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: @@ -177,6 +190,10 @@ 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 @@ -205,6 +222,7 @@ 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} @@ -213,6 +231,8 @@ of elements, where is element can be either a single element: or a repeated element +@findex elt-rep +@findex elt-rep-end @example @samp{,} @var{whitespace} ; @r{omitted for the first element} @var{the-value} @@ -228,6 +248,7 @@ 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 @@ -235,6 +256,172 @@ ended with ^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. 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), 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 @@ -259,19 +446,34 @@ features the following annotations: 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 @@ -282,12 +484,14 @@ presence of annotations. @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 @@ -302,6 +506,7 @@ 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 @@ -320,6 +525,8 @@ Warning messages are not yet annotated. 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} @@ -333,6 +540,8 @@ 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 @@ -359,6 +568,7 @@ of: The output ends with +@findex breakpoints-table-end @example ^Z^Zbreakpoints-table-end @end example @@ -370,20 +580,92 @@ 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 @@ -400,4 +682,9 @@ 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. +@node Index +@unnumbered Index + +@printindex fn + @bye -- 2.30.2