1 @c \input texinfo @c -*-texinfo-*-
2 @c @c %**start of header
3 @c @setfilename annotate.info
4 @c @settitle GDB Annotations
5 @c @setchapternewpage off
12 @c This file documents GDB annotations.
14 @c This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB
15 @c Annotations}. Copyright 1994 Free Software Foundation
17 @c Permission is granted to make and distribute verbatim copies of
18 @c this manual provided the copyright notice and this permission notice
19 @c are preserved on all copies.
23 @c Permission is granted to process this file through TeX and print the
24 @c results, provided the printed document carries copying permission
25 @c notice identical to this one except for the removal of this paragraph
26 @c (this paragraph not being relevant to the printed manual).
29 @c Permission is granted to copy and distribute modified versions of this
30 @c manual under the conditions for verbatim copying, provided also that the
31 @c entire resulting derived work is distributed under the terms of a
32 @c permission notice identical to this one.
34 @c Permission is granted to copy and distribute translations of this manual
35 @c into another language, under the above conditions for modified versions.
39 @c @title GDB Annotations
40 @c @subtitle Edition @value{EDITION}
41 @c @subtitle @value{DATE}
42 @c @author Cygnus Support
44 @c @vskip 0pt plus 1filll
45 @c Permission is granted to make and distribute verbatim copies of
46 @c this manual provided the copyright notice and this permission notice
47 @c are preserved on all copies.
49 @c Copyright @copyright{} 1994 Free Software Foundation
54 @c @top GDB Annotations
60 @chapter @value{GDBN} Annotations
63 This chapter describes annotations in @value{GDBN}, the GNU symbolic debugger.
64 Annotations are designed to interface @value{GDBN} to graphical user interfaces
65 or other similar programs which want to interact with @value{GDBN} at a
66 relatively high level.
69 This is Edition @value{EDITION}, @value{DATE}.
73 * Annotations Overview:: What annotations are; the general syntax.
74 * Server Prefix:: Issuing a command without affecting user state.
75 * Value Annotations:: Values are marked as such.
76 * Frame Annotations:: Stack frames are annotated.
77 * Displays:: @value{GDBN} can be told to display something periodically.
78 * Prompting:: Annotations marking @value{GDBN}'s need for input.
79 * Errors:: Annotations for error messages.
80 * Breakpoint Info:: Information on breakpoints.
81 * Invalidation:: Some annotations describe things now invalid.
82 * Annotations for Running::
83 Whether the program is running, how it stopped, etc.
84 * Source Annotations:: Annotations describing source code.
85 * TODO:: Annotations which might be added in the future.
88 @node Annotations Overview
89 @section What is an Annotation?
92 To produce annotations, start @value{GDBN} with the @code{--annotate=2} option.
94 Annotations start with a newline character, two @samp{control-z}
95 characters, and the name of the annotation. If there is no additional
96 information associated with this annotation, the name of the annotation
97 is followed immediately by a newline. If there is additional
98 information, the name of the annotation is followed by a space, the
99 additional information, and a newline. The additional information
100 cannot contain newline characters.
102 Any output not beginning with a newline and two @samp{control-z}
103 characters denotes literal output from @value{GDBN}. Currently there is no need
104 for @value{GDBN} to output a newline followed by two @samp{control-z} characters,
105 but if there was such a need, the annotations could be extended with an
106 @samp{escape} annotation which means those three characters as output.
108 A simple example of starting up @value{GDBN} with annotations is:
113 Copyright 2000 Free Software Foundation, Inc.
114 GDB is free software, covered by the GNU General Public License, and you are
115 welcome to change it and/or distribute copies of it under certain conditions.
116 Type "show copying" to see the conditions.
117 There is absolutely no warranty for GDB. Type "show warranty" for details.
118 This GDB was configured as "sparc-sun-sunos4.1.3"
129 Here @samp{quit} is input to @value{GDBN}; the rest is output from @value{GDBN}. The three
130 lines beginning @samp{^Z^Z} (where @samp{^Z} denotes a @samp{control-z}
131 character) are annotations; the rest is output from @value{GDBN}.
134 @section The Server Prefix
135 @cindex server prefix for annotations
137 To issue a command to @value{GDBN} without affecting certain aspects of the state
138 which is seen by users, prefix it with @samp{server }. This means that
139 this command will not affect the command history, nor will it affect
140 @value{GDBN}'s notion of which command to repeat if @key{RET} is pressed on a
143 The server prefix does not affect the recording of values into the value
144 history; to print a value without recording it into the value history,
145 use the @code{output} command instead of the @code{print} command.
147 @node Value Annotations
150 @cindex annotations for values
151 When a value is printed in various contexts, @value{GDBN} uses annotations to
152 delimit the value from the surrounding text.
154 @findex value-history-begin
155 @findex value-history-value
156 @findex value-history-end
157 If a value is printed using @code{print} and added to the value history,
158 the annotation looks like
161 ^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
163 ^Z^Zvalue-history-value
165 ^Z^Zvalue-history-end
168 where @var{history-number} is the number it is getting in the value
169 history, @var{history-string} is a string, such as @samp{$5 = }, which
170 introduces the value to the user, @var{the-value} is the output
171 corresponding to the value itself, and @var{value-flags} is @samp{*} for
172 a value which can be dereferenced and @samp{-} for a value which cannot.
176 If the value is not added to the value history (it is an invalid float
177 or it is printed with the @code{output} command), the annotation is similar:
180 ^Z^Zvalue-begin @var{value-flags}
189 When @value{GDBN} prints an argument to a function (for example, in the output
190 from the @code{backtrace} command), it annotates it as follows:
196 @var{separator-string}
197 ^Z^Zarg-value @var{value-flags}
202 where @var{argument-name} is the name of the argument,
203 @var{separator-string} is text which separates the name from the value
204 for the user's benefit (such as @samp{=}), and @var{value-flags} and
205 @var{the-value} have the same meanings as in a
206 @code{value-history-begin} annotation.
209 @findex field-name-end
212 When printing a structure, @value{GDBN} annotates it as follows:
215 ^Z^Zfield-begin @var{value-flags}
218 @var{separator-string}
224 where @var{field-name} is the name of the field, @var{separator-string}
225 is text which separates the name from the value for the user's benefit
226 (such as @samp{=}), and @var{value-flags} and @var{the-value} have the
227 same meanings as in a @code{value-history-begin} annotation.
229 When printing an array, @value{GDBN} annotates it as follows:
232 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
235 where @var{array-index} is the index of the first element being
236 annotated and @var{value-flags} has the same meaning as in a
237 @code{value-history-begin} annotation. This is followed by any number
238 of elements, where is element can be either a single element:
242 @samp{,} @var{whitespace} ; @r{omitted for the first element}
247 or a repeated element
252 @samp{,} @var{whitespace} ; @r{omitted for the first element}
254 ^Z^Zelt-rep @var{number-of-repititions}
255 @var{repetition-string}
259 In both cases, @var{the-value} is the output for the value of the
260 element and @var{whitespace} can contain spaces, tabs, and newlines. In
261 the repeated case, @var{number-of-repititons} is the number of
262 consecutive array elements which contain that value, and
263 @var{repetition-string} is a string which is designed to convey to the
264 user that repitition is being depicted.
266 @findex array-section-end
267 Once all the array elements have been output, the array annotation is
271 ^Z^Zarray-section-end
274 @node Frame Annotations
277 @cindex annotations for frames
278 Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
279 to frames printed when @value{GDBN} stops, output from commands such as
280 @code{backtrace} or @code{up}, etc.
283 The frame annotation begins with
286 ^Z^Zframe-begin @var{level} @var{address}
290 where @var{level} is the number of the frame (0 is the innermost frame,
291 and other frames have positive numbers), @var{address} is the address of
292 the code executing in that frame, and @var{level-string} is a string
293 designed to convey the level to the user. @var{address} is in the form
294 @samp{0x} followed by one or more lowercase hex digits (note that this
295 does not depend on the language). The frame ends with
302 Between these annotations is the main body of the frame, which can
307 @findex function-call
310 @var{function-call-string}
313 where @var{function-call-string} is text designed to convey to the user
314 that this frame is associated with a function call made by @value{GDBN} to a
315 function in the program being debugged.
318 @findex signal-handler-caller
320 ^Z^Zsignal-handler-caller
321 @var{signal-handler-caller-string}
324 where @var{signal-handler-caller-string} is text designed to convey to
325 the user that this frame is associated with whatever mechanism is used
326 by this operating system to call a signal handler (it is the frame which
327 calls the signal handler, not the frame for the signal handler itself).
332 @findex frame-address
333 @findex frame-address-end
334 This can optionally (depending on whether this is thought of as
335 interesting information for the user to see) begin with
340 ^Z^Zframe-address-end
341 @var{separator-string}
344 where @var{address} is the address executing in the frame (the same
345 address as in the @code{frame-begin} annotation, but printed in a form
346 which is intended for user consumption---in particular, the syntax varies
347 depending on the language), and @var{separator-string} is a string
348 intended to separate this address from what follows for the user's
351 @findex frame-function-name
356 ^Z^Zframe-function-name
362 where @var{function-name} is the name of the function executing in the
363 frame, or @samp{??} if not known, and @var{arguments} are the arguments
364 to the frame, with parentheses around them (each argument is annotated
365 individually as well, @pxref{Value Annotations}).
367 @findex frame-source-begin
368 @findex frame-source-file
369 @findex frame-source-file-end
370 @findex frame-source-line
371 @findex frame-source-end
372 If source information is available, a reference to it is then printed:
375 ^Z^Zframe-source-begin
376 @var{source-intro-string}
377 ^Z^Zframe-source-file
379 ^Z^Zframe-source-file-end
381 ^Z^Zframe-source-line
386 where @var{source-intro-string} separates for the user's benefit the
387 reference from the text which precedes it, @var{filename} is the name of
388 the source file, and @var{line-number} is the line number within that
389 file (the first line is line 1).
392 If @value{GDBN} prints some information about where the frame is from (which
393 library, which load segment, etc.; currently only done on the RS/6000),
401 Then, if source is to actually be displayed for this frame (for example,
402 this is not true for output from the @code{backtrace} command), then a
403 @code{source} annotation (@pxref{Source}) is displayed. Unlike most
404 annotations, this is output instead of the normal text which would be
405 output, not in addition.
411 @findex display-begin
412 @findex display-number-end
413 @findex display-format
414 @findex display-expression
415 @findex display-expression-end
416 @findex display-value
418 @cindex annotations for display
419 When @value{GDBN} is told to display something using the @code{display} command,
420 the results of the display are annotated:
425 ^Z^Zdisplay-number-end
426 @var{number-separator}
429 ^Z^Zdisplay-expression
431 ^Z^Zdisplay-expression-end
432 @var{expression-separator}
438 where @var{number} is the number of the display, @var{number-separator}
439 is intended to separate the number from what follows for the user,
440 @var{format} includes information such as the size, format, or other
441 information about how the value is being displayed, @var{expression} is
442 the expression being displayed, @var{expression-separator} is intended
443 to separate the expression from the text that follows for the user,
444 and @var{value} is the actual value being displayed.
447 @section Annotation for @value{GDBN} Input
449 @cindex annotations for prompts
450 When @value{GDBN} prompts for input, it annotates this fact so it is possible
451 to know when to send output, when the output from a given command is
454 Different kinds of input each have a different @dfn{input type}. Each
455 input type has three annotations: a @code{pre-} annotation, which
456 denotes the beginning of any prompt which is being output, a plain
457 annotation, which denotes the end of the prompt, and then a @code{post-}
458 annotation which denotes the end of any echo which may (or may not) be
459 associated with the input. For example, the @code{prompt} input type
460 features the following annotations:
475 When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
479 @findex post-commands
481 When @value{GDBN} prompts for a set of commands, like in the @code{commands}
482 command. The annotations are repeated for each command which is input.
484 @findex pre-overload-choice
485 @findex overload-choice
486 @findex post-overload-choice
487 @item overload-choice
488 When @value{GDBN} wants the user to select between various overloaded functions.
494 When @value{GDBN} wants the user to confirm a potentially dangerous operation.
496 @findex pre-prompt-for-continue
497 @findex prompt-for-continue
498 @findex post-prompt-for-continue
499 @item prompt-for-continue
500 When @value{GDBN} is asking the user to press return to continue. Note: Don't
501 expect this to work well; instead use @code{set height 0} to disable
502 prompting. This is because the counting of lines is buggy in the
503 presence of annotations.
508 @cindex annotations for errors, warnings and interrupts
515 This annotation occurs right before @value{GDBN} responds to an interrupt.
522 This annotation occurs right before @value{GDBN} responds to an error.
524 Quit and error annotations indicate that any annotations which @value{GDBN} was
525 in the middle of may end abruptly. For example, if a
526 @code{value-history-begin} annotation is followed by a @code{error}, one
527 cannot expect to receive the matching @code{value-history-end}. One
528 cannot expect not to receive it either, however; an error annotation
529 does not necessarily mean that @value{GDBN} is immediately returning all the way
533 A quit or error annotation may be preceded by
539 Any output between that and the quit or error annotation is the error
542 Warning messages are not yet annotated.
543 @c If we want to change that, need to fix warning(), type_error(),
544 @c range_error(), and possibly other places.
546 @node Breakpoint Info
547 @section Information on Breakpoints
549 @cindex annotations for breakpoints
550 The output from the @code{info breakpoints} command is annotated as follows:
552 @findex breakpoints-headers
553 @findex breakpoints-table
555 ^Z^Zbreakpoints-headers
557 ^Z^Zbreakpoints-table
560 where @var{header-entry} has the same syntax as an entry (see below) but
561 instead of containing data, it contains strings which are intended to
562 convey the meaning of each field to the user. This is followed by any
563 number of entries. If a field does not apply for this entry, it is
564 omitted. Fields may contain trailing whitespace. Each entry consists
593 Note that @var{address} is intended for user consumption---the syntax
594 varies depending on the language.
598 @findex breakpoints-table-end
600 ^Z^Zbreakpoints-table-end
604 @section Invalidation Notices
606 @cindex annotations for invalidation messages
607 The following annotations say that certain pieces of state may have
611 @findex frames-invalid
612 @item ^Z^Zframes-invalid
614 The frames (for example, output from the @code{backtrace} command) may
617 @findex breakpoints-invalid
618 @item ^Z^Zbreakpoints-invalid
620 The breakpoints may have changed. For example, the user just added or
621 deleted a breakpoint.
624 @node Annotations for Running
625 @section Running the Program
626 @cindex annotations for running programs
630 When the program starts executing due to a @value{GDBN} command such as
631 @code{step} or @code{continue},
637 is output. When the program stops,
643 is output. Before the @code{stopped} annotation, a variety of
644 annotations describe how the program stopped.
648 @item ^Z^Zexited @var{exit-status}
649 The program exited, and @var{exit-status} is the exit status (zero for
650 successful exit, otherwise nonzero).
654 @findex signal-name-end
655 @findex signal-string
656 @findex signal-string-end
658 The program exited with a signal. After the @code{^Z^Zsignalled}, the
659 annotation continues:
669 ^Z^Zsignal-string-end
673 where @var{name} is the name of the signal, such as @code{SIGILL} or
674 @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
675 as @code{Illegal Instruction} or @code{Segmentation fault}.
676 @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
677 user's benefit and have no particular format.
681 The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
682 just saying that the program received the signal, not that it was
686 @item ^Z^Zbreakpoint @var{number}
687 The program hit breakpoint number @var{number}.
690 @item ^Z^Zwatchpoint @var{number}
691 The program hit watchpoint number @var{number}.
694 @node Source Annotations
695 @section Displaying Source
696 @cindex annotations for source display
699 The following annotation is used instead of displaying source code:
702 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
705 where @var{filename} is an absolute file name indicating which source
706 file, @var{line} is the line number within that file (where 1 is the
707 first line in the file), @var{character} is the character position
708 within the file (where 0 is the first character in the file) (for most
709 debug formats this will necessarily point to the beginning of a line),
710 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
711 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
712 @var{addr} is the address in the target program associated with the
713 source which is being displayed. @var{addr} is in the form @samp{0x}
714 followed by one or more lowercase hex digits (note that this does not
715 depend on the language).
718 @section Annotations We Might Want in the Future
722 the target might have changed (registers, heap contents, or
723 execution status). For performance, we might eventually want
724 to hit `registers-invalid' and `all-registers-invalid' with
727 - systematic annotation for set/show parameters (including
728 invalidation notices).
730 - similarly, `info' returns a list of candidates for invalidation