1 \input texinfo @c -*-texinfo-*-
3 @setfilename annotate.info
4 @settitle GDB Annotations
12 This file documents GDB annotations.
14 This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB
15 Annotations}. Copyright 1994 Free Software Foundation
17 Permission is granted to make and distribute verbatim copies of
18 this manual provided the copyright notice and this permission notice
19 are preserved on all copies.
22 Permission is granted to process this file through TeX and print the
23 results, provided the printed document carries copying permission
24 notice identical to this one except for the removal of this paragraph
25 (this paragraph not being relevant to the printed manual).
28 Permission is granted to copy and distribute modified versions of this
29 manual under the conditions for verbatim copying, provided also that the
30 entire resulting derived work is distributed under the terms of a
31 permission notice identical to this one.
33 Permission is granted to copy and distribute translations of this manual
34 into another language, under the above conditions for modified versions.
38 @title GDB Annotations
39 @subtitle Edition @value{EDITION}
40 @subtitle @value{DATE}
41 @author Cygnus Support
43 @vskip 0pt plus 1filll
44 Permission is granted to make and distribute verbatim copies of
45 this manual provided the copyright notice and this permission notice
46 are preserved on all copies.
48 Copyright @copyright{} 1994 Free Software Foundation
55 This file describes annotations in GDB, the GNU symbolic debugger.
56 Annotations are designed to interface GDB to graphical user interfaces
57 or other similar programs which want to interact with GDB at a
58 relatively high level.
60 This is Edition @value{EDITION}, @value{DATE}.
63 * General:: What annotations are; the general syntax.
64 * Server:: Issuing a command without affecting user state.
65 * Values:: Values are marked as such.
66 * Frames:: Stack frames are annotated.
67 * Displays:: GDB can be told to display something periodically.
68 * Prompting:: Annotations marking GDB's need for input.
69 * Errors:: Annotations for error messages.
70 * Breakpoint Info:: Information on breakpoints.
71 * Invalidation:: Some annotations describe things now invalid.
72 * Running:: Whether the program is running, how it stopped, etc.
73 * Source:: Annotations describing source code.
74 * TODO:: Annotations which might be added in the future.
80 @chapter What is an Annotation?
82 To produce annotations, start GDB with the @code{--annotate=2} option.
84 Annotations start with a newline character, two @samp{control-z}
85 characters, and the name of the annotation. If there is no additional
86 information associated with this annotation, the name of the annotation
87 is followed immediately by a newline. If there is additional
88 information, the name of the annotation is followed by a space, the
89 additional information, and a newline. The additional information
90 cannot contain newline characters.
92 Any output not beginning with a newline and two @samp{control-z}
93 characters denotes literal output from GDB. Currently there is no need
94 for GDB to output a newline followed by two @samp{control-z} characters,
95 but if there was such a need, the annotations could be extended with an
96 @samp{escape} annotation which means those three characters as output.
98 A simple example of starting up GDB with annotations is:
102 GDB is free software and you are welcome to distribute copies of it
103 under certain conditions; type "show copying" to see the conditions.
104 There is absolutely no warranty for GDB; type "show warranty" for details.
105 GDB 4.12.3 (sparc-sun-sunos4.1.3),
106 Copyright 1994 Free Software Foundation, Inc.
117 Here @samp{quit} is input to GDB; the rest is output from GDB. The three
118 lines beginning @samp{^Z^Z} (where @samp{^Z} denotes a @samp{control-z}
119 character) are annotations; the rest is output from GDB.
122 @chapter The Server Prefix
124 To issue a command to GDB without affecting certain aspects of the state
125 which is seen by users, prefix it with @samp{server }. This means that
126 this command will not affect the command history, nor will it affect
127 GDB's notion of which command to repeat if @key{RET} is pressed on a
130 The server prefix does not affect the recording of values into the value
131 history; to print a value without recording it into the value history,
132 use the @code{output} command instead of the @code{print} command.
137 When a value is printed in various contexts, GDB uses annotations to
138 delimit the value from the surrounding text.
140 @findex value-history-begin
141 @findex value-history-value
142 @findex value-history-end
143 If a value is printed using @code{print} and added to the value history,
144 the annotation looks like
147 ^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
149 ^Z^Zvalue-history-value
151 ^Z^Zvalue-history-end
154 where @var{history-number} is the number it is getting in the value
155 history, @var{history-string} is a string, such as @samp{$5 = }, which
156 introduces the value to the user, @var{the-value} is the output
157 corresponding to the value itself, and @var{value-flags} is @samp{*} for
158 a value which can be dereferenced and @samp{-} for a value which cannot.
162 If the value is not added to the value history (it is an invalid float
163 or it is printed with the @code{output} command), the annotation is similar:
166 ^Z^Zvalue-begin @var{value-flags}
175 When GDB prints an argument to a function (for example, in the output
176 from the @code{backtrace} command), it annotates it as follows:
182 @var{separator-string}
183 ^Z^Zarg-value @var{value-flags}
188 where @var{argument-name} is the name of the argument,
189 @var{separator-string} is text which separates the name from the value
190 for the user's benefit (such as @samp{=}), and @var{value-flags} and
191 @var{the-value} have the same meanings as in a
192 @code{value-history-begin} annotation.
195 @findex field-name-end
198 When printing a structure, GDB annotates it as follows:
201 ^Z^Zfield-begin @var{value-flags}
204 @var{separator-string}
210 where @var{field-name} is the name of the field, @var{separator-string}
211 is text which separates the name from the value for the user's benefit
212 (such as @samp{=}), and @var{value-flags} and @var{the-value} have the
213 same meanings as in a @code{value-history-begin} annotation.
215 When printing an array, GDB annotates it as follows:
218 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
221 where @var{array-index} is the index of the first element being
222 annotated and @var{value-flags} has the same meaning as in a
223 @code{value-history-begin} annotation. This is followed by any number
224 of elements, where is element can be either a single element:
228 @samp{,} @var{whitespace} ; @r{omitted for the first element}
233 or a repeated element
238 @samp{,} @var{whitespace} ; @r{omitted for the first element}
240 ^Z^Zelt-rep @var{number-of-repititions}
241 @var{repetition-string}
245 In both cases, @var{the-value} is the output for the value of the
246 element and @var{whitespace} can contain spaces, tabs, and newlines. In
247 the repeated case, @var{number-of-repititons} is the number of
248 consecutive array elements which contain that value, and
249 @var{repetition-string} is a string which is designed to convey to the
250 user that repitition is being depicted.
252 @findex array-section-end
253 Once all the array elements have been output, the array annotation is
257 ^Z^Zarray-section-end
263 Whenever GDB prints a frame, it annotates it. For example, this applies
264 to frames printed when GDB stops, output from commands such as
265 @code{backtrace} or @code{up}, etc.
268 The frame annotation begins with
271 ^Z^Zframe-begin @var{level} @var{address}
275 where @var{level} is the number of the frame (0 is the innermost frame,
276 and other frames have positive numbers), @var{address} is the address of
277 the code executing in that frame, and @var{level-string} is a string
278 designed to convey the level to the user. @var{address} is in the form
279 @samp{0x} followed by one or more lowercase hex digits (note that this
280 does not depend on the language). The frame ends with
287 Between these annotations is the main body of the frame, which can
292 @findex function-call
295 @var{function-call-string}
298 where @var{function-call-string} is text designed to convey to the user
299 that this frame is associated with a function call made by GDB to a
300 function in the program being debugged.
303 @findex signal-handler-caller
305 ^Z^Zsignal-handler-caller
306 @var{signal-handler-caller-string}
309 where @var{signal-handler-caller-string} is text designed to convey to
310 the user that this frame is associated with whatever mechanism is used
311 by this operating system to call a signal handler (it is the frame which
312 calls the signal handler, not the frame for the signal handler itself).
317 @findex frame-address
318 @findex frame-address-end
319 This can optionally (depending on whether this is thought of as
320 interesting information for the user to see) begin with
325 ^Z^Zframe-address-end
326 @var{separator-string}
329 where @var{address} is the address executing in the frame (the same
330 address as in the @code{frame-begin} annotation, but printed in a form
331 which is intended for user consumption---in particular, the syntax varies
332 depending on the language), and @var{separator-string} is a string
333 intended to separate this address from what follows for the user's
336 @findex frame-function-name
341 ^Z^Zframe-function-name
347 where @var{function-name} is the name of the function executing in the
348 frame, or @samp{??} if not known, and @var{arguments} are the arguments
349 to the frame, with parentheses around them (each argument is annotated
350 individually as well @pxref{Values}).
352 @findex frame-source-begin
353 @findex frame-source-file
354 @findex frame-source-file-end
355 @findex frame-source-line
356 @findex frame-source-end
357 If source information is available, a reference to it is then printed:
360 ^Z^Zframe-source-begin
361 @var{source-intro-string}
362 ^Z^Zframe-source-file
364 ^Z^Zframe-source-file-end
366 ^Z^Zframe-source-line
371 where @var{source-intro-string} separates for the user's benefit the
372 reference from the text which precedes it, @var{filename} is the name of
373 the source file, and @var{line-number} is the line number within that
374 file (the first line is line 1).
377 If GDB prints some information about where the frame is from (which
378 library, which load segment, etc.; currently only done on the RS/6000),
386 Then, if source is to actually be displayed for this frame (for example,
387 this is not true for output from the @code{backtrace} command), then a
388 @code{source} annotation (@pxref{Source}) is displayed. Unlike most
389 annotations, this is output instead of the normal text which would be
390 output, not in addition.
396 @findex display-begin
397 @findex display-number-end
398 @findex display-format
399 @findex display-expression
400 @findex display-expression-end
401 @findex display-value
403 When GDB is told to display something using the @code{display} command,
404 the results of the display are annotated:
409 ^Z^Zdisplay-number-end
410 @var{number-separator}
413 ^Z^Zdisplay-expression
415 ^Z^Zdisplay-expression-end
416 @var{expression-separator}
422 where @var{number} is the number of the display, @var{number-separator}
423 is intended to separate the number from what follows for the user,
424 @var{format} includes information such as the size, format, or other
425 information about how the value is being displayed, @var{expression} is
426 the expression being displayed, @var{expression-separator} is intended
427 to separate the expression from the text that follows for the user,
428 and @var{value} is the actual value being displayed.
431 @chapter Annotation for GDB Input
433 When GDB prompts for input, it annotates this fact so it is possible
434 to know when to send output, when the output from a given command is
437 Different kinds of input each have a different @dfn{input type}. Each
438 input type has three annotations: a @code{pre-} annotation, which
439 denotes the beginning of any prompt which is being output, a plain
440 annotation, which denotes the end of the prompt, and then a @code{post-}
441 annotation which denotes the end of any echo which may (or may not) be
442 associated with the input. For example, the @code{prompt} input type
443 features the following annotations:
458 When GDB is prompting for a command (the main GDB prompt).
462 @findex post-commands
464 When GDB prompts for a set of commands, like in the @code{commands}
465 command. The annotations are repeated for each command which is input.
467 @findex pre-overload-choice
468 @findex overload-choice
469 @findex post-overload-choice
470 @item overload-choice
471 When GDB wants the user to select between various overloaded functions.
477 When GDB wants the user to confirm a potentially dangerous operation.
479 @findex pre-prompt-for-continue
480 @findex prompt-for-continue
481 @findex post-prompt-for-continue
482 @item prompt-for-continue
483 When GDB is asking the user to press return to continue. Note: Don't
484 expect this to work well; instead use @code{set height 0} to disable
485 prompting. This is because the counting of lines is buggy in the
486 presence of annotations.
497 This annotation occurs right before GDB responds to an interrupt.
504 This annotation occurs right before GDB responds to an error.
506 Quit and error annotations indicate that any annotations which GDB was
507 in the middle of may end abruptly. For example, if a
508 @code{value-history-begin} annotation is followed by a @code{error}, one
509 cannot expect to receive the matching @code{value-history-end}. One
510 cannot expect not to receive it either, however; an error annotation
511 does not necessarily mean that GDB is immediately returning all the way
515 A quit or error annotation may be preceded by
521 Any output between that and the quit or error annotation is the error
524 Warning messages are not yet annotated.
525 @c If we want to change that, need to fix warning(), type_error(),
526 @c range_error(), and possibly other places.
528 @node Breakpoint Info
529 @chapter Information on Breakpoints
531 The output from the @code{info breakpoints} command is annotated as follows:
533 @findex breakpoints-headers
534 @findex breakpoints-table
536 ^Z^Zbreakpoints-headers
538 ^Z^Zbreakpoints-table
541 where @var{header-entry} has the same syntax as an entry (see below) but
542 instead of containing data, it contains strings which are intended to
543 convey the meaning of each field to the user. This is followed by any
544 number of entries. If a field does not apply for this entry, it is
545 omitted. Fields may contain trailing whitespace. Each entry consists
574 Note that @var{address} is intended for user consumption---the syntax
575 varies depending on the language.
579 @findex breakpoints-table-end
581 ^Z^Zbreakpoints-table-end
585 @chapter Invalidation Notices
587 The following annotations say that certain pieces of state may have
591 @findex frames-invalid
592 @item ^Z^Zframes-invalid
594 The frames (for example, output from the @code{backtrace} command) may
597 @findex breakpoints-invalid
598 @item ^Z^Zbreakpoints-invalid
600 The breakpoints may have changed. For example, the user just added or
601 deleted a breakpoint.
605 @chapter Running the Program
609 When the program starts executing due to a GDB command such as
610 @code{step} or @code{continue},
616 is output. When the program stops,
622 is output. Before the @code{stopped} annotation, a variety of
623 annotations describe how the program stopped.
627 @item ^Z^Zexited @var{exit-status}
628 The program exited, and @var{exit-status} is the exit status (zero for
629 successful exit, otherwise nonzero).
633 @findex signal-name-end
634 @findex signal-string
635 @findex signal-string-end
637 The program exited with a signal. After the @code{^Z^Zsignalled}, the
638 annotation continues:
648 ^Z^Zsignal-string-end
652 where @var{name} is the name of the signal, such as @code{SIGILL} or
653 @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
654 as @code{Illegal Instruction} or @code{Segmentation fault}.
655 @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
656 user's benefit and have no particular format.
660 The syntax of this annotation is just like @code{signalled}, but GDB is
661 just saying that the program received the signal, not that it was
665 @item ^Z^Zbreakpoint @var{number}
666 The program hit breakpoint number @var{number}.
669 @item ^Z^Zwatchpoint @var{number}
670 The program hit watchpoint number @var{number}.
674 @chapter Displaying Source
677 The following annotation is used instead of displaying source code:
680 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
683 where @var{filename} is an absolute file name indicating which source
684 file, @var{line} is the line number within that file (where 1 is the
685 first line in the file), @var{character} is the character position
686 within the file (where 0 is the first character in the file) (for most
687 debug formats this will necessarily point to the beginning of a line),
688 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
689 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
690 @var{addr} is the address in the target program associated with the
691 source which is being displayed. @var{addr} is in the form @samp{0x}
692 followed by one or more lowercase hex digits (note that this does not
693 depend on the language).
696 @chapter Annotations We Might Want in the Future
700 the target might have changed (registers, heap contents, or
701 execution status). For performance, we might eventually want
702 to hit `registers-invalid' and `all-registers-invalid' with
705 - systematic annotation for set/show parameters (including
706 invalidation notices).
708 - similarly, `info' returns a list of candidates for invalidation