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
60 @chapter @value{GDBN} Annotations
63 This chapter describes annotations in @value{GDBN}. Annotations are
64 designed to interface @value{GDBN} to graphical user interfaces or other
65 similar programs which want to interact with @value{GDBN} at a
66 relatively high level.
69 This is Edition @value{EDITION}, @value{DATE}.
73 * Annotations Overview:: What annotations are; the general syntax.
74 * Server Prefix:: Issuing a command without affecting user state.
75 * Value Annotations:: Values are marked as such.
76 * Frame Annotations:: Stack frames are annotated.
77 * Displays:: @value{GDBN} can be told to display something periodically.
78 * Prompting:: Annotations marking @value{GDBN}'s need for input.
79 * Errors:: Annotations for error messages.
80 * Breakpoint Info:: Information on breakpoints.
81 * Invalidation:: Some annotations describe things now invalid.
82 * Annotations for Running::
83 Whether the program is running, how it stopped, etc.
84 * Source Annotations:: Annotations describing source code.
85 * TODO:: Annotations which might be added in the future.
88 @node Annotations Overview
89 @section What is an Annotation?
92 To produce annotations, start @value{GDBN} with the @code{--annotate=2} option.
94 Annotations start with a newline character, two @samp{control-z}
95 characters, and the name of the annotation. If there is no additional
96 information associated with this annotation, the name of the annotation
97 is followed immediately by a newline. If there is additional
98 information, the name of the annotation is followed by a space, the
99 additional information, and a newline. The additional information
100 cannot contain newline characters.
102 Any output not beginning with a newline and two @samp{control-z}
103 characters denotes literal output from @value{GDBN}. Currently there is
104 no need for @value{GDBN} to output a newline followed by two
105 @samp{control-z} characters, but if there was such a need, the
106 annotations could be extended with an @samp{escape} annotation which
107 means those three characters as output.
109 A simple example of starting up @value{GDBN} with annotations is:
114 Copyright 2000 Free Software Foundation, Inc.
115 GDB is free software, covered by the GNU General Public License,
116 and you are welcome to change it and/or distribute copies of it
117 under certain conditions.
118 Type "show copying" to see the conditions.
119 There is absolutely no warranty for GDB. Type "show warranty"
121 This GDB was configured as "sparc-sun-sunos4.1.3"
132 Here @samp{quit} is input to @value{GDBN}; the rest is output from
133 @value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z}
134 denotes a @samp{control-z} character) are annotations; the rest is
135 output from @value{GDBN}.
138 @section The Server Prefix
139 @cindex server prefix for annotations
141 To issue a command to @value{GDBN} without affecting certain aspects of
142 the state which is seen by users, prefix it with @samp{server }. This
143 means that this command will not affect the command history, nor will it
144 affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
145 pressed on a line by itself.
147 The server prefix does not affect the recording of values into the value
148 history; to print a value without recording it into the value history,
149 use the @code{output} command instead of the @code{print} command.
151 @node Value Annotations
154 @cindex annotations for values
155 When a value is printed in various contexts, @value{GDBN} uses
156 annotations to delimit the value from the surrounding text.
158 @findex value-history-begin
159 @findex value-history-value
160 @findex value-history-end
161 If a value is printed using @code{print} and added to the value history,
162 the annotation looks like
165 ^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
167 ^Z^Zvalue-history-value
169 ^Z^Zvalue-history-end
172 where @var{history-number} is the number it is getting in the value
173 history, @var{history-string} is a string, such as @samp{$5 = }, which
174 introduces the value to the user, @var{the-value} is the output
175 corresponding to the value itself, and @var{value-flags} is @samp{*} for
176 a value which can be dereferenced and @samp{-} for a value which cannot.
180 If the value is not added to the value history (it is an invalid float
181 or it is printed with the @code{output} command), the annotation is similar:
184 ^Z^Zvalue-begin @var{value-flags}
193 When @value{GDBN} prints an argument to a function (for example, in the output
194 from the @code{backtrace} command), it annotates it as follows:
200 @var{separator-string}
201 ^Z^Zarg-value @var{value-flags}
206 where @var{argument-name} is the name of the argument,
207 @var{separator-string} is text which separates the name from the value
208 for the user's benefit (such as @samp{=}), and @var{value-flags} and
209 @var{the-value} have the same meanings as in a
210 @code{value-history-begin} annotation.
213 @findex field-name-end
216 When printing a structure, @value{GDBN} annotates it as follows:
219 ^Z^Zfield-begin @var{value-flags}
222 @var{separator-string}
228 where @var{field-name} is the name of the field, @var{separator-string}
229 is text which separates the name from the value for the user's benefit
230 (such as @samp{=}), and @var{value-flags} and @var{the-value} have the
231 same meanings as in a @code{value-history-begin} annotation.
233 When printing an array, @value{GDBN} annotates it as follows:
236 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
239 where @var{array-index} is the index of the first element being
240 annotated and @var{value-flags} has the same meaning as in a
241 @code{value-history-begin} annotation. This is followed by any number
242 of elements, where is element can be either a single element:
246 @samp{,} @var{whitespace} ; @r{omitted for the first element}
251 or a repeated element
256 @samp{,} @var{whitespace} ; @r{omitted for the first element}
258 ^Z^Zelt-rep @var{number-of-repititions}
259 @var{repetition-string}
263 In both cases, @var{the-value} is the output for the value of the
264 element and @var{whitespace} can contain spaces, tabs, and newlines. In
265 the repeated case, @var{number-of-repititons} is the number of
266 consecutive array elements which contain that value, and
267 @var{repetition-string} is a string which is designed to convey to the
268 user that repitition is being depicted.
270 @findex array-section-end
271 Once all the array elements have been output, the array annotation is
275 ^Z^Zarray-section-end
278 @node Frame Annotations
281 @cindex annotations for frames
282 Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
283 to frames printed when @value{GDBN} stops, output from commands such as
284 @code{backtrace} or @code{up}, etc.
287 The frame annotation begins with
290 ^Z^Zframe-begin @var{level} @var{address}
294 where @var{level} is the number of the frame (0 is the innermost frame,
295 and other frames have positive numbers), @var{address} is the address of
296 the code executing in that frame, and @var{level-string} is a string
297 designed to convey the level to the user. @var{address} is in the form
298 @samp{0x} followed by one or more lowercase hex digits (note that this
299 does not depend on the language). The frame ends with
306 Between these annotations is the main body of the frame, which can
311 @findex function-call
314 @var{function-call-string}
317 where @var{function-call-string} is text designed to convey to the user
318 that this frame is associated with a function call made by @value{GDBN} to a
319 function in the program being debugged.
322 @findex signal-handler-caller
324 ^Z^Zsignal-handler-caller
325 @var{signal-handler-caller-string}
328 where @var{signal-handler-caller-string} is text designed to convey to
329 the user that this frame is associated with whatever mechanism is used
330 by this operating system to call a signal handler (it is the frame which
331 calls the signal handler, not the frame for the signal handler itself).
336 @findex frame-address
337 @findex frame-address-end
338 This can optionally (depending on whether this is thought of as
339 interesting information for the user to see) begin with
344 ^Z^Zframe-address-end
345 @var{separator-string}
348 where @var{address} is the address executing in the frame (the same
349 address as in the @code{frame-begin} annotation, but printed in a form
350 which is intended for user consumption---in particular, the syntax varies
351 depending on the language), and @var{separator-string} is a string
352 intended to separate this address from what follows for the user's
355 @findex frame-function-name
360 ^Z^Zframe-function-name
366 where @var{function-name} is the name of the function executing in the
367 frame, or @samp{??} if not known, and @var{arguments} are the arguments
368 to the frame, with parentheses around them (each argument is annotated
369 individually as well, @pxref{Value Annotations}).
371 @findex frame-source-begin
372 @findex frame-source-file
373 @findex frame-source-file-end
374 @findex frame-source-line
375 @findex frame-source-end
376 If source information is available, a reference to it is then printed:
379 ^Z^Zframe-source-begin
380 @var{source-intro-string}
381 ^Z^Zframe-source-file
383 ^Z^Zframe-source-file-end
385 ^Z^Zframe-source-line
390 where @var{source-intro-string} separates for the user's benefit the
391 reference from the text which precedes it, @var{filename} is the name of
392 the source file, and @var{line-number} is the line number within that
393 file (the first line is line 1).
396 If @value{GDBN} prints some information about where the frame is from (which
397 library, which load segment, etc.; currently only done on the RS/6000),
405 Then, if source is to actually be displayed for this frame (for example,
406 this is not true for output from the @code{backtrace} command), then a
407 @code{source} annotation (@pxref{Source}) is displayed. Unlike most
408 annotations, this is output instead of the normal text which would be
409 output, not in addition.
415 @findex display-begin
416 @findex display-number-end
417 @findex display-format
418 @findex display-expression
419 @findex display-expression-end
420 @findex display-value
422 @cindex annotations for display
423 When @value{GDBN} is told to display something using the @code{display} command,
424 the results of the display are annotated:
429 ^Z^Zdisplay-number-end
430 @var{number-separator}
433 ^Z^Zdisplay-expression
435 ^Z^Zdisplay-expression-end
436 @var{expression-separator}
442 where @var{number} is the number of the display, @var{number-separator}
443 is intended to separate the number from what follows for the user,
444 @var{format} includes information such as the size, format, or other
445 information about how the value is being displayed, @var{expression} is
446 the expression being displayed, @var{expression-separator} is intended
447 to separate the expression from the text that follows for the user,
448 and @var{value} is the actual value being displayed.
451 @section Annotation for @value{GDBN} Input
453 @cindex annotations for prompts
454 When @value{GDBN} prompts for input, it annotates this fact so it is possible
455 to know when to send output, when the output from a given command is
458 Different kinds of input each have a different @dfn{input type}. Each
459 input type has three annotations: a @code{pre-} annotation, which
460 denotes the beginning of any prompt which is being output, a plain
461 annotation, which denotes the end of the prompt, and then a @code{post-}
462 annotation which denotes the end of any echo which may (or may not) be
463 associated with the input. For example, the @code{prompt} input type
464 features the following annotations:
479 When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
483 @findex post-commands
485 When @value{GDBN} prompts for a set of commands, like in the @code{commands}
486 command. The annotations are repeated for each command which is input.
488 @findex pre-overload-choice
489 @findex overload-choice
490 @findex post-overload-choice
491 @item overload-choice
492 When @value{GDBN} wants the user to select between various overloaded functions.
498 When @value{GDBN} wants the user to confirm a potentially dangerous operation.
500 @findex pre-prompt-for-continue
501 @findex prompt-for-continue
502 @findex post-prompt-for-continue
503 @item prompt-for-continue
504 When @value{GDBN} is asking the user to press return to continue. Note: Don't
505 expect this to work well; instead use @code{set height 0} to disable
506 prompting. This is because the counting of lines is buggy in the
507 presence of annotations.
512 @cindex annotations for errors, warnings and interrupts
519 This annotation occurs right before @value{GDBN} responds to an interrupt.
526 This annotation occurs right before @value{GDBN} responds to an error.
528 Quit and error annotations indicate that any annotations which @value{GDBN} was
529 in the middle of may end abruptly. For example, if a
530 @code{value-history-begin} annotation is followed by a @code{error}, one
531 cannot expect to receive the matching @code{value-history-end}. One
532 cannot expect not to receive it either, however; an error annotation
533 does not necessarily mean that @value{GDBN} is immediately returning all the way
537 A quit or error annotation may be preceded by
543 Any output between that and the quit or error annotation is the error
546 Warning messages are not yet annotated.
547 @c If we want to change that, need to fix warning(), type_error(),
548 @c range_error(), and possibly other places.
550 @node Breakpoint Info
551 @section Information on Breakpoints
553 @cindex annotations for breakpoints
554 The output from the @code{info breakpoints} command is annotated as follows:
556 @findex breakpoints-headers
557 @findex breakpoints-table
559 ^Z^Zbreakpoints-headers
561 ^Z^Zbreakpoints-table
564 where @var{header-entry} has the same syntax as an entry (see below) but
565 instead of containing data, it contains strings which are intended to
566 convey the meaning of each field to the user. This is followed by any
567 number of entries. If a field does not apply for this entry, it is
568 omitted. Fields may contain trailing whitespace. Each entry consists
597 Note that @var{address} is intended for user consumption---the syntax
598 varies depending on the language.
602 @findex breakpoints-table-end
604 ^Z^Zbreakpoints-table-end
608 @section Invalidation Notices
610 @cindex annotations for invalidation messages
611 The following annotations say that certain pieces of state may have
615 @findex frames-invalid
616 @item ^Z^Zframes-invalid
618 The frames (for example, output from the @code{backtrace} command) may
621 @findex breakpoints-invalid
622 @item ^Z^Zbreakpoints-invalid
624 The breakpoints may have changed. For example, the user just added or
625 deleted a breakpoint.
628 @node Annotations for Running
629 @section Running the Program
630 @cindex annotations for running programs
634 When the program starts executing due to a @value{GDBN} command such as
635 @code{step} or @code{continue},
641 is output. When the program stops,
647 is output. Before the @code{stopped} annotation, a variety of
648 annotations describe how the program stopped.
652 @item ^Z^Zexited @var{exit-status}
653 The program exited, and @var{exit-status} is the exit status (zero for
654 successful exit, otherwise nonzero).
658 @findex signal-name-end
659 @findex signal-string
660 @findex signal-string-end
662 The program exited with a signal. After the @code{^Z^Zsignalled}, the
663 annotation continues:
673 ^Z^Zsignal-string-end
677 where @var{name} is the name of the signal, such as @code{SIGILL} or
678 @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
679 as @code{Illegal Instruction} or @code{Segmentation fault}.
680 @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
681 user's benefit and have no particular format.
685 The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
686 just saying that the program received the signal, not that it was
690 @item ^Z^Zbreakpoint @var{number}
691 The program hit breakpoint number @var{number}.
694 @item ^Z^Zwatchpoint @var{number}
695 The program hit watchpoint number @var{number}.
698 @node Source Annotations
699 @section Displaying Source
700 @cindex annotations for source display
703 The following annotation is used instead of displaying source code:
706 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
709 where @var{filename} is an absolute file name indicating which source
710 file, @var{line} is the line number within that file (where 1 is the
711 first line in the file), @var{character} is the character position
712 within the file (where 0 is the first character in the file) (for most
713 debug formats this will necessarily point to the beginning of a line),
714 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
715 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
716 @var{addr} is the address in the target program associated with the
717 source which is being displayed. @var{addr} is in the form @samp{0x}
718 followed by one or more lowercase hex digits (note that this does not
719 depend on the language).
722 @section Annotations We Might Want in the Future
726 the target might have changed (registers, heap contents, or
727 execution status). For performance, we might eventually want
728 to hit `registers-invalid' and `all-registers-invalid' with
731 - systematic annotation for set/show parameters (including
732 invalidation notices).
734 - similarly, `info' returns a list of candidates for invalidation