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. The frame ends with
285 Between these annotations is the main body of the frame, which can
290 @findex function-call
293 @var{function-call-string}
296 where @var{function-call-string} is text designed to convey to the user
297 that this frame is associated with a function call made by GDB to a
298 function in the program being debugged.
301 @findex signal-handler-caller
303 ^Z^Zsignal-handler-caller
304 @var{signal-handler-caller-string}
307 where @var{signal-handler-caller-string} is text designed to convey to
308 the user that this frame is associated with whatever mechanism is used
309 by this operating system to call a signal handler (it is the frame which
310 calls the signal handler, not the frame for the signal handler itself).
315 @findex frame-address
316 @findex frame-address-end
317 This can optionally (depending on whether this is thought of as
318 interesting information for the user to see) begin with
323 ^Z^Zframe-address-end
324 @var{separator-string}
327 where @var{address} is the address executing in the frame (the same
328 address as in the @code{frame-begin} annotation), and
329 @var{separator-string} is a string intended to separate this address
330 from what follows for the user's benefit.
332 @findex frame-function-name
337 ^Z^Zframe-function-name
343 where @var{function-name} is the name of the function executing in the
344 frame, or @samp{??} if not known, and @var{arguments} are the arguments
345 to the frame, with parentheses around them (each argument is annotated
346 individually as well @pxref{Values}).
348 @findex frame-source-begin
349 @findex frame-source-file
350 @findex frame-source-file-end
351 @findex frame-source-line
352 @findex frame-source-end
353 If source information is available, a reference to it is then printed:
356 ^Z^Zframe-source-begin
357 @var{source-intro-string}
358 ^Z^Zframe-source-file
360 ^Z^Zframe-source-file-end
362 ^Z^Zframe-source-line
367 where @var{source-intro-string} separates for the user's benefit the
368 reference from the text which precedes it, @var{filename} is the name of
369 the source file, and @var{line-number} is the line number within that
370 file (the first line is line 1).
373 If GDB prints some information about where the frame is from (which
374 library, which load segment, etc.; currently only done on the RS/6000),
382 Then, if source is to actually be displayed for this frame (for example,
383 this is not true for output from the @code{backtrace} command), then a
384 @code{source} annotation (@pxref{Source}) is displayed. Unlike most
385 annotations, this is output instead of the normal text which would be
386 output, not in addition.
392 @findex display-begin
393 @findex display-number-end
394 @findex display-format
395 @findex display-expression
396 @findex display-expression-end
397 @findex display-value
399 When GDB is told to display something using the @code{display} command,
400 the results of the display are annotated:
405 ^Z^Zdisplay-number-end
406 @var{number-separator}
409 ^Z^Zdisplay-expression
411 ^Z^Zdisplay-expression-end
412 @var{expression-separator}
418 where @var{number} is the number of the display, @var{number-separator}
419 is intended to separate the number from what follows for the user,
420 @var{format} includes information such as the size, format, or other
421 information about how the value is being displayed, @var{expression} is
422 the expression being displayed, @var{expression-separator} is intended
423 to separate the expression from the text that follows for the user,
424 and @var{value} is the actual value being displayed.
427 @chapter Annotation for GDB Input
429 When GDB prompts for input, it annotates this fact so it is possible
430 to know when to send output, when the output from a given command is
433 Different kinds of input each have a different @dfn{input type}. Each
434 input type has three annotations: a @code{pre-} annotation, which
435 denotes the beginning of any prompt which is being output, a plain
436 annotation, which denotes the end of the prompt, and then a @code{post-}
437 annotation which denotes the end of any echo which may (or may not) be
438 associated with the input. For example, the @code{prompt} input type
439 features the following annotations:
454 When GDB is prompting for a command (the main GDB prompt).
458 @findex post-commands
460 When GDB prompts for a set of commands, like in the @code{commands}
461 command. The annotations are repeated for each command which is input.
463 @findex pre-overload-choice
464 @findex overload-choice
465 @findex post-overload-choice
466 @item overload-choice
467 When GDB wants the user to select between various overloaded functions.
473 When GDB wants the user to confirm a potentially dangerous operation.
475 @findex pre-prompt-for-continue
476 @findex prompt-for-continue
477 @findex post-prompt-for-continue
478 @item prompt-for-continue
479 When GDB is asking the user to press return to continue. Note: Don't
480 expect this to work well; instead use @code{set height 0} to disable
481 prompting. This is because the counting of lines is buggy in the
482 presence of annotations.
493 This annotation occurs right before GDB responds to an interrupt.
500 This annotation occurs right before GDB responds to an error.
502 Quit and error annotations indicate that any annotations which GDB was
503 in the middle of may end abruptly. For example, if a
504 @code{value-history-begin} annotation is followed by a @code{error}, one
505 cannot expect to receive the matching @code{value-history-end}. One
506 cannot expect not to receive it either, however; an error annotation
507 does not necessarily mean that GDB is immediately returning all the way
511 A quit or error annotation may be preceded by
517 Any output between that and the quit or error annotation is the error
520 Warning messages are not yet annotated.
521 @c If we want to change that, need to fix warning(), type_error(),
522 @c range_error(), and possibly other places.
524 @node Breakpoint Info
525 @chapter Information on Breakpoints
527 The output from the @code{info breakpoints} command is annotated as follows:
529 @findex breakpoints-headers
530 @findex breakpoints-table
532 ^Z^Zbreakpoints-headers
534 ^Z^Zbreakpoints-table
537 where @var{header-entry} has the same syntax as an entry (see below) but
538 instead of containing data, it contains strings which are intended to
539 convey the meaning of each field to the user. This is followed by any
540 number of entries. If a field does not apply for this entry, it is
541 omitted. Fields may contain trailing whitespace. Each entry consists
572 @findex breakpoints-table-end
574 ^Z^Zbreakpoints-table-end
578 @chapter Invalidation Notices
580 The following annotations say that certain pieces of state may have
584 @findex frames-invalid
585 @item ^Z^Zframes-invalid
587 The frames (for example, output from the @code{backtrace} command) may
590 @findex breakpoints-invalid
591 @item ^Z^Zbreakpoints-invalid
593 The breakpoints may have changed. For example, the user just added or
594 deleted a breakpoint.
598 @chapter Running the Program
602 When the program starts executing due to a GDB command such as
603 @code{step} or @code{continue},
609 is output. When the program stops,
615 is output. Before the @code{stopped} annotation, a variety of
616 annotations describe how the program stopped.
620 @item ^Z^Zexited @var{exit-status}
621 The program exited, and @var{exit-status} is the exit status (zero for
622 successful exit, otherwise nonzero).
626 @findex signal-name-end
627 @findex signal-string
628 @findex signal-string-end
630 The program exited with a signal. After the @code{^Z^Zsignalled}, the
631 annotation continues:
641 ^Z^Zsignal-string-end
645 where @var{name} is the name of the signal, such as @code{SIGILL} or
646 @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
647 as @code{Illegal Instruction} or @code{Segmentation fault}.
648 @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
649 user's benefit and have no particular format.
653 The syntax of this annotation is just like @code{signalled}, but GDB is
654 just saying that the program received the signal, not that it was
658 @item ^Z^Zbreakpoint @var{number}
659 The program hit breakpoint number @var{number}.
662 @item ^Z^Zwatchpoint @var{number}
663 The program hit watchpoint number @var{number}.
667 @chapter Displaying Source
670 The following annotation is used instead of displaying source code:
673 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
676 where @var{filename} is an absolute file name indicating which source
677 file, @var{line} is the line number within that file (where 1 is the
678 first line in the file), @var{character} is the character position
679 within the file (where 0 is the first character in the file) (for most
680 debug formats this will necessarily point to the beginning of a line),
681 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
682 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
683 @var{addr} is the address in the target program associated with the
684 source which is being displayed.
687 @chapter Annotations We Might Want in the Future
691 the target might have changed (registers, heap contents, or
692 execution status). For performance, we might eventually want
693 to hit `registers-invalid' and `all-registers-invalid' with
696 - systematic annotation for set/show parameters (including
697 invalidation notices).
699 - similarly, `info' returns a list of candidates for invalidation