1 \input texinfo @c -*-texinfo-*-
3 @setfilename annotate.info
5 @c This is a dir.info fragment to support semi-automated addition of
6 @c manuals to an info tree.
7 @dircategory Software development
9 * Annotate: (annotate). The obsolete annotation interface.
15 @settitle @value{GDBN}'s Obsolete Annotations
16 @setchapternewpage off
22 @c NOTE: cagney/2003-07-28:
23 @c Don't make this migration document an appendix of GDB's user guide.
24 @c By keeping this separate, the size of the user guide is contained. If
25 @c the user guide to get much bigger it would need to switch to a larger,
26 @c more expensive, form factor and would drive up the manuals publication
27 @c cost. Having a smaller cheaper manual helps the GNU Press with its sales.
30 This file documents @value{GDBN}'s obsolete annotations.
32 Copyright (C) 1994, 1995, 2000, 2001, 2003 Free Software Foundation, Inc.
34 Permission is granted to copy, distribute and/or modify this document
35 under the terms of the GNU Free Documentation License, Version 1.1 or
36 any later version published by the Free Software Foundation; with no
37 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
38 Texts. A copy of the license is included in the section entitled ``GNU
39 Free Documentation License''.
44 @title @value{GDBN}'s Obsolete Annotations
45 @subtitle Edition @value{EDITION}
46 @subtitle @value{DATE}
47 @author Free Software Foundation
49 @vskip 0pt plus 1filll
50 Copyright @copyright{} 1994, 1995, 2000, 2001, 2003 Free Software
53 Permission is granted to copy, distribute and/or modify this document
54 under the terms of the GNU Free Documentation License, Version 1.1 or
55 any later version published by the Free Software Foundation; with no
56 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
57 Texts. A copy of the license is included in the section entitled ``GNU
58 Free Documentation License''.
65 This document describes the obsolete level two annotation interface
66 implemented in older @value{GDBN} versions.
69 This is Edition @value{EDITION}, @value{DATE}.
74 * Annotations Overview:: What annotations are; the general syntax.
75 * Limitations:: Limitations of the annotation interface.
76 * Migrating to GDB/MI:: Migrating to GDB/MI
77 * Server Prefix:: Issuing a command without affecting user state.
78 * Value Annotations:: Values are marked as such.
79 * Frame Annotations:: Stack frames are annotated.
80 * Displays:: @value{GDBN} can be told to display something periodically.
81 * Prompting:: Annotations marking @value{GDBN}'s need for input.
82 * Errors:: Annotations for error messages.
83 * Breakpoint Info:: Information on breakpoints.
84 * Invalidation:: Some annotations describe things now invalid.
85 * Annotations for Running::
86 Whether the program is running, how it stopped, etc.
87 * Source Annotations:: Annotations describing source code.
88 * Multi-threaded Apps:: An annotation that reports multi-threadedness.
90 * GNU Free Documentation License::
95 @node Annotations Overview
96 @chapter What is an Annotation?
99 To produce obsolete level two annotations, start @value{GDBN} with the
100 @code{--annotate=2} option.
102 Annotations start with a newline character, two @samp{control-z}
103 characters, and the name of the annotation. If there is no additional
104 information associated with this annotation, the name of the annotation
105 is followed immediately by a newline. If there is additional
106 information, the name of the annotation is followed by a space, the
107 additional information, and a newline. The additional information
108 cannot contain newline characters.
110 Any output not beginning with a newline and two @samp{control-z}
111 characters denotes literal output from @value{GDBN}. Currently there is
112 no need for @value{GDBN} to output a newline followed by two
113 @samp{control-z} characters, but if there was such a need, the
114 annotations could be extended with an @samp{escape} annotation which
115 means those three characters as output.
117 A simple example of starting up @value{GDBN} with annotations is:
122 Copyright 2000 Free Software Foundation, Inc.
123 GDB is free software, covered by the GNU General Public License,
124 and you are welcome to change it and/or distribute copies of it
125 under certain conditions.
126 Type "show copying" to see the conditions.
127 There is absolutely no warranty for GDB. Type "show warranty"
129 This GDB was configured as "sparc-sun-sunos4.1.3"
140 Here @samp{quit} is input to @value{GDBN}; the rest is output from
141 @value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z}
142 denotes a @samp{control-z} character) are annotations; the rest is
143 output from @value{GDBN}.
146 @chapter Limitations of the Annotation Interface
148 The level two annotations mechanism is known to have a number of
149 technical and architectural limitations. As a consequence, in 2001,
150 with the release of @value{GDBN} 5.1 and the addition of @sc{gdb/mi},
151 the annotation interface was marked as deprecated.
153 This chapter discusses the known problems.
155 @section Dependant on @sc{cli} output
157 The annotation interface works by interspersing markups with
158 @value{GDBN} normal command-line interpreter output. Unfortunately, this
159 makes the annotation client dependant on not just the annotations, but
160 also the @sc{cli} output. This is because the client is forced to
161 assume that specific @value{GDBN} commands provide specific information.
162 Any change to @value{GDBN}'s @sc{cli} output modifies or removes that
163 information and, consequently, likely breaks the client.
165 Since the @sc{gdb/mi} output is independent of the @sc{cli}, it does not
170 The annotation interface relies on value annotations (@pxref{Value
171 Annotations}) and the display mechanism as a way of obtaining up-to-date
172 value information. These mechanisms are not scalable.
174 In a graphical environment, where many values can be displayed
175 simultaneously, a serious performance problem occurs when the client
176 tries to first extract from @value{GDBN}, and then re-display, all those
177 values. The client should instead only request and update the values
180 The @sc{gdb/mi} Variable Objects provide just that mechanism.
184 The annotation interface assumes that a variable's value can only be
185 changed when the target is running. This assumption is not correct. A
186 single assignment to a single variable can result in the entire target,
187 and all displayed values, needing an update.
189 The @sc{gdb/mi} Variable Objects include a mechanism for efficiently
190 reporting such changes.
194 The @sc{gdb/mi} interface includes a dedicated test directory
195 (@file{gdb/gdb.mi}), and any addition or fix to @sc{gdb/mi} must include
198 @section Maintainability
200 The annotation mechanism was implemented by interspersing @sc{cli} print
201 statements with various annotations. As a consequence, any @sc{cli}
202 output change can alter the annotation output.
204 Since the @sc{gdb/mi} output is independent of the @sc{cli}, and the
205 @sc{gdb/mi} is increasingly implemented independent of the @sc{cli}
206 code, its long term maintenance is much easier.
208 @node Migrating to GDB/MI
209 @chapter Migrating to @sc{gdb/mi}
211 By using the @samp{interp mi} command, it is possible for annotation
212 clients to invoke @sc{gdb/mi} commands, and hence access the
213 @sc{gdb/mi}. By doing this, existing annotation clients have a
214 migration path from this obsolete interface to @sc{gdb/mi}.
217 @chapter The Server Prefix
218 @cindex server prefix for annotations
220 To issue a command to @value{GDBN} without affecting certain aspects of
221 the state which is seen by users, prefix it with @samp{server }. This
222 means that this command will not affect the command history, nor will it
223 affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
224 pressed on a line by itself.
226 The server prefix does not affect the recording of values into the value
227 history; to print a value without recording it into the value history,
228 use the @code{output} command instead of the @code{print} command.
230 @node Value Annotations
233 @emph{Value Annotations have been removed. @sc{gdb/mi} instead provides
236 @cindex annotations for values
237 When a value is printed in various contexts, @value{GDBN} uses
238 annotations to delimit the value from the surrounding text.
240 @findex value-history-begin
241 @findex value-history-value
242 @findex value-history-end
243 If a value is printed using @code{print} and added to the value history,
244 the annotation looks like
247 ^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
249 ^Z^Zvalue-history-value
251 ^Z^Zvalue-history-end
255 where @var{history-number} is the number it is getting in the value
256 history, @var{history-string} is a string, such as @samp{$5 = }, which
257 introduces the value to the user, @var{the-value} is the output
258 corresponding to the value itself, and @var{value-flags} is @samp{*} for
259 a value which can be dereferenced and @samp{-} for a value which cannot.
263 If the value is not added to the value history (it is an invalid float
264 or it is printed with the @code{output} command), the annotation is similar:
267 ^Z^Zvalue-begin @var{value-flags}
276 When @value{GDBN} prints an argument to a function (for example, in the output
277 from the @code{backtrace} command), it annotates it as follows:
283 @var{separator-string}
284 ^Z^Zarg-value @var{value-flags}
290 where @var{argument-name} is the name of the argument,
291 @var{separator-string} is text which separates the name from the value
292 for the user's benefit (such as @samp{=}), and @var{value-flags} and
293 @var{the-value} have the same meanings as in a
294 @code{value-history-begin} annotation.
297 @findex field-name-end
300 When printing a structure, @value{GDBN} annotates it as follows:
303 ^Z^Zfield-begin @var{value-flags}
306 @var{separator-string}
313 where @var{field-name} is the name of the field, @var{separator-string}
314 is text which separates the name from the value for the user's benefit
315 (such as @samp{=}), and @var{value-flags} and @var{the-value} have the
316 same meanings as in a @code{value-history-begin} annotation.
318 When printing an array, @value{GDBN} annotates it as follows:
321 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
325 where @var{array-index} is the index of the first element being
326 annotated and @var{value-flags} has the same meaning as in a
327 @code{value-history-begin} annotation. This is followed by any number
328 of elements, where is element can be either a single element:
332 @samp{,} @var{whitespace} ; @r{omitted for the first element}
337 or a repeated element
342 @samp{,} @var{whitespace} ; @r{omitted for the first element}
344 ^Z^Zelt-rep @var{number-of-repetitions}
345 @var{repetition-string}
349 In both cases, @var{the-value} is the output for the value of the
350 element and @var{whitespace} can contain spaces, tabs, and newlines. In
351 the repeated case, @var{number-of-repetitions} is the number of
352 consecutive array elements which contain that value, and
353 @var{repetition-string} is a string which is designed to convey to the
354 user that repetition is being depicted.
356 @findex array-section-end
357 Once all the array elements have been output, the array annotation is
361 ^Z^Zarray-section-end
364 @node Frame Annotations
367 @emph{Value Annotations have been removed. @sc{gdb/mi} instead provides
368 a number of frame commands.}
370 @emph{Frame annotations are no longer available. The @sc{gdb/mi}
371 provides @samp{-stack-list-arguments}, @samp{-stack-list-locals}, and
372 @samp{-stack-list-frames} commands.}
374 @cindex annotations for frames
375 Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
376 to frames printed when @value{GDBN} stops, output from commands such as
377 @code{backtrace} or @code{up}, etc.
380 The frame annotation begins with
383 ^Z^Zframe-begin @var{level} @var{address}
388 where @var{level} is the number of the frame (0 is the innermost frame,
389 and other frames have positive numbers), @var{address} is the address of
390 the code executing in that frame, and @var{level-string} is a string
391 designed to convey the level to the user. @var{address} is in the form
392 @samp{0x} followed by one or more lowercase hex digits (note that this
393 does not depend on the language). The frame ends with
400 Between these annotations is the main body of the frame, which can
405 @findex function-call
408 @var{function-call-string}
411 where @var{function-call-string} is text designed to convey to the user
412 that this frame is associated with a function call made by @value{GDBN} to a
413 function in the program being debugged.
416 @findex signal-handler-caller
418 ^Z^Zsignal-handler-caller
419 @var{signal-handler-caller-string}
422 where @var{signal-handler-caller-string} is text designed to convey to
423 the user that this frame is associated with whatever mechanism is used
424 by this operating system to call a signal handler (it is the frame which
425 calls the signal handler, not the frame for the signal handler itself).
430 @findex frame-address
431 @findex frame-address-end
432 This can optionally (depending on whether this is thought of as
433 interesting information for the user to see) begin with
438 ^Z^Zframe-address-end
439 @var{separator-string}
442 where @var{address} is the address executing in the frame (the same
443 address as in the @code{frame-begin} annotation, but printed in a form
444 which is intended for user consumption---in particular, the syntax varies
445 depending on the language), and @var{separator-string} is a string
446 intended to separate this address from what follows for the user's
449 @findex frame-function-name
454 ^Z^Zframe-function-name
460 where @var{function-name} is the name of the function executing in the
461 frame, or @samp{??} if not known, and @var{arguments} are the arguments
462 to the frame, with parentheses around them (each argument is annotated
463 individually as well, @pxref{Value Annotations}).
465 @findex frame-source-begin
466 @findex frame-source-file
467 @findex frame-source-file-end
468 @findex frame-source-line
469 @findex frame-source-end
470 If source information is available, a reference to it is then printed:
473 ^Z^Zframe-source-begin
474 @var{source-intro-string}
475 ^Z^Zframe-source-file
477 ^Z^Zframe-source-file-end
479 ^Z^Zframe-source-line
484 where @var{source-intro-string} separates for the user's benefit the
485 reference from the text which precedes it, @var{filename} is the name of
486 the source file, and @var{line-number} is the line number within that
487 file (the first line is line 1).
490 If @value{GDBN} prints some information about where the frame is from (which
491 library, which load segment, etc.; currently only done on the RS/6000),
499 Then, if source is to actually be displayed for this frame (for example,
500 this is not true for output from the @code{backtrace} command), then a
501 @code{source} annotation (@pxref{Source Annotations}) is displayed. Unlike
502 most annotations, this is output instead of the normal text which would be
503 output, not in addition.
509 @emph{Display Annotations have been removed. @sc{gdb/mi} instead
510 provides Variable Objects.}
512 @findex display-begin
513 @findex display-number-end
514 @findex display-format
515 @findex display-expression
516 @findex display-expression-end
517 @findex display-value
519 @cindex annotations for display
520 When @value{GDBN} is told to display something using the @code{display} command,
521 the results of the display are annotated:
526 ^Z^Zdisplay-number-end
527 @var{number-separator}
530 ^Z^Zdisplay-expression
532 ^Z^Zdisplay-expression-end
533 @var{expression-separator}
540 where @var{number} is the number of the display, @var{number-separator}
541 is intended to separate the number from what follows for the user,
542 @var{format} includes information such as the size, format, or other
543 information about how the value is being displayed, @var{expression} is
544 the expression being displayed, @var{expression-separator} is intended
545 to separate the expression from the text that follows for the user,
546 and @var{value} is the actual value being displayed.
549 @chapter Annotation for @value{GDBN} Input
551 @cindex annotations for prompts
552 When @value{GDBN} prompts for input, it annotates this fact so it is possible
553 to know when to send output, when the output from a given command is
556 Different kinds of input each have a different @dfn{input type}. Each
557 input type has three annotations: a @code{pre-} annotation, which
558 denotes the beginning of any prompt which is being output, a plain
559 annotation, which denotes the end of the prompt, and then a @code{post-}
560 annotation which denotes the end of any echo which may (or may not) be
561 associated with the input. For example, the @code{prompt} input type
562 features the following annotations:
577 When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
581 @findex post-commands
583 When @value{GDBN} prompts for a set of commands, like in the @code{commands}
584 command. The annotations are repeated for each command which is input.
586 @findex pre-overload-choice
587 @findex overload-choice
588 @findex post-overload-choice
589 @item overload-choice
590 When @value{GDBN} wants the user to select between various overloaded functions.
596 When @value{GDBN} wants the user to confirm a potentially dangerous operation.
598 @findex pre-prompt-for-continue
599 @findex prompt-for-continue
600 @findex post-prompt-for-continue
601 @item prompt-for-continue
602 When @value{GDBN} is asking the user to press return to continue. Note: Don't
603 expect this to work well; instead use @code{set height 0} to disable
604 prompting. This is because the counting of lines is buggy in the
605 presence of annotations.
610 @cindex annotations for errors, warnings and interrupts
617 This annotation occurs right before @value{GDBN} responds to an interrupt.
624 This annotation occurs right before @value{GDBN} responds to an error.
626 Quit and error annotations indicate that any annotations which @value{GDBN} was
627 in the middle of may end abruptly. For example, if a
628 @code{value-history-begin} annotation is followed by a @code{error}, one
629 cannot expect to receive the matching @code{value-history-end}. One
630 cannot expect not to receive it either, however; an error annotation
631 does not necessarily mean that @value{GDBN} is immediately returning all the way
635 A quit or error annotation may be preceded by
641 Any output between that and the quit or error annotation is the error
644 Warning messages are not yet annotated.
645 @c If we want to change that, need to fix warning(), type_error(),
646 @c range_error(), and possibly other places.
648 @node Breakpoint Info
649 @chapter Information on Breakpoints
651 @emph{Breakpoint Annotations have been removed. @sc{gdb/mi} instead
652 provides breakpoint commands.}
654 @cindex annotations for breakpoints
655 The output from the @code{info breakpoints} command is annotated as follows:
657 @findex breakpoints-headers
658 @findex breakpoints-table
660 ^Z^Zbreakpoints-headers
662 ^Z^Zbreakpoints-table
666 where @var{header-entry} has the same syntax as an entry (see below) but
667 instead of containing data, it contains strings which are intended to
668 convey the meaning of each field to the user. This is followed by any
669 number of entries. If a field does not apply for this entry, it is
670 omitted. Fields may contain trailing whitespace. Each entry consists
699 Note that @var{address} is intended for user consumption---the syntax
700 varies depending on the language.
704 @findex breakpoints-table-end
706 ^Z^Zbreakpoints-table-end
710 @chapter Invalidation Notices
712 @cindex annotations for invalidation messages
713 The following annotations say that certain pieces of state may have
717 @findex frames-invalid
718 @item ^Z^Zframes-invalid
720 The frames (for example, output from the @code{backtrace} command) may
723 @findex breakpoints-invalid
724 @item ^Z^Zbreakpoints-invalid
726 The breakpoints may have changed. For example, the user just added or
727 deleted a breakpoint.
730 @node Annotations for Running
731 @chapter Running the Program
732 @cindex annotations for running programs
736 When the program starts executing due to a @value{GDBN} command such as
737 @code{step} or @code{continue},
743 is output. When the program stops,
749 is output. Before the @code{stopped} annotation, a variety of
750 annotations describe how the program stopped.
754 @item ^Z^Zexited @var{exit-status}
755 The program exited, and @var{exit-status} is the exit status (zero for
756 successful exit, otherwise nonzero).
760 @findex signal-name-end
761 @findex signal-string
762 @findex signal-string-end
764 The program exited with a signal. After the @code{^Z^Zsignalled}, the
765 annotation continues:
775 ^Z^Zsignal-string-end
780 where @var{name} is the name of the signal, such as @code{SIGILL} or
781 @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
782 as @code{Illegal Instruction} or @code{Segmentation fault}.
783 @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
784 user's benefit and have no particular format.
788 The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
789 just saying that the program received the signal, not that it was
793 @item ^Z^Zbreakpoint @var{number}
794 The program hit breakpoint number @var{number}.
797 @item ^Z^Zwatchpoint @var{number}
798 The program hit watchpoint number @var{number}.
801 @node Source Annotations
802 @chapter Displaying Source
803 @cindex annotations for source display
806 The following annotation is used instead of displaying source code:
809 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
812 where @var{filename} is an absolute file name indicating which source
813 file, @var{line} is the line number within that file (where 1 is the
814 first line in the file), @var{character} is the character position
815 within the file (where 0 is the first character in the file) (for most
816 debug formats this will necessarily point to the beginning of a line),
817 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
818 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
819 @var{addr} is the address in the target program associated with the
820 source which is being displayed. @var{addr} is in the form @samp{0x}
821 followed by one or more lowercase hex digits (note that this does not
822 depend on the language).
824 @node Multi-threaded Apps
825 @chapter Multi-threaded Applications
826 @cindex annotations for multi-threaded apps
828 The following annotations report thread related changes of state.
831 @findex new-thread@r{, annotation}
834 This annotation is issued once for each thread that is created apart from
835 the main thread, which is not reported.
837 @findex thread-changed@r{, annotation}
838 @item ^Z^Zthread-changed
840 The selected thread has changed. This may occur at the request of the
841 user with the @code{thread} command, or as a result of execution,
842 e.g., another thread hits a breakpoint.