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,1995,2000,2001 Free Software Foundation, Inc.
17 @c Permission is granted to copy, distribute and/or modify this document
18 @c under the terms of the GNU Free Documentation License, Version 1.1 or
19 @c any later version published by the Free Software Foundation; with the
20 @c Invariant Sections being ``Annotations Overview'' and ``Source
21 @c Annotations'', with the Front-Cover texts being ``A GNU Manual,''
22 @c and with the Back-Cover Texts as in (a) below.
24 @c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
25 @c this GNU Manual, like GNU software. Copies published by the Free
26 @c Software Foundation raise funds for GNU development.''
30 @c @title GDB Annotations
31 @c @subtitle Edition @value{EDITION}
32 @c @subtitle @value{DATE}
33 @c @author Cygnus Support
35 @c @vskip 0pt plus 1filll
36 @c Permission is granted to make and distribute verbatim copies of
37 @c this manual provided the copyright notice and this permission notice
38 @c are preserved on all copies.
40 @c Copyright @copyright{} 1994,1995,2000,2001 Free Software Foundation
45 @c @top GDB Annotations
47 @c @syncodeindex fn cp
50 @chapter @value{GDBN} Annotations
52 This chapter describes annotations in @value{GDBN}. Annotations are
53 designed to interface @value{GDBN} to graphical user interfaces or
54 other similar programs which want to interact with @value{GDBN} at a
55 relatively high level.
58 This is Edition @value{EDITION}, @value{DATE}.
62 * Annotations Overview:: What annotations are; the general syntax.
63 * Server Prefix:: Issuing a command without affecting user state.
64 * Value Annotations:: Values are marked as such.
65 * Frame Annotations:: Stack frames are annotated.
66 * Displays:: @value{GDBN} can be told to display something periodically.
67 * Prompting:: Annotations marking @value{GDBN}'s need for input.
68 * Errors:: Annotations for error messages.
69 * Breakpoint Info:: Information on breakpoints.
70 * Invalidation:: Some annotations describe things now invalid.
71 * Annotations for Running::
72 Whether the program is running, how it stopped, etc.
73 * Source Annotations:: Annotations describing source code.
74 * TODO:: Annotations which might be added in the future.
77 @node Annotations Overview
78 @section What is an Annotation?
81 To produce annotations, start @value{GDBN} with the @code{--annotate=2} option.
83 Annotations start with a newline character, two @samp{control-z}
84 characters, and the name of the annotation. If there is no additional
85 information associated with this annotation, the name of the annotation
86 is followed immediately by a newline. If there is additional
87 information, the name of the annotation is followed by a space, the
88 additional information, and a newline. The additional information
89 cannot contain newline characters.
91 Any output not beginning with a newline and two @samp{control-z}
92 characters denotes literal output from @value{GDBN}. Currently there is
93 no need for @value{GDBN} to output a newline followed by two
94 @samp{control-z} characters, but if there was such a need, the
95 annotations could be extended with an @samp{escape} annotation which
96 means those three characters as output.
98 A simple example of starting up @value{GDBN} with annotations is:
103 Copyright 2000 Free Software Foundation, Inc.
104 GDB is free software, covered by the GNU General Public License,
105 and you are welcome to change it and/or distribute copies of it
106 under certain conditions.
107 Type "show copying" to see the conditions.
108 There is absolutely no warranty for GDB. Type "show warranty"
110 This GDB was configured as "sparc-sun-sunos4.1.3"
121 Here @samp{quit} is input to @value{GDBN}; the rest is output from
122 @value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z}
123 denotes a @samp{control-z} character) are annotations; the rest is
124 output from @value{GDBN}.
127 @section The Server Prefix
128 @cindex server prefix for annotations
130 To issue a command to @value{GDBN} without affecting certain aspects of
131 the state which is seen by users, prefix it with @samp{server }. This
132 means that this command will not affect the command history, nor will it
133 affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
134 pressed on a line by itself.
136 The server prefix does not affect the recording of values into the value
137 history; to print a value without recording it into the value history,
138 use the @code{output} command instead of the @code{print} command.
140 @node Value Annotations
143 @cindex annotations for values
144 When a value is printed in various contexts, @value{GDBN} uses
145 annotations to delimit the value from the surrounding text.
147 @findex value-history-begin
148 @findex value-history-value
149 @findex value-history-end
150 If a value is printed using @code{print} and added to the value history,
151 the annotation looks like
154 ^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
156 ^Z^Zvalue-history-value
158 ^Z^Zvalue-history-end
161 where @var{history-number} is the number it is getting in the value
162 history, @var{history-string} is a string, such as @samp{$5 = }, which
163 introduces the value to the user, @var{the-value} is the output
164 corresponding to the value itself, and @var{value-flags} is @samp{*} for
165 a value which can be dereferenced and @samp{-} for a value which cannot.
169 If the value is not added to the value history (it is an invalid float
170 or it is printed with the @code{output} command), the annotation is similar:
173 ^Z^Zvalue-begin @var{value-flags}
182 When @value{GDBN} prints an argument to a function (for example, in the output
183 from the @code{backtrace} command), it annotates it as follows:
189 @var{separator-string}
190 ^Z^Zarg-value @var{value-flags}
195 where @var{argument-name} is the name of the argument,
196 @var{separator-string} is text which separates the name from the value
197 for the user's benefit (such as @samp{=}), and @var{value-flags} and
198 @var{the-value} have the same meanings as in a
199 @code{value-history-begin} annotation.
202 @findex field-name-end
205 When printing a structure, @value{GDBN} annotates it as follows:
208 ^Z^Zfield-begin @var{value-flags}
211 @var{separator-string}
217 where @var{field-name} is the name of the field, @var{separator-string}
218 is text which separates the name from the value for the user's benefit
219 (such as @samp{=}), and @var{value-flags} and @var{the-value} have the
220 same meanings as in a @code{value-history-begin} annotation.
222 When printing an array, @value{GDBN} annotates it as follows:
225 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
228 where @var{array-index} is the index of the first element being
229 annotated and @var{value-flags} has the same meaning as in a
230 @code{value-history-begin} annotation. This is followed by any number
231 of elements, where is element can be either a single element:
235 @samp{,} @var{whitespace} ; @r{omitted for the first element}
240 or a repeated element
245 @samp{,} @var{whitespace} ; @r{omitted for the first element}
247 ^Z^Zelt-rep @var{number-of-repititions}
248 @var{repetition-string}
252 In both cases, @var{the-value} is the output for the value of the
253 element and @var{whitespace} can contain spaces, tabs, and newlines. In
254 the repeated case, @var{number-of-repititons} is the number of
255 consecutive array elements which contain that value, and
256 @var{repetition-string} is a string which is designed to convey to the
257 user that repitition is being depicted.
259 @findex array-section-end
260 Once all the array elements have been output, the array annotation is
264 ^Z^Zarray-section-end
267 @node Frame Annotations
270 @cindex annotations for frames
271 Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
272 to frames printed when @value{GDBN} stops, output from commands such as
273 @code{backtrace} or @code{up}, etc.
276 The frame annotation begins with
279 ^Z^Zframe-begin @var{level} @var{address}
283 where @var{level} is the number of the frame (0 is the innermost frame,
284 and other frames have positive numbers), @var{address} is the address of
285 the code executing in that frame, and @var{level-string} is a string
286 designed to convey the level to the user. @var{address} is in the form
287 @samp{0x} followed by one or more lowercase hex digits (note that this
288 does not depend on the language). The frame ends with
295 Between these annotations is the main body of the frame, which can
300 @findex function-call
303 @var{function-call-string}
306 where @var{function-call-string} is text designed to convey to the user
307 that this frame is associated with a function call made by @value{GDBN} to a
308 function in the program being debugged.
311 @findex signal-handler-caller
313 ^Z^Zsignal-handler-caller
314 @var{signal-handler-caller-string}
317 where @var{signal-handler-caller-string} is text designed to convey to
318 the user that this frame is associated with whatever mechanism is used
319 by this operating system to call a signal handler (it is the frame which
320 calls the signal handler, not the frame for the signal handler itself).
325 @findex frame-address
326 @findex frame-address-end
327 This can optionally (depending on whether this is thought of as
328 interesting information for the user to see) begin with
333 ^Z^Zframe-address-end
334 @var{separator-string}
337 where @var{address} is the address executing in the frame (the same
338 address as in the @code{frame-begin} annotation, but printed in a form
339 which is intended for user consumption---in particular, the syntax varies
340 depending on the language), and @var{separator-string} is a string
341 intended to separate this address from what follows for the user's
344 @findex frame-function-name
349 ^Z^Zframe-function-name
355 where @var{function-name} is the name of the function executing in the
356 frame, or @samp{??} if not known, and @var{arguments} are the arguments
357 to the frame, with parentheses around them (each argument is annotated
358 individually as well, @pxref{Value Annotations}).
360 @findex frame-source-begin
361 @findex frame-source-file
362 @findex frame-source-file-end
363 @findex frame-source-line
364 @findex frame-source-end
365 If source information is available, a reference to it is then printed:
368 ^Z^Zframe-source-begin
369 @var{source-intro-string}
370 ^Z^Zframe-source-file
372 ^Z^Zframe-source-file-end
374 ^Z^Zframe-source-line
379 where @var{source-intro-string} separates for the user's benefit the
380 reference from the text which precedes it, @var{filename} is the name of
381 the source file, and @var{line-number} is the line number within that
382 file (the first line is line 1).
385 If @value{GDBN} prints some information about where the frame is from (which
386 library, which load segment, etc.; currently only done on the RS/6000),
394 Then, if source is to actually be displayed for this frame (for example,
395 this is not true for output from the @code{backtrace} command), then a
396 @code{source} annotation (@pxref{Source Annotations}) is displayed. Unlike
397 most annotations, this is output instead of the normal text which would be
398 output, not in addition.
404 @findex display-begin
405 @findex display-number-end
406 @findex display-format
407 @findex display-expression
408 @findex display-expression-end
409 @findex display-value
411 @cindex annotations for display
412 When @value{GDBN} is told to display something using the @code{display} command,
413 the results of the display are annotated:
418 ^Z^Zdisplay-number-end
419 @var{number-separator}
422 ^Z^Zdisplay-expression
424 ^Z^Zdisplay-expression-end
425 @var{expression-separator}
431 where @var{number} is the number of the display, @var{number-separator}
432 is intended to separate the number from what follows for the user,
433 @var{format} includes information such as the size, format, or other
434 information about how the value is being displayed, @var{expression} is
435 the expression being displayed, @var{expression-separator} is intended
436 to separate the expression from the text that follows for the user,
437 and @var{value} is the actual value being displayed.
440 @section Annotation for @value{GDBN} Input
442 @cindex annotations for prompts
443 When @value{GDBN} prompts for input, it annotates this fact so it is possible
444 to know when to send output, when the output from a given command is
447 Different kinds of input each have a different @dfn{input type}. Each
448 input type has three annotations: a @code{pre-} annotation, which
449 denotes the beginning of any prompt which is being output, a plain
450 annotation, which denotes the end of the prompt, and then a @code{post-}
451 annotation which denotes the end of any echo which may (or may not) be
452 associated with the input. For example, the @code{prompt} input type
453 features the following annotations:
468 When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
472 @findex post-commands
474 When @value{GDBN} prompts for a set of commands, like in the @code{commands}
475 command. The annotations are repeated for each command which is input.
477 @findex pre-overload-choice
478 @findex overload-choice
479 @findex post-overload-choice
480 @item overload-choice
481 When @value{GDBN} wants the user to select between various overloaded functions.
487 When @value{GDBN} wants the user to confirm a potentially dangerous operation.
489 @findex pre-prompt-for-continue
490 @findex prompt-for-continue
491 @findex post-prompt-for-continue
492 @item prompt-for-continue
493 When @value{GDBN} is asking the user to press return to continue. Note: Don't
494 expect this to work well; instead use @code{set height 0} to disable
495 prompting. This is because the counting of lines is buggy in the
496 presence of annotations.
501 @cindex annotations for errors, warnings and interrupts
508 This annotation occurs right before @value{GDBN} responds to an interrupt.
515 This annotation occurs right before @value{GDBN} responds to an error.
517 Quit and error annotations indicate that any annotations which @value{GDBN} was
518 in the middle of may end abruptly. For example, if a
519 @code{value-history-begin} annotation is followed by a @code{error}, one
520 cannot expect to receive the matching @code{value-history-end}. One
521 cannot expect not to receive it either, however; an error annotation
522 does not necessarily mean that @value{GDBN} is immediately returning all the way
526 A quit or error annotation may be preceded by
532 Any output between that and the quit or error annotation is the error
535 Warning messages are not yet annotated.
536 @c If we want to change that, need to fix warning(), type_error(),
537 @c range_error(), and possibly other places.
539 @node Breakpoint Info
540 @section Information on Breakpoints
542 @cindex annotations for breakpoints
543 The output from the @code{info breakpoints} command is annotated as follows:
545 @findex breakpoints-headers
546 @findex breakpoints-table
548 ^Z^Zbreakpoints-headers
550 ^Z^Zbreakpoints-table
553 where @var{header-entry} has the same syntax as an entry (see below) but
554 instead of containing data, it contains strings which are intended to
555 convey the meaning of each field to the user. This is followed by any
556 number of entries. If a field does not apply for this entry, it is
557 omitted. Fields may contain trailing whitespace. Each entry consists
586 Note that @var{address} is intended for user consumption---the syntax
587 varies depending on the language.
591 @findex breakpoints-table-end
593 ^Z^Zbreakpoints-table-end
597 @section Invalidation Notices
599 @cindex annotations for invalidation messages
600 The following annotations say that certain pieces of state may have
604 @findex frames-invalid
605 @item ^Z^Zframes-invalid
607 The frames (for example, output from the @code{backtrace} command) may
610 @findex breakpoints-invalid
611 @item ^Z^Zbreakpoints-invalid
613 The breakpoints may have changed. For example, the user just added or
614 deleted a breakpoint.
617 @node Annotations for Running
618 @section Running the Program
619 @cindex annotations for running programs
623 When the program starts executing due to a @value{GDBN} command such as
624 @code{step} or @code{continue},
630 is output. When the program stops,
636 is output. Before the @code{stopped} annotation, a variety of
637 annotations describe how the program stopped.
641 @item ^Z^Zexited @var{exit-status}
642 The program exited, and @var{exit-status} is the exit status (zero for
643 successful exit, otherwise nonzero).
647 @findex signal-name-end
648 @findex signal-string
649 @findex signal-string-end
651 The program exited with a signal. After the @code{^Z^Zsignalled}, the
652 annotation continues:
662 ^Z^Zsignal-string-end
666 where @var{name} is the name of the signal, such as @code{SIGILL} or
667 @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
668 as @code{Illegal Instruction} or @code{Segmentation fault}.
669 @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
670 user's benefit and have no particular format.
674 The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
675 just saying that the program received the signal, not that it was
679 @item ^Z^Zbreakpoint @var{number}
680 The program hit breakpoint number @var{number}.
683 @item ^Z^Zwatchpoint @var{number}
684 The program hit watchpoint number @var{number}.
687 @node Source Annotations
688 @section Displaying Source
689 @cindex annotations for source display
692 The following annotation is used instead of displaying source code:
695 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
698 where @var{filename} is an absolute file name indicating which source
699 file, @var{line} is the line number within that file (where 1 is the
700 first line in the file), @var{character} is the character position
701 within the file (where 0 is the first character in the file) (for most
702 debug formats this will necessarily point to the beginning of a line),
703 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
704 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
705 @var{addr} is the address in the target program associated with the
706 source which is being displayed. @var{addr} is in the form @samp{0x}
707 followed by one or more lowercase hex digits (note that this does not
708 depend on the language).
711 @section Annotations We Might Want in the Future
715 the target might have changed (registers, heap contents, or
716 execution status). For performance, we might eventually want
717 to hit `registers-invalid' and `all-registers-invalid' with
720 - systematic annotation for set/show parameters (including
721 invalidation notices).
723 - similarly, `info' returns a list of candidates for invalidation