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
162 where @var{history-number} is the number it is getting in the value
163 history, @var{history-string} is a string, such as @samp{$5 = }, which
164 introduces the value to the user, @var{the-value} is the output
165 corresponding to the value itself, and @var{value-flags} is @samp{*} for
166 a value which can be dereferenced and @samp{-} for a value which cannot.
170 If the value is not added to the value history (it is an invalid float
171 or it is printed with the @code{output} command), the annotation is similar:
174 ^Z^Zvalue-begin @var{value-flags}
183 When @value{GDBN} prints an argument to a function (for example, in the output
184 from the @code{backtrace} command), it annotates it as follows:
190 @var{separator-string}
191 ^Z^Zarg-value @var{value-flags}
197 where @var{argument-name} is the name of the argument,
198 @var{separator-string} is text which separates the name from the value
199 for the user's benefit (such as @samp{=}), and @var{value-flags} and
200 @var{the-value} have the same meanings as in a
201 @code{value-history-begin} annotation.
204 @findex field-name-end
207 When printing a structure, @value{GDBN} annotates it as follows:
210 ^Z^Zfield-begin @var{value-flags}
213 @var{separator-string}
220 where @var{field-name} is the name of the field, @var{separator-string}
221 is text which separates the name from the value for the user's benefit
222 (such as @samp{=}), and @var{value-flags} and @var{the-value} have the
223 same meanings as in a @code{value-history-begin} annotation.
225 When printing an array, @value{GDBN} annotates it as follows:
228 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
232 where @var{array-index} is the index of the first element being
233 annotated and @var{value-flags} has the same meaning as in a
234 @code{value-history-begin} annotation. This is followed by any number
235 of elements, where is element can be either a single element:
239 @samp{,} @var{whitespace} ; @r{omitted for the first element}
244 or a repeated element
249 @samp{,} @var{whitespace} ; @r{omitted for the first element}
251 ^Z^Zelt-rep @var{number-of-repititions}
252 @var{repetition-string}
256 In both cases, @var{the-value} is the output for the value of the
257 element and @var{whitespace} can contain spaces, tabs, and newlines. In
258 the repeated case, @var{number-of-repititons} is the number of
259 consecutive array elements which contain that value, and
260 @var{repetition-string} is a string which is designed to convey to the
261 user that repitition is being depicted.
263 @findex array-section-end
264 Once all the array elements have been output, the array annotation is
268 ^Z^Zarray-section-end
271 @node Frame Annotations
274 @cindex annotations for frames
275 Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
276 to frames printed when @value{GDBN} stops, output from commands such as
277 @code{backtrace} or @code{up}, etc.
280 The frame annotation begins with
283 ^Z^Zframe-begin @var{level} @var{address}
288 where @var{level} is the number of the frame (0 is the innermost frame,
289 and other frames have positive numbers), @var{address} is the address of
290 the code executing in that frame, and @var{level-string} is a string
291 designed to convey the level to the user. @var{address} is in the form
292 @samp{0x} followed by one or more lowercase hex digits (note that this
293 does not depend on the language). The frame ends with
300 Between these annotations is the main body of the frame, which can
305 @findex function-call
308 @var{function-call-string}
311 where @var{function-call-string} is text designed to convey to the user
312 that this frame is associated with a function call made by @value{GDBN} to a
313 function in the program being debugged.
316 @findex signal-handler-caller
318 ^Z^Zsignal-handler-caller
319 @var{signal-handler-caller-string}
322 where @var{signal-handler-caller-string} is text designed to convey to
323 the user that this frame is associated with whatever mechanism is used
324 by this operating system to call a signal handler (it is the frame which
325 calls the signal handler, not the frame for the signal handler itself).
330 @findex frame-address
331 @findex frame-address-end
332 This can optionally (depending on whether this is thought of as
333 interesting information for the user to see) begin with
338 ^Z^Zframe-address-end
339 @var{separator-string}
342 where @var{address} is the address executing in the frame (the same
343 address as in the @code{frame-begin} annotation, but printed in a form
344 which is intended for user consumption---in particular, the syntax varies
345 depending on the language), and @var{separator-string} is a string
346 intended to separate this address from what follows for the user's
349 @findex frame-function-name
354 ^Z^Zframe-function-name
360 where @var{function-name} is the name of the function executing in the
361 frame, or @samp{??} if not known, and @var{arguments} are the arguments
362 to the frame, with parentheses around them (each argument is annotated
363 individually as well, @pxref{Value Annotations}).
365 @findex frame-source-begin
366 @findex frame-source-file
367 @findex frame-source-file-end
368 @findex frame-source-line
369 @findex frame-source-end
370 If source information is available, a reference to it is then printed:
373 ^Z^Zframe-source-begin
374 @var{source-intro-string}
375 ^Z^Zframe-source-file
377 ^Z^Zframe-source-file-end
379 ^Z^Zframe-source-line
384 where @var{source-intro-string} separates for the user's benefit the
385 reference from the text which precedes it, @var{filename} is the name of
386 the source file, and @var{line-number} is the line number within that
387 file (the first line is line 1).
390 If @value{GDBN} prints some information about where the frame is from (which
391 library, which load segment, etc.; currently only done on the RS/6000),
399 Then, if source is to actually be displayed for this frame (for example,
400 this is not true for output from the @code{backtrace} command), then a
401 @code{source} annotation (@pxref{Source Annotations}) is displayed. Unlike
402 most annotations, this is output instead of the normal text which would be
403 output, not in addition.
409 @findex display-begin
410 @findex display-number-end
411 @findex display-format
412 @findex display-expression
413 @findex display-expression-end
414 @findex display-value
416 @cindex annotations for display
417 When @value{GDBN} is told to display something using the @code{display} command,
418 the results of the display are annotated:
423 ^Z^Zdisplay-number-end
424 @var{number-separator}
427 ^Z^Zdisplay-expression
429 ^Z^Zdisplay-expression-end
430 @var{expression-separator}
437 where @var{number} is the number of the display, @var{number-separator}
438 is intended to separate the number from what follows for the user,
439 @var{format} includes information such as the size, format, or other
440 information about how the value is being displayed, @var{expression} is
441 the expression being displayed, @var{expression-separator} is intended
442 to separate the expression from the text that follows for the user,
443 and @var{value} is the actual value being displayed.
446 @section Annotation for @value{GDBN} Input
448 @cindex annotations for prompts
449 When @value{GDBN} prompts for input, it annotates this fact so it is possible
450 to know when to send output, when the output from a given command is
453 Different kinds of input each have a different @dfn{input type}. Each
454 input type has three annotations: a @code{pre-} annotation, which
455 denotes the beginning of any prompt which is being output, a plain
456 annotation, which denotes the end of the prompt, and then a @code{post-}
457 annotation which denotes the end of any echo which may (or may not) be
458 associated with the input. For example, the @code{prompt} input type
459 features the following annotations:
474 When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
478 @findex post-commands
480 When @value{GDBN} prompts for a set of commands, like in the @code{commands}
481 command. The annotations are repeated for each command which is input.
483 @findex pre-overload-choice
484 @findex overload-choice
485 @findex post-overload-choice
486 @item overload-choice
487 When @value{GDBN} wants the user to select between various overloaded functions.
493 When @value{GDBN} wants the user to confirm a potentially dangerous operation.
495 @findex pre-prompt-for-continue
496 @findex prompt-for-continue
497 @findex post-prompt-for-continue
498 @item prompt-for-continue
499 When @value{GDBN} is asking the user to press return to continue. Note: Don't
500 expect this to work well; instead use @code{set height 0} to disable
501 prompting. This is because the counting of lines is buggy in the
502 presence of annotations.
507 @cindex annotations for errors, warnings and interrupts
514 This annotation occurs right before @value{GDBN} responds to an interrupt.
521 This annotation occurs right before @value{GDBN} responds to an error.
523 Quit and error annotations indicate that any annotations which @value{GDBN} was
524 in the middle of may end abruptly. For example, if a
525 @code{value-history-begin} annotation is followed by a @code{error}, one
526 cannot expect to receive the matching @code{value-history-end}. One
527 cannot expect not to receive it either, however; an error annotation
528 does not necessarily mean that @value{GDBN} is immediately returning all the way
532 A quit or error annotation may be preceded by
538 Any output between that and the quit or error annotation is the error
541 Warning messages are not yet annotated.
542 @c If we want to change that, need to fix warning(), type_error(),
543 @c range_error(), and possibly other places.
545 @node Breakpoint Info
546 @section Information on Breakpoints
548 @cindex annotations for breakpoints
549 The output from the @code{info breakpoints} command is annotated as follows:
551 @findex breakpoints-headers
552 @findex breakpoints-table
554 ^Z^Zbreakpoints-headers
556 ^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
674 where @var{name} is the name of the signal, such as @code{SIGILL} or
675 @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
676 as @code{Illegal Instruction} or @code{Segmentation fault}.
677 @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
678 user's benefit and have no particular format.
682 The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
683 just saying that the program received the signal, not that it was
687 @item ^Z^Zbreakpoint @var{number}
688 The program hit breakpoint number @var{number}.
691 @item ^Z^Zwatchpoint @var{number}
692 The program hit watchpoint number @var{number}.
695 @node Source Annotations
696 @section Displaying Source
697 @cindex annotations for source display
700 The following annotation is used instead of displaying source code:
703 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
706 where @var{filename} is an absolute file name indicating which source
707 file, @var{line} is the line number within that file (where 1 is the
708 first line in the file), @var{character} is the character position
709 within the file (where 0 is the first character in the file) (for most
710 debug formats this will necessarily point to the beginning of a line),
711 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
712 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
713 @var{addr} is the address in the target program associated with the
714 source which is being displayed. @var{addr} is in the form @samp{0x}
715 followed by one or more lowercase hex digits (note that this does not
716 depend on the language).
719 @section Annotations We Might Want in the Future
723 the target might have changed (registers, heap contents, or
724 execution status). For performance, we might eventually want
725 to hit `registers-invalid' and `all-registers-invalid' with
728 - systematic annotation for set/show parameters (including
729 invalidation notices).
731 - similarly, `info' returns a list of candidates for invalidation