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 Free Software Foundation
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
59 @chapter @value{GDBN} Annotations
61 This chapter describes annotations in @value{GDBN}, the GNU symbolic debugger.
62 Annotations are designed to interface @value{GDBN} to graphical user interfaces
63 or other 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 no need
102 for @value{GDBN} to output a newline followed by two @samp{control-z} characters,
103 but if there was such a need, the annotations could be extended with an
104 @samp{escape} annotation which means those three characters as output.
106 A simple example of starting up @value{GDBN} with annotations is:
111 Copyright 2000 Free Software Foundation, Inc.
112 GDB is free software, covered by the GNU General Public License, and you are
113 welcome to change it and/or distribute copies of it under certain conditions.
114 Type "show copying" to see the conditions.
115 There is absolutely no warranty for GDB. Type "show warranty" for details.
116 This GDB was configured as "sparc-sun-sunos4.1.3"
127 Here @samp{quit} is input to @value{GDBN}; the rest is output from @value{GDBN}. The three
128 lines beginning @samp{^Z^Z} (where @samp{^Z} denotes a @samp{control-z}
129 character) are annotations; the rest is output from @value{GDBN}.
132 @section The Server Prefix
133 @cindex server prefix for annotations
135 To issue a command to @value{GDBN} without affecting certain aspects of the state
136 which is seen by users, prefix it with @samp{server }. This means that
137 this command will not affect the command history, nor will it affect
138 @value{GDBN}'s notion of which command to repeat if @key{RET} is pressed on a
141 The server prefix does not affect the recording of values into the value
142 history; to print a value without recording it into the value history,
143 use the @code{output} command instead of the @code{print} command.
145 @node Value Annotations
148 @cindex annotations for values
149 When a value is printed in various contexts, @value{GDBN} uses annotations to
150 delimit the value from the surrounding text.
152 @findex value-history-begin
153 @findex value-history-value
154 @findex value-history-end
155 If a value is printed using @code{print} and added to the value history,
156 the annotation looks like
159 ^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
161 ^Z^Zvalue-history-value
163 ^Z^Zvalue-history-end
166 where @var{history-number} is the number it is getting in the value
167 history, @var{history-string} is a string, such as @samp{$5 = }, which
168 introduces the value to the user, @var{the-value} is the output
169 corresponding to the value itself, and @var{value-flags} is @samp{*} for
170 a value which can be dereferenced and @samp{-} for a value which cannot.
174 If the value is not added to the value history (it is an invalid float
175 or it is printed with the @code{output} command), the annotation is similar:
178 ^Z^Zvalue-begin @var{value-flags}
187 When @value{GDBN} prints an argument to a function (for example, in the output
188 from the @code{backtrace} command), it annotates it as follows:
194 @var{separator-string}
195 ^Z^Zarg-value @var{value-flags}
200 where @var{argument-name} is the name of the argument,
201 @var{separator-string} is text which separates the name from the value
202 for the user's benefit (such as @samp{=}), and @var{value-flags} and
203 @var{the-value} have the same meanings as in a
204 @code{value-history-begin} annotation.
207 @findex field-name-end
210 When printing a structure, @value{GDBN} annotates it as follows:
213 ^Z^Zfield-begin @var{value-flags}
216 @var{separator-string}
222 where @var{field-name} is the name of the field, @var{separator-string}
223 is text which separates the name from the value for the user's benefit
224 (such as @samp{=}), and @var{value-flags} and @var{the-value} have the
225 same meanings as in a @code{value-history-begin} annotation.
227 When printing an array, @value{GDBN} annotates it as follows:
230 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
233 where @var{array-index} is the index of the first element being
234 annotated and @var{value-flags} has the same meaning as in a
235 @code{value-history-begin} annotation. This is followed by any number
236 of elements, where is element can be either a single element:
240 @samp{,} @var{whitespace} ; @r{omitted for the first element}
245 or a repeated element
250 @samp{,} @var{whitespace} ; @r{omitted for the first element}
252 ^Z^Zelt-rep @var{number-of-repititions}
253 @var{repetition-string}
257 In both cases, @var{the-value} is the output for the value of the
258 element and @var{whitespace} can contain spaces, tabs, and newlines. In
259 the repeated case, @var{number-of-repititons} is the number of
260 consecutive array elements which contain that value, and
261 @var{repetition-string} is a string which is designed to convey to the
262 user that repitition is being depicted.
264 @findex array-section-end
265 Once all the array elements have been output, the array annotation is
269 ^Z^Zarray-section-end
272 @node Frame Annotations
275 @cindex annotations for frames
276 Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
277 to frames printed when @value{GDBN} stops, output from commands such as
278 @code{backtrace} or @code{up}, etc.
281 The frame annotation begins with
284 ^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}) is displayed. Unlike most
402 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}
436 where @var{number} is the number of the display, @var{number-separator}
437 is intended to separate the number from what follows for the user,
438 @var{format} includes information such as the size, format, or other
439 information about how the value is being displayed, @var{expression} is
440 the expression being displayed, @var{expression-separator} is intended
441 to separate the expression from the text that follows for the user,
442 and @var{value} is the actual value being displayed.
445 @section Annotation for @value{GDBN} Input
447 @cindex annotations for prompts
448 When @value{GDBN} prompts for input, it annotates this fact so it is possible
449 to know when to send output, when the output from a given command is
452 Different kinds of input each have a different @dfn{input type}. Each
453 input type has three annotations: a @code{pre-} annotation, which
454 denotes the beginning of any prompt which is being output, a plain
455 annotation, which denotes the end of the prompt, and then a @code{post-}
456 annotation which denotes the end of any echo which may (or may not) be
457 associated with the input. For example, the @code{prompt} input type
458 features the following annotations:
473 When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
477 @findex post-commands
479 When @value{GDBN} prompts for a set of commands, like in the @code{commands}
480 command. The annotations are repeated for each command which is input.
482 @findex pre-overload-choice
483 @findex overload-choice
484 @findex post-overload-choice
485 @item overload-choice
486 When @value{GDBN} wants the user to select between various overloaded functions.
492 When @value{GDBN} wants the user to confirm a potentially dangerous operation.
494 @findex pre-prompt-for-continue
495 @findex prompt-for-continue
496 @findex post-prompt-for-continue
497 @item prompt-for-continue
498 When @value{GDBN} is asking the user to press return to continue. Note: Don't
499 expect this to work well; instead use @code{set height 0} to disable
500 prompting. This is because the counting of lines is buggy in the
501 presence of annotations.
506 @cindex annotations for errors, warnings and interrupts
513 This annotation occurs right before @value{GDBN} responds to an interrupt.
520 This annotation occurs right before @value{GDBN} responds to an error.
522 Quit and error annotations indicate that any annotations which @value{GDBN} was
523 in the middle of may end abruptly. For example, if a
524 @code{value-history-begin} annotation is followed by a @code{error}, one
525 cannot expect to receive the matching @code{value-history-end}. One
526 cannot expect not to receive it either, however; an error annotation
527 does not necessarily mean that @value{GDBN} is immediately returning all the way
531 A quit or error annotation may be preceded by
537 Any output between that and the quit or error annotation is the error
540 Warning messages are not yet annotated.
541 @c If we want to change that, need to fix warning(), type_error(),
542 @c range_error(), and possibly other places.
544 @node Breakpoint Info
545 @section Information on Breakpoints
547 @cindex annotations for breakpoints
548 The output from the @code{info breakpoints} command is annotated as follows:
550 @findex breakpoints-headers
551 @findex breakpoints-table
553 ^Z^Zbreakpoints-headers
555 ^Z^Zbreakpoints-table
558 where @var{header-entry} has the same syntax as an entry (see below) but
559 instead of containing data, it contains strings which are intended to
560 convey the meaning of each field to the user. This is followed by any
561 number of entries. If a field does not apply for this entry, it is
562 omitted. Fields may contain trailing whitespace. Each entry consists
591 Note that @var{address} is intended for user consumption---the syntax
592 varies depending on the language.
596 @findex breakpoints-table-end
598 ^Z^Zbreakpoints-table-end
602 @section Invalidation Notices
604 @cindex annotations for invalidation messages
605 The following annotations say that certain pieces of state may have
609 @findex frames-invalid
610 @item ^Z^Zframes-invalid
612 The frames (for example, output from the @code{backtrace} command) may
615 @findex breakpoints-invalid
616 @item ^Z^Zbreakpoints-invalid
618 The breakpoints may have changed. For example, the user just added or
619 deleted a breakpoint.
622 @node Annotations for Running
623 @section Running the Program
624 @cindex annotations for running programs
628 When the program starts executing due to a @value{GDBN} command such as
629 @code{step} or @code{continue},
635 is output. When the program stops,
641 is output. Before the @code{stopped} annotation, a variety of
642 annotations describe how the program stopped.
646 @item ^Z^Zexited @var{exit-status}
647 The program exited, and @var{exit-status} is the exit status (zero for
648 successful exit, otherwise nonzero).
652 @findex signal-name-end
653 @findex signal-string
654 @findex signal-string-end
656 The program exited with a signal. After the @code{^Z^Zsignalled}, the
657 annotation continues:
667 ^Z^Zsignal-string-end
671 where @var{name} is the name of the signal, such as @code{SIGILL} or
672 @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
673 as @code{Illegal Instruction} or @code{Segmentation fault}.
674 @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
675 user's benefit and have no particular format.
679 The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
680 just saying that the program received the signal, not that it was
684 @item ^Z^Zbreakpoint @var{number}
685 The program hit breakpoint number @var{number}.
688 @item ^Z^Zwatchpoint @var{number}
689 The program hit watchpoint number @var{number}.
692 @node Source Annotations
693 @section Displaying Source
694 @cindex annotations for source display
697 The following annotation is used instead of displaying source code:
700 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
703 where @var{filename} is an absolute file name indicating which source
704 file, @var{line} is the line number within that file (where 1 is the
705 first line in the file), @var{character} is the character position
706 within the file (where 0 is the first character in the file) (for most
707 debug formats this will necessarily point to the beginning of a line),
708 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
709 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
710 @var{addr} is the address in the target program associated with the
711 source which is being displayed. @var{addr} is in the form @samp{0x}
712 followed by one or more lowercase hex digits (note that this does not
713 depend on the language).
716 @section Annotations We Might Want in the Future
720 the target might have changed (registers, heap contents, or
721 execution status). For performance, we might eventually want
722 to hit `registers-invalid' and `all-registers-invalid' with
725 - systematic annotation for set/show parameters (including
726 invalidation notices).
728 - similarly, `info' returns a list of candidates for invalidation