diff options
Diffstat (limited to 'gdb/doc/annotate.texi')
| -rw-r--r-- | gdb/doc/annotate.texi | 717 |
1 files changed, 717 insertions, 0 deletions
diff --git a/gdb/doc/annotate.texi b/gdb/doc/annotate.texi new file mode 100644 index 00000000000..9d5850dbf21 --- /dev/null +++ b/gdb/doc/annotate.texi @@ -0,0 +1,717 @@ +\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 |