diff options
Diffstat (limited to 'contrib/gdb/gdb/doc/annotate.texi')
| -rw-r--r-- | contrib/gdb/gdb/doc/annotate.texi | 400 |
1 files changed, 212 insertions, 188 deletions
diff --git a/contrib/gdb/gdb/doc/annotate.texi b/contrib/gdb/gdb/doc/annotate.texi index 9d5850d..59d599b 100644 --- a/contrib/gdb/gdb/doc/annotate.texi +++ b/contrib/gdb/gdb/doc/annotate.texi @@ -1,85 +1,83 @@ -\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 +@c \input texinfo @c -*-texinfo-*- +@c @c %**start of header +@c @setfilename annotate.info +@c @settitle GDB Annotations +@c @setchapternewpage off +@c @c %**end of header + +@c @set EDITION 0.5 +@c @set DATE May 1994 + +@c @ifinfo +@c This file documents GDB annotations. + +@c This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB +@c Annotations}. Copyright 1994,1995,2000,2001 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.1 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +@c and with the Back-Cover Texts as in (a) below. + +@c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +@c this GNU Manual, like GNU software. Copies published by the Free +@c Software Foundation raise funds for GNU development.'' +@c @end ifinfo + +@c @titlepage +@c @title GDB Annotations +@c @subtitle Edition @value{EDITION} +@c @subtitle @value{DATE} +@c @author Cygnus Support +@c @page +@c @vskip 0pt plus 1filll +@c Permission is granted to make and distribute verbatim copies of +@c this manual provided the copyright notice and this permission notice +@c are preserved on all copies. + +@c Copyright @copyright{} 1994,1995,2000,2001 Free Software Foundation +@c @end titlepage + +@c @ifinfo +@c @node Top +@c @top GDB Annotations + +@c @syncodeindex fn cp + +@node Annotations +@chapter @value{GDBN} Annotations + +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 This is Edition @value{EDITION}, @value{DATE}. +@end ignore @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. +* Annotations Overview:: What annotations are; the general syntax. +* Server Prefix:: Issuing a command without affecting user state. +* Value Annotations:: Values are marked as such. +* Frame Annotations:: Stack frames are annotated. +* Displays:: @value{GDBN} can be told to display something periodically. +* Prompting:: Annotations marking @value{GDBN}'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. +* Annotations for Running:: + Whether the program is running, how it stopped, etc. +* Source Annotations:: 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? +@node Annotations Overview +@section What is an Annotation? +@cindex annotations -To produce annotations, start GDB with the @code{--annotate=2} option. +To produce annotations, start @value{GDBN} 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 @@ -90,20 +88,25 @@ 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. +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 GDB with annotations is: +A simple example of starting up @value{GDBN} with annotations is: -@example +@smallexample $ 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. +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. +Type "show copying" to see the conditions. +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 (gdb) @@ -112,30 +115,33 @@ quit ^Z^Zpost-prompt $ -@end example +@end smallexample -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. +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 -@chapter The Server Prefix +@node Server Prefix +@section The Server Prefix +@cindex server prefix for annotations -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. +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, use the @code{output} command instead of the @code{print} command. -@node Values -@chapter Values +@node Value Annotations +@section Values -When a value is printed in various contexts, GDB uses annotations to -delimit the value from the surrounding text. +@cindex annotations for values +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 @@ -143,14 +149,15 @@ 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 +@noindent 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 @@ -162,20 +169,20 @@ 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 @findex arg-value @findex arg-end -When GDB prints an argument to a function (for example, in the output +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 @@ -183,8 +190,9 @@ 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 +@noindent 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 @@ -195,9 +203,9 @@ for the user's benefit (such as @samp{=}), and @var{value-flags} and @findex field-name-end @findex field-value @findex field-end -When printing a structure, GDB annotates it as follows: +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 @@ -205,42 +213,44 @@ When printing a structure, GDB annotates it as follows: ^Z^Zfield-value @var{the-value} ^Z^Zfield-end -@end example +@end smallexample +@noindent 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: +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 +@noindent 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 +@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 @@ -253,25 +263,27 @@ 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 Frames -@chapter Frames +@node Frame Annotations +@section Frames -Whenever GDB prints a frame, it annotates it. For example, this applies -to frames printed when GDB stops, output from commands such as +@cindex annotations for frames +Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies +to frames printed when @value{GDBN} stops, output from commands such as @code{backtrace} or @code{up}, etc. @findex frame-begin The frame annotation begins with -@example +@smallexample ^Z^Zframe-begin @var{level} @var{address} @var{level-string} -@end example +@end smallexample +@noindent 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 @@ -280,9 +292,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 @@ -290,21 +302,21 @@ 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 GDB to a +that this frame is associated with a function call made by @value{GDBN} to a 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 @@ -319,12 +331,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 @@ -337,17 +349,17 @@ 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 to the frame, with parentheses around them (each argument is annotated -individually as well @pxref{Values}). +individually as well, @pxref{Value Annotations}). @findex frame-source-begin @findex frame-source-file @@ -356,7 +368,7 @@ individually as well @pxref{Values}). @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 @@ -366,7 +378,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 @@ -374,24 +386,24 @@ 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 +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 -@code{source} annotation (@pxref{Source}) is displayed. Unlike most -annotations, this is output instead of the normal text which would be +@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 +@section Displays @findex display-begin @findex display-number-end @@ -400,10 +412,11 @@ output, not in addition. @findex display-expression-end @findex display-value @findex display-end -When GDB is told to display something using the @code{display} command, +@cindex annotations for display +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 @@ -417,8 +430,9 @@ the results of the display are annotated: ^Z^Zdisplay-value @var{value} ^Z^Zdisplay-end -@end example +@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 @@ -428,9 +442,10 @@ 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 +@section Annotation for @value{GDBN} Input -When GDB prompts for input, it annotates this fact so it is possible +@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. @@ -442,11 +457,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 @@ -455,68 +470,69 @@ The input types are @findex prompt @findex post-prompt @item prompt -When GDB is prompting for a command (the main GDB 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 GDB prompts for a set of commands, like in the @code{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 GDB wants the user to select between various overloaded functions. +When @value{GDBN} 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. +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 GDB is asking the user to press return to continue. Note: Don't +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 +@section Errors +@cindex annotations for errors, warnings and interrupts @findex quit -@example +@smallexample ^Z^Zquit -@end example +@end smallexample -This annotation occurs right before GDB responds to an interrupt. +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 GDB responds to an error. +This annotation occurs right before @value{GDBN} responds to an error. -Quit and error annotations indicate that any annotations which GDB was +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 GDB is immediately returning all the way +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 -@example +@smallexample ^Z^Zerror-begin -@end example +@end smallexample Any output between that and the quit or error annotation is the error message. @@ -526,18 +542,20 @@ Warning messages are not yet annotated. @c range_error(), and possibly other places. @node Breakpoint Info -@chapter Information on Breakpoints +@section Information on Breakpoints +@cindex annotations for breakpoints 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 +@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 @@ -547,7 +565,7 @@ of: @findex record @findex field -@example +@smallexample ^Z^Zrecord ^Z^Zfield 0 @var{number} @@ -569,7 +587,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. @@ -577,13 +595,14 @@ 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 -@chapter Invalidation Notices +@section Invalidation Notices +@cindex annotations for invalidation messages The following annotations say that certain pieces of state may have changed. @@ -601,23 +620,24 @@ The breakpoints may have changed. For example, the user just added or deleted a breakpoint. @end table -@node Running -@chapter Running the Program +@node Annotations for Running +@section Running the Program +@cindex annotations for running programs @findex starting @findex stopping -When the program starts executing due to a GDB command such as +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. @@ -637,7 +657,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} @@ -647,8 +667,9 @@ annotation continues: @var{string} ^Z^Zsignal-string-end @var{end-text} -@end example +@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}. @@ -657,7 +678,7 @@ 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 +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. @@ -670,15 +691,16 @@ The program hit breakpoint number @var{number}. The program hit watchpoint number @var{number}. @end table -@node Source -@chapter Displaying Source +@node Source Annotations +@section Displaying Source +@cindex annotations for source display @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 @@ -693,7 +715,7 @@ 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 +@section Annotations We Might Want in the Future @format - target-invalid @@ -709,9 +731,11 @@ depend on the language). notices. @end format +@ignore @node Index @unnumbered Index @printindex fn +@end ignore -@bye +@c @bye |
