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 Free Software Foundation, Inc.
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
56 @c @syncodeindex fn cp
59 @chapter @value{GDBN} Annotations
61 This chapter describes annotations in @value{GDBN}. Annotations are
62 designed to interface @value{GDBN} to graphical user interfaces or other
63 similar programs which want to interact with @value{GDBN} at a
64 relatively high level.
67 This is Edition @value{EDITION}, @value{DATE}.
71 * Annotations Overview:: What annotations are; the general syntax.
72 * Server Prefix:: Issuing a command without affecting user state.
73 * Value Annotations:: Values are marked as such.
74 * Frame Annotations:: Stack frames are annotated.
75 * Displays:: @value{GDBN} can be told to display something periodically.
76 * Prompting:: Annotations marking @value{GDBN}'s need for input.
77 * Errors:: Annotations for error messages.
78 * Breakpoint Info:: Information on breakpoints.
79 * Invalidation:: Some annotations describe things now invalid.
80 * Annotations for Running::
81 Whether the program is running, how it stopped, etc.
82 * Source Annotations:: Annotations describing source code.
83 * TODO:: Annotations which might be added in the future.
86 @node Annotations Overview
87 @section What is an Annotation?
90 To produce annotations, start @value{GDBN} with the @code{--annotate=2} option.
92 Annotations start with a newline character, two @samp{control-z}
93 characters, and the name of the annotation. If there is no additional
94 information associated with this annotation, the name of the annotation
95 is followed immediately by a newline. If there is additional
96 information, the name of the annotation is followed by a space, the
97 additional information, and a newline. The additional information
98 cannot contain newline characters.
100 Any output not beginning with a newline and two @samp{control-z}
101 characters denotes literal output from @value{GDBN}. Currently there is
102 no need for @value{GDBN} to output a newline followed by two
103 @samp{control-z} characters, but if there was such a need, the
104 annotations could be extended with an @samp{escape} annotation which
105 means those three characters as output.
107 A simple example of starting up @value{GDBN} with annotations is:
112 Copyright 2000 Free Software Foundation, Inc.
113 GDB is free software, covered by the GNU General Public License,
114 and you are welcome to change it and/or distribute copies of it
115 under certain conditions.
116 Type "show copying" to see the conditions.
117 There is absolutely no warranty for GDB. Type "show warranty"
119 This GDB was configured as "sparc-sun-sunos4.1.3"
130 Here @samp{quit} is input to @value{GDBN}; the rest is output from
131 @value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z}
132 denotes a @samp{control-z} character) are annotations; the rest is
133 output from @value{GDBN}.
136 @section The Server Prefix
137 @cindex server prefix for annotations
139 To issue a command to @value{GDBN} without affecting certain aspects of
140 the state which is seen by users, prefix it with @samp{server }. This
141 means that this command will not affect the command history, nor will it
142 affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
143 pressed on a line by itself.
145 The server prefix does not affect the recording of values into the value
146 history; to print a value without recording it into the value history,
147 use the @code{output} command instead of the @code{print} command.
149 @node Value Annotations
152 @cindex annotations for values
153 When a value is printed in various contexts, @value{GDBN} uses
154 annotations to delimit the value from the surrounding text.
156 @findex value-history-begin
157 @findex value-history-value
158 @findex value-history-end
159 If a value is printed using @code{print} and added to the value history,
160 the annotation looks like
163 ^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
165 ^Z^Zvalue-history-value
167 ^Z^Zvalue-history-end
170 where @var{history-number} is the number it is getting in the value
171 history, @var{history-string} is a string, such as @samp{$5 = }, which
172 introduces the value to the user, @var{the-value} is the output
173 corresponding to the value itself, and @var{value-flags} is @samp{*} for
174 a value which can be dereferenced and @samp{-} for a value which cannot.
178 If the value is not added to the value history (it is an invalid float
179 or it is printed with the @code{output} command), the annotation is similar:
182 ^Z^Zvalue-begin @var{value-flags}
191 When @value{GDBN} prints an argument to a function (for example, in the output
192 from the @code{backtrace} command), it annotates it as follows:
198 @var{separator-string}
199 ^Z^Zarg-value @var{value-flags}
204 where @var{argument-name} is the name of the argument,
205 @var{separator-string} is text which separates the name from the value
206 for the user's benefit (such as @samp{=}), and @var{value-flags} and
207 @var{the-value} have the same meanings as in a
208 @code{value-history-begin} annotation.
211 @findex field-name-end
214 When printing a structure, @value{GDBN} annotates it as follows:
217 ^Z^Zfield-begin @var{value-flags}
220 @var{separator-string}
226 where @var{field-name} is the name of the field, @var{separator-string}
227 is text which separates the name from the value for the user's benefit
228 (such as @samp{=}), and @var{value-flags} and @var{the-value} have the
229 same meanings as in a @code{value-history-begin} annotation.
231 When printing an array, @value{GDBN} annotates it as follows:
234 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
237 where @var{array-index} is the index of the first element being
238 annotated and @var{value-flags} has the same meaning as in a
239 @code{value-history-begin} annotation. This is followed by any number
240 of elements, where is element can be either a single element:
244 @samp{,} @var{whitespace} ; @r{omitted for the first element}
249 or a repeated element
254 @samp{,} @var{whitespace} ; @r{omitted for the first element}
256 ^Z^Zelt-rep @var{number-of-repititions}
257 @var{repetition-string}
261 In both cases, @var{the-value} is the output for the value of the
262 element and @var{whitespace} can contain spaces, tabs, and newlines. In
263 the repeated case, @var{number-of-repititons} is the number of
264 consecutive array elements which contain that value, and
265 @var{repetition-string} is a string which is designed to convey to the
266 user that repitition is being depicted.
268 @findex array-section-end
269 Once all the array elements have been output, the array annotation is
273 ^Z^Zarray-section-end
276 @node Frame Annotations
279 @cindex annotations for frames
280 Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
281 to frames printed when @value{GDBN} stops, output from commands such as
282 @code{backtrace} or @code{up}, etc.
285 The frame annotation begins with
288 ^Z^Zframe-begin @var{level} @var{address}
292 where @var{level} is the number of the frame (0 is the innermost frame,
293 and other frames have positive numbers), @var{address} is the address of
294 the code executing in that frame, and @var{level-string} is a string
295 designed to convey the level to the user. @var{address} is in the form
296 @samp{0x} followed by one or more lowercase hex digits (note that this
297 does not depend on the language). The frame ends with
304 Between these annotations is the main body of the frame, which can
309 @findex function-call
312 @var{function-call-string}
315 where @var{function-call-string} is text designed to convey to the user
316 that this frame is associated with a function call made by @value{GDBN} to a
317 function in the program being debugged.
320 @findex signal-handler-caller
322 ^Z^Zsignal-handler-caller
323 @var{signal-handler-caller-string}
326 where @var{signal-handler-caller-string} is text designed to convey to
327 the user that this frame is associated with whatever mechanism is used
328 by this operating system to call a signal handler (it is the frame which
329 calls the signal handler, not the frame for the signal handler itself).
334 @findex frame-address
335 @findex frame-address-end
336 This can optionally (depending on whether this is thought of as
337 interesting information for the user to see) begin with
342 ^Z^Zframe-address-end
343 @var{separator-string}
346 where @var{address} is the address executing in the frame (the same
347 address as in the @code{frame-begin} annotation, but printed in a form
348 which is intended for user consumption---in particular, the syntax varies
349 depending on the language), and @var{separator-string} is a string
350 intended to separate this address from what follows for the user's
353 @findex frame-function-name
358 ^Z^Zframe-function-name
364 where @var{function-name} is the name of the function executing in the
365 frame, or @samp{??} if not known, and @var{arguments} are the arguments
366 to the frame, with parentheses around them (each argument is annotated
367 individually as well, @pxref{Value Annotations}).
369 @findex frame-source-begin
370 @findex frame-source-file
371 @findex frame-source-file-end
372 @findex frame-source-line
373 @findex frame-source-end
374 If source information is available, a reference to it is then printed:
377 ^Z^Zframe-source-begin
378 @var{source-intro-string}
379 ^Z^Zframe-source-file
381 ^Z^Zframe-source-file-end
383 ^Z^Zframe-source-line
388 where @var{source-intro-string} separates for the user's benefit the
389 reference from the text which precedes it, @var{filename} is the name of
390 the source file, and @var{line-number} is the line number within that
391 file (the first line is line 1).
394 If @value{GDBN} prints some information about where the frame is from (which
395 library, which load segment, etc.; currently only done on the RS/6000),
403 Then, if source is to actually be displayed for this frame (for example,
404 this is not true for output from the @code{backtrace} command), then a
405 @code{source} annotation (@pxref{Source Annotations}) is displayed. Unlike
406 most annotations, this is output instead of the normal text which would be
407 output, not in addition.
413 @findex display-begin
414 @findex display-number-end
415 @findex display-format
416 @findex display-expression
417 @findex display-expression-end
418 @findex display-value
420 @cindex annotations for display
421 When @value{GDBN} is told to display something using the @code{display} command,
422 the results of the display are annotated:
427 ^Z^Zdisplay-number-end
428 @var{number-separator}
431 ^Z^Zdisplay-expression
433 ^Z^Zdisplay-expression-end
434 @var{expression-separator}
440 where @var{number} is the number of the display, @var{number-separator}
441 is intended to separate the number from what follows for the user,
442 @var{format} includes information such as the size, format, or other
443 information about how the value is being displayed, @var{expression} is
444 the expression being displayed, @var{expression-separator} is intended
445 to separate the expression from the text that follows for the user,
446 and @var{value} is the actual value being displayed.
449 @section Annotation for @value{GDBN} Input
451 @cindex annotations for prompts
452 When @value{GDBN} prompts for input, it annotates this fact so it is possible
453 to know when to send output, when the output from a given command is
456 Different kinds of input each have a different @dfn{input type}. Each
457 input type has three annotations: a @code{pre-} annotation, which
458 denotes the beginning of any prompt which is being output, a plain
459 annotation, which denotes the end of the prompt, and then a @code{post-}
460 annotation which denotes the end of any echo which may (or may not) be
461 associated with the input. For example, the @code{prompt} input type
462 features the following annotations:
477 When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
481 @findex post-commands
483 When @value{GDBN} prompts for a set of commands, like in the @code{commands}
484 command. The annotations are repeated for each command which is input.
486 @findex pre-overload-choice
487 @findex overload-choice
488 @findex post-overload-choice
489 @item overload-choice
490 When @value{GDBN} wants the user to select between various overloaded functions.
496 When @value{GDBN} wants the user to confirm a potentially dangerous operation.
498 @findex pre-prompt-for-continue
499 @findex prompt-for-continue
500 @findex post-prompt-for-continue
501 @item prompt-for-continue
502 When @value{GDBN} is asking the user to press return to continue. Note: Don't
503 expect this to work well; instead use @code{set height 0} to disable
504 prompting. This is because the counting of lines is buggy in the
505 presence of annotations.
510 @cindex annotations for errors, warnings and interrupts
517 This annotation occurs right before @value{GDBN} responds to an interrupt.
524 This annotation occurs right before @value{GDBN} responds to an error.
526 Quit and error annotations indicate that any annotations which @value{GDBN} was
527 in the middle of may end abruptly. For example, if a
528 @code{value-history-begin} annotation is followed by a @code{error}, one
529 cannot expect to receive the matching @code{value-history-end}. One
530 cannot expect not to receive it either, however; an error annotation
531 does not necessarily mean that @value{GDBN} is immediately returning all the way
535 A quit or error annotation may be preceded by
541 Any output between that and the quit or error annotation is the error
544 Warning messages are not yet annotated.
545 @c If we want to change that, need to fix warning(), type_error(),
546 @c range_error(), and possibly other places.
548 @node Breakpoint Info
549 @section Information on Breakpoints
551 @cindex annotations for breakpoints
552 The output from the @code{info breakpoints} command is annotated as follows:
554 @findex breakpoints-headers
555 @findex breakpoints-table
557 ^Z^Zbreakpoints-headers
559 ^Z^Zbreakpoints-table
562 where @var{header-entry} has the same syntax as an entry (see below) but
563 instead of containing data, it contains strings which are intended to
564 convey the meaning of each field to the user. This is followed by any
565 number of entries. If a field does not apply for this entry, it is
566 omitted. Fields may contain trailing whitespace. Each entry consists
595 Note that @var{address} is intended for user consumption---the syntax
596 varies depending on the language.
600 @findex breakpoints-table-end
602 ^Z^Zbreakpoints-table-end
606 @section Invalidation Notices
608 @cindex annotations for invalidation messages
609 The following annotations say that certain pieces of state may have
613 @findex frames-invalid
614 @item ^Z^Zframes-invalid
616 The frames (for example, output from the @code{backtrace} command) may
619 @findex breakpoints-invalid
620 @item ^Z^Zbreakpoints-invalid
622 The breakpoints may have changed. For example, the user just added or
623 deleted a breakpoint.
626 @node Annotations for Running
627 @section Running the Program
628 @cindex annotations for running programs
632 When the program starts executing due to a @value{GDBN} command such as
633 @code{step} or @code{continue},
639 is output. When the program stops,
645 is output. Before the @code{stopped} annotation, a variety of
646 annotations describe how the program stopped.
650 @item ^Z^Zexited @var{exit-status}
651 The program exited, and @var{exit-status} is the exit status (zero for
652 successful exit, otherwise nonzero).
656 @findex signal-name-end
657 @findex signal-string
658 @findex signal-string-end
660 The program exited with a signal. After the @code{^Z^Zsignalled}, the
661 annotation continues:
671 ^Z^Zsignal-string-end
675 where @var{name} is the name of the signal, such as @code{SIGILL} or
676 @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
677 as @code{Illegal Instruction} or @code{Segmentation fault}.
678 @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
679 user's benefit and have no particular format.
683 The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
684 just saying that the program received the signal, not that it was
688 @item ^Z^Zbreakpoint @var{number}
689 The program hit breakpoint number @var{number}.
692 @item ^Z^Zwatchpoint @var{number}
693 The program hit watchpoint number @var{number}.
696 @node Source Annotations
697 @section Displaying Source
698 @cindex annotations for source display
701 The following annotation is used instead of displaying source code:
704 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
707 where @var{filename} is an absolute file name indicating which source
708 file, @var{line} is the line number within that file (where 1 is the
709 first line in the file), @var{character} is the character position
710 within the file (where 0 is the first character in the file) (for most
711 debug formats this will necessarily point to the beginning of a line),
712 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
713 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
714 @var{addr} is the address in the target program associated with the
715 source which is being displayed. @var{addr} is in the form @samp{0x}
716 followed by one or more lowercase hex digits (note that this does not
717 depend on the language).
720 @section Annotations We Might Want in the Future
724 the target might have changed (registers, heap contents, or
725 execution status). For performance, we might eventually want
726 to hit `registers-invalid' and `all-registers-invalid' with
729 - systematic annotation for set/show parameters (including
730 invalidation notices).
732 - similarly, `info' returns a list of candidates for invalidation