1 \input texinfo @c -*-texinfo-*-
3 @setfilename annotate.info
7 @settitle @value{GDBN}'s Obsolete Annotations
14 @c NOTE: cagney/2003-07-28:
15 @c Don't make this migration doccument an appendix of GDB's user guide.
16 @c By keeping this separate, the size of the user guide is contained. If
17 @c the user guide to get much bigger it would need to switch to a larger,
18 @c more expensive, form factor and would drive up the manuals publication
19 @c cost. Having a smaller cheaper manual helps the GNU Press with its sales.
22 This file documents @value{GDBN}'s obsolete annotations.
24 Copyright 1994, 1995, 2000, 2001, 2003 Free Software Foundation, Inc.
26 Permission is granted to copy, distribute and/or modify this document
27 under the terms of the GNU Free Documentation License, Version 1.1 or
28 any later version published by the Free Software Foundation; with no
29 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
30 Texts. A copy of the license is included in the section entitled ``GNU
31 Free Documentation License''.
36 @title @value{GDBN}'s Obsolete Annotations
37 @subtitle Edition @value{EDITION}
38 @subtitle @value{DATE}
39 @author Free Software Foundation
41 @vskip 0pt plus 1filll
42 Copyright @copyright{} 1994, 1995, 2000, 2001, 2003 Free Software
45 Permission is granted to copy, distribute and/or modify this document
46 under the terms of the GNU Free Documentation License, Version 1.1 or
47 any later version published by the Free Software Foundation; with no
48 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
49 Texts. A copy of the license is included in the section entitled ``GNU
50 Free Documentation License''.
57 This document describes the obsolete level two annotation interface
58 implemented in older @value{GDBN} versions.
61 This is Edition @value{EDITION}, @value{DATE}.
66 * Annotations Overview:: What annotations are; the general syntax.
67 * Limitations:: Limitations of the annotation interface.
68 * Migrating to GDB/MI:: Migrating to GDB/MI
69 * Server Prefix:: Issuing a command without affecting user state.
70 * Value Annotations:: Values are marked as such.
71 * Frame Annotations:: Stack frames are annotated.
72 * Displays:: @value{GDBN} can be told to display something periodically.
73 * Prompting:: Annotations marking @value{GDBN}'s need for input.
74 * Errors:: Annotations for error messages.
75 * Breakpoint Info:: Information on breakpoints.
76 * Invalidation:: Some annotations describe things now invalid.
77 * Annotations for Running::
78 Whether the program is running, how it stopped, etc.
79 * Source Annotations:: Annotations describing source code.
81 * GNU Free Documentation License::
86 @node Annotations Overview
87 @chapter What is an Annotation?
90 To produce obsolete level two annotations, start @value{GDBN} with the
91 @code{--annotate=2} option.
93 Annotations start with a newline character, two @samp{control-z}
94 characters, and the name of the annotation. If there is no additional
95 information associated with this annotation, the name of the annotation
96 is followed immediately by a newline. If there is additional
97 information, the name of the annotation is followed by a space, the
98 additional information, and a newline. The additional information
99 cannot contain newline characters.
101 Any output not beginning with a newline and two @samp{control-z}
102 characters denotes literal output from @value{GDBN}. Currently there is
103 no need for @value{GDBN} to output a newline followed by two
104 @samp{control-z} characters, but if there was such a need, the
105 annotations could be extended with an @samp{escape} annotation which
106 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,
115 and you are welcome to change it and/or distribute copies of it
116 under certain conditions.
117 Type "show copying" to see the conditions.
118 There is absolutely no warranty for GDB. Type "show warranty"
120 This GDB was configured as "sparc-sun-sunos4.1.3"
131 Here @samp{quit} is input to @value{GDBN}; the rest is output from
132 @value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z}
133 denotes a @samp{control-z} character) are annotations; the rest is
134 output from @value{GDBN}.
137 @chapter Limitations of the Annotation Interface
139 The level two annotations mechanism is known to have a number of
140 technical and architectural limitations. As a consequence, in 2001,
141 with the release of @value{GDBN} 5.1 and the addition of @sc{gdb/mi},
142 the annotation interface was marked as deprecated.
144 This chapter discusses the known problems.
146 @section Dependant on @sc{cli} output
148 The annotation interface works by interspersing markups with
149 @value{GDBN} normal command-line interpreter output. Unfortunatly, this
150 makes the annotation client dependant on not just the annotations, but
151 also the @sc{cli} output. This is because the client is forced to
152 assume that specific @value{GDBN} commands provide specific information.
153 Any change to @value{GDBN}'s @sc{cli} output modifies or removes that
154 information and, consequently, likely breaks the client.
156 Since the @sc{gdb/mi} output is independant of the @sc{cli}, it does not
161 The annotation interface relies on value annotations (@pxref{Value
162 Annotations}) and the display mechanism as a way of obtaining up-to-date
163 value information. These mechanisms are not scalable.
165 In a graphical environment, where many values can be displayed
166 simultaneously, a serious performance problem occurs when the client
167 tries to first extract from @value{GDBN}, and then re-display, all those
168 values. The client should instead only request and update the values
171 The @sc{gdb/mi} Variable Objects provide just that mechanism.
175 The annotation interface assumes that a variable's value can only be
176 changed when the target is running. This assumption is not correct. A
177 single assignment to a single variable can result in the entire target,
178 and all displayed values, needing an update.
180 The @sc{gdb/mi} Variable Objects include a mechanism for efficiently
181 reporting such changes.
185 The @sc{gdb/mi} interface includes a dedicated test directory
186 (@file{gdb/gdb.mi}), and any addition or fix to @sc{gdb/mi} must include
189 @section Maintainability
191 The annotation mechanism was implemented by interspersing @sc{cli} print
192 statements with various annotations. As a consequence, any @sc{cli}
193 output change can alter the annotation output.
195 Since the @sc{gdb/mi} output is independant of the @sc{cli}, and the
196 @sc{gdb/mi} is increasingly implemented independant of the @sc{cli}
197 code, its long term maintenance is much easier.
199 @node Migrating to GDB/MI
200 @chapter Migrating to @sc{gdb/mi}
202 By using the @samp{interp mi} command, it is possible for annotation
203 clients to invoke @sc{gdb/mi} commands, and hence access the
204 @sc{gdb/mi}. By doing this, existing annotation clients have a
205 migration path from this obsolete interface to @sc{gdb/mi}.
208 @chapter The Server Prefix
209 @cindex server prefix for annotations
211 To issue a command to @value{GDBN} without affecting certain aspects of
212 the state which is seen by users, prefix it with @samp{server }. This
213 means that this command will not affect the command history, nor will it
214 affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
215 pressed on a line by itself.
217 The server prefix does not affect the recording of values into the value
218 history; to print a value without recording it into the value history,
219 use the @code{output} command instead of the @code{print} command.
221 @node Value Annotations
224 @emph{Value Annotations have been removed. @sc{gdb/mi} instead provides
227 @cindex annotations for values
228 When a value is printed in various contexts, @value{GDBN} uses
229 annotations to delimit the value from the surrounding text.
231 @findex value-history-begin
232 @findex value-history-value
233 @findex value-history-end
234 If a value is printed using @code{print} and added to the value history,
235 the annotation looks like
238 ^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
240 ^Z^Zvalue-history-value
242 ^Z^Zvalue-history-end
246 where @var{history-number} is the number it is getting in the value
247 history, @var{history-string} is a string, such as @samp{$5 = }, which
248 introduces the value to the user, @var{the-value} is the output
249 corresponding to the value itself, and @var{value-flags} is @samp{*} for
250 a value which can be dereferenced and @samp{-} for a value which cannot.
254 If the value is not added to the value history (it is an invalid float
255 or it is printed with the @code{output} command), the annotation is similar:
258 ^Z^Zvalue-begin @var{value-flags}
267 When @value{GDBN} prints an argument to a function (for example, in the output
268 from the @code{backtrace} command), it annotates it as follows:
274 @var{separator-string}
275 ^Z^Zarg-value @var{value-flags}
281 where @var{argument-name} is the name of the argument,
282 @var{separator-string} is text which separates the name from the value
283 for the user's benefit (such as @samp{=}), and @var{value-flags} and
284 @var{the-value} have the same meanings as in a
285 @code{value-history-begin} annotation.
288 @findex field-name-end
291 When printing a structure, @value{GDBN} annotates it as follows:
294 ^Z^Zfield-begin @var{value-flags}
297 @var{separator-string}
304 where @var{field-name} is the name of the field, @var{separator-string}
305 is text which separates the name from the value for the user's benefit
306 (such as @samp{=}), and @var{value-flags} and @var{the-value} have the
307 same meanings as in a @code{value-history-begin} annotation.
309 When printing an array, @value{GDBN} annotates it as follows:
312 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
316 where @var{array-index} is the index of the first element being
317 annotated and @var{value-flags} has the same meaning as in a
318 @code{value-history-begin} annotation. This is followed by any number
319 of elements, where is element can be either a single element:
323 @samp{,} @var{whitespace} ; @r{omitted for the first element}
328 or a repeated element
333 @samp{,} @var{whitespace} ; @r{omitted for the first element}
335 ^Z^Zelt-rep @var{number-of-repetitions}
336 @var{repetition-string}
340 In both cases, @var{the-value} is the output for the value of the
341 element and @var{whitespace} can contain spaces, tabs, and newlines. In
342 the repeated case, @var{number-of-repetitions} is the number of
343 consecutive array elements which contain that value, and
344 @var{repetition-string} is a string which is designed to convey to the
345 user that repetition is being depicted.
347 @findex array-section-end
348 Once all the array elements have been output, the array annotation is
352 ^Z^Zarray-section-end
355 @node Frame Annotations
358 @emph{Value Annotations have been removed. @sc{gdb/mi} instead provides
359 a number of frame commands.}
361 @emph{Frame annotations are no longer available. The @sc{gdb/mi}
362 provides @samp{-stack-list-arguments}, @samp{-stack-list-locals}, and
363 @samp{-stack-list-frames} commands.}
365 @cindex annotations for frames
366 Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
367 to frames printed when @value{GDBN} stops, output from commands such as
368 @code{backtrace} or @code{up}, etc.
371 The frame annotation begins with
374 ^Z^Zframe-begin @var{level} @var{address}
379 where @var{level} is the number of the frame (0 is the innermost frame,
380 and other frames have positive numbers), @var{address} is the address of
381 the code executing in that frame, and @var{level-string} is a string
382 designed to convey the level to the user. @var{address} is in the form
383 @samp{0x} followed by one or more lowercase hex digits (note that this
384 does not depend on the language). The frame ends with
391 Between these annotations is the main body of the frame, which can
396 @findex function-call
399 @var{function-call-string}
402 where @var{function-call-string} is text designed to convey to the user
403 that this frame is associated with a function call made by @value{GDBN} to a
404 function in the program being debugged.
407 @findex signal-handler-caller
409 ^Z^Zsignal-handler-caller
410 @var{signal-handler-caller-string}
413 where @var{signal-handler-caller-string} is text designed to convey to
414 the user that this frame is associated with whatever mechanism is used
415 by this operating system to call a signal handler (it is the frame which
416 calls the signal handler, not the frame for the signal handler itself).
421 @findex frame-address
422 @findex frame-address-end
423 This can optionally (depending on whether this is thought of as
424 interesting information for the user to see) begin with
429 ^Z^Zframe-address-end
430 @var{separator-string}
433 where @var{address} is the address executing in the frame (the same
434 address as in the @code{frame-begin} annotation, but printed in a form
435 which is intended for user consumption---in particular, the syntax varies
436 depending on the language), and @var{separator-string} is a string
437 intended to separate this address from what follows for the user's
440 @findex frame-function-name
445 ^Z^Zframe-function-name
451 where @var{function-name} is the name of the function executing in the
452 frame, or @samp{??} if not known, and @var{arguments} are the arguments
453 to the frame, with parentheses around them (each argument is annotated
454 individually as well, @pxref{Value Annotations}).
456 @findex frame-source-begin
457 @findex frame-source-file
458 @findex frame-source-file-end
459 @findex frame-source-line
460 @findex frame-source-end
461 If source information is available, a reference to it is then printed:
464 ^Z^Zframe-source-begin
465 @var{source-intro-string}
466 ^Z^Zframe-source-file
468 ^Z^Zframe-source-file-end
470 ^Z^Zframe-source-line
475 where @var{source-intro-string} separates for the user's benefit the
476 reference from the text which precedes it, @var{filename} is the name of
477 the source file, and @var{line-number} is the line number within that
478 file (the first line is line 1).
481 If @value{GDBN} prints some information about where the frame is from (which
482 library, which load segment, etc.; currently only done on the RS/6000),
490 Then, if source is to actually be displayed for this frame (for example,
491 this is not true for output from the @code{backtrace} command), then a
492 @code{source} annotation (@pxref{Source Annotations}) is displayed. Unlike
493 most annotations, this is output instead of the normal text which would be
494 output, not in addition.
500 @emph{Display Annotations have been removed. @sc{gdb/mi} instead
501 provides Variable Objects.}
503 @findex display-begin
504 @findex display-number-end
505 @findex display-format
506 @findex display-expression
507 @findex display-expression-end
508 @findex display-value
510 @cindex annotations for display
511 When @value{GDBN} is told to display something using the @code{display} command,
512 the results of the display are annotated:
517 ^Z^Zdisplay-number-end
518 @var{number-separator}
521 ^Z^Zdisplay-expression
523 ^Z^Zdisplay-expression-end
524 @var{expression-separator}
531 where @var{number} is the number of the display, @var{number-separator}
532 is intended to separate the number from what follows for the user,
533 @var{format} includes information such as the size, format, or other
534 information about how the value is being displayed, @var{expression} is
535 the expression being displayed, @var{expression-separator} is intended
536 to separate the expression from the text that follows for the user,
537 and @var{value} is the actual value being displayed.
540 @chapter Annotation for @value{GDBN} Input
542 @cindex annotations for prompts
543 When @value{GDBN} prompts for input, it annotates this fact so it is possible
544 to know when to send output, when the output from a given command is
547 Different kinds of input each have a different @dfn{input type}. Each
548 input type has three annotations: a @code{pre-} annotation, which
549 denotes the beginning of any prompt which is being output, a plain
550 annotation, which denotes the end of the prompt, and then a @code{post-}
551 annotation which denotes the end of any echo which may (or may not) be
552 associated with the input. For example, the @code{prompt} input type
553 features the following annotations:
568 When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
572 @findex post-commands
574 When @value{GDBN} prompts for a set of commands, like in the @code{commands}
575 command. The annotations are repeated for each command which is input.
577 @findex pre-overload-choice
578 @findex overload-choice
579 @findex post-overload-choice
580 @item overload-choice
581 When @value{GDBN} wants the user to select between various overloaded functions.
587 When @value{GDBN} wants the user to confirm a potentially dangerous operation.
589 @findex pre-prompt-for-continue
590 @findex prompt-for-continue
591 @findex post-prompt-for-continue
592 @item prompt-for-continue
593 When @value{GDBN} is asking the user to press return to continue. Note: Don't
594 expect this to work well; instead use @code{set height 0} to disable
595 prompting. This is because the counting of lines is buggy in the
596 presence of annotations.
601 @cindex annotations for errors, warnings and interrupts
608 This annotation occurs right before @value{GDBN} responds to an interrupt.
615 This annotation occurs right before @value{GDBN} responds to an error.
617 Quit and error annotations indicate that any annotations which @value{GDBN} was
618 in the middle of may end abruptly. For example, if a
619 @code{value-history-begin} annotation is followed by a @code{error}, one
620 cannot expect to receive the matching @code{value-history-end}. One
621 cannot expect not to receive it either, however; an error annotation
622 does not necessarily mean that @value{GDBN} is immediately returning all the way
626 A quit or error annotation may be preceded by
632 Any output between that and the quit or error annotation is the error
635 Warning messages are not yet annotated.
636 @c If we want to change that, need to fix warning(), type_error(),
637 @c range_error(), and possibly other places.
639 @node Breakpoint Info
640 @chapter Information on Breakpoints
642 @emph{Breakpoint Annotations have been removed. @sc{gdb/mi} instead
643 provides breakpoint commands.}
645 @cindex annotations for breakpoints
646 The output from the @code{info breakpoints} command is annotated as follows:
648 @findex breakpoints-headers
649 @findex breakpoints-table
651 ^Z^Zbreakpoints-headers
653 ^Z^Zbreakpoints-table
657 where @var{header-entry} has the same syntax as an entry (see below) but
658 instead of containing data, it contains strings which are intended to
659 convey the meaning of each field to the user. This is followed by any
660 number of entries. If a field does not apply for this entry, it is
661 omitted. Fields may contain trailing whitespace. Each entry consists
690 Note that @var{address} is intended for user consumption---the syntax
691 varies depending on the language.
695 @findex breakpoints-table-end
697 ^Z^Zbreakpoints-table-end
701 @chapter Invalidation Notices
703 @cindex annotations for invalidation messages
704 The following annotations say that certain pieces of state may have
708 @findex frames-invalid
709 @item ^Z^Zframes-invalid
711 The frames (for example, output from the @code{backtrace} command) may
714 @findex breakpoints-invalid
715 @item ^Z^Zbreakpoints-invalid
717 The breakpoints may have changed. For example, the user just added or
718 deleted a breakpoint.
721 @node Annotations for Running
722 @chapter Running the Program
723 @cindex annotations for running programs
727 When the program starts executing due to a @value{GDBN} command such as
728 @code{step} or @code{continue},
734 is output. When the program stops,
740 is output. Before the @code{stopped} annotation, a variety of
741 annotations describe how the program stopped.
745 @item ^Z^Zexited @var{exit-status}
746 The program exited, and @var{exit-status} is the exit status (zero for
747 successful exit, otherwise nonzero).
751 @findex signal-name-end
752 @findex signal-string
753 @findex signal-string-end
755 The program exited with a signal. After the @code{^Z^Zsignalled}, the
756 annotation continues:
766 ^Z^Zsignal-string-end
771 where @var{name} is the name of the signal, such as @code{SIGILL} or
772 @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
773 as @code{Illegal Instruction} or @code{Segmentation fault}.
774 @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
775 user's benefit and have no particular format.
779 The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
780 just saying that the program received the signal, not that it was
784 @item ^Z^Zbreakpoint @var{number}
785 The program hit breakpoint number @var{number}.
788 @item ^Z^Zwatchpoint @var{number}
789 The program hit watchpoint number @var{number}.
792 @node Source Annotations
793 @chapter Displaying Source
794 @cindex annotations for source display
797 The following annotation is used instead of displaying source code:
800 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
803 where @var{filename} is an absolute file name indicating which source
804 file, @var{line} is the line number within that file (where 1 is the
805 first line in the file), @var{character} is the character position
806 within the file (where 0 is the first character in the file) (for most
807 debug formats this will necessarily point to the beginning of a line),
808 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
809 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
810 @var{addr} is the address in the target program associated with the
811 source which is being displayed. @var{addr} is in the form @samp{0x}
812 followed by one or more lowercase hex digits (note that this does not
813 depend on the language).