Upgrade GDB from 7.4.1 to 7.6.1 on the vendor branch
[dragonfly.git] / contrib / gdb-7 / gdb / doc / annotate.texinfo
1 \input texinfo   @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename annotate.info
4
5 @c This is a dir.info fragment to support semi-automated addition of
6 @c manuals to an info tree.
7 @dircategory Software development
8 @direntry
9 * Annotate: (annotate).                 The obsolete annotation interface.
10 @end direntry
11
12 @c
13 @include gdb-cfg.texi
14 @c
15 @settitle @value{GDBN}'s Obsolete Annotations
16 @setchapternewpage off
17 @c %**end of header
18
19 @set EDITION 1.0
20 @set DATE July 2003
21
22 @c NOTE: cagney/2003-07-28:
23 @c Don't make this migration document an appendix of GDB's user guide.
24 @c By keeping this separate, the size of the user guide is contained. If
25 @c the user guide to get much bigger it would need to switch to a larger,
26 @c more expensive, form factor and would drive up the manuals publication
27 @c cost.  Having a smaller cheaper manual helps the GNU Press with its sales.
28
29 @copying
30 Copyright @copyright{} 1994-2013 Free Software Foundation, Inc.
31
32 Permission is granted to copy, distribute and/or modify this document
33 under the terms of the GNU Free Documentation License, Version 1.3 or
34 any later version published by the Free Software Foundation; with no
35 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
36 Texts.  A copy of the license is included in the section entitled ``GNU
37 Free Documentation License''.
38 @end copying
39
40 @ifnottex
41 This file documents @value{GDBN}'s obsolete annotations.
42
43 @insertcopying
44 @end ifnottex
45
46 @titlepage
47 @title @value{GDBN}'s Obsolete Annotations
48 @subtitle Edition @value{EDITION}
49 @subtitle @value{DATE}
50 @author Free Software Foundation
51 @page
52 @vskip 0pt plus 1filll
53 @insertcopying
54 @end titlepage
55
56 @ifnottex
57 @node Top
58 @top GDB Annotations
59
60 This document describes the obsolete level two annotation interface
61 implemented in older @value{GDBN} versions.
62
63 @ignore
64 This is Edition @value{EDITION}, @value{DATE}.
65 @end ignore
66 @end ifnottex
67
68 @menu
69 * Annotations Overview::  What annotations are; the general syntax.
70 * Limitations::           Limitations of the annotation interface.
71 * Migrating to GDB/MI::   Migrating to GDB/MI
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 * Multi-threaded Apps:: An annotation that reports multi-threadedness.
84
85 * GNU Free Documentation License::
86 @end menu
87
88 @contents
89
90 @node Annotations Overview
91 @chapter What is an Annotation?
92 @cindex annotations
93
94 To produce obsolete level two annotations, start @value{GDBN} with the
95 @code{--annotate=2} option.
96
97 Annotations start with a newline character, two @samp{control-z}
98 characters, and the name of the annotation.  If there is no additional
99 information associated with this annotation, the name of the annotation
100 is followed immediately by a newline.  If there is additional
101 information, the name of the annotation is followed by a space, the
102 additional information, and a newline.  The additional information
103 cannot contain newline characters.
104
105 Any output not beginning with a newline and two @samp{control-z}
106 characters denotes literal output from @value{GDBN}.  Currently there is
107 no need for @value{GDBN} to output a newline followed by two
108 @samp{control-z} characters, but if there was such a need, the
109 annotations could be extended with an @samp{escape} annotation which
110 means those three characters as output.
111
112 A simple example of starting up @value{GDBN} with annotations is:
113
114 @smallexample
115 $ gdb --annotate=2
116 GNU GDB 5.0
117 Copyright 2000 Free Software Foundation, Inc.
118 GDB is free software, covered by the GNU General Public License,
119 and you are welcome to change it and/or distribute copies of it
120 under certain conditions.
121 Type "show copying" to see the conditions.
122 There is absolutely no warranty for GDB.  Type "show warranty"
123 for details.
124 This GDB was configured as "sparc-sun-sunos4.1.3"
125
126 ^Z^Zpre-prompt
127 (gdb) 
128 ^Z^Zprompt
129 quit
130
131 ^Z^Zpost-prompt
132
133 @end smallexample
134
135 Here @samp{quit} is input to @value{GDBN}; the rest is output from
136 @value{GDBN}.  The three lines beginning @samp{^Z^Z} (where @samp{^Z}
137 denotes a @samp{control-z} character) are annotations; the rest is
138 output from @value{GDBN}.
139
140 @node Limitations
141 @chapter Limitations of the Annotation Interface
142
143 The level two annotations mechanism is known to have a number of
144 technical and architectural limitations.  As a consequence, in 2001,
145 with the release of @value{GDBN} 5.1 and the addition of @sc{gdb/mi},
146 the annotation interface was marked as deprecated.
147
148 This chapter discusses the known problems.
149
150 @section Dependant on @sc{cli} output
151
152 The annotation interface works by interspersing markups with
153 @value{GDBN} normal command-line interpreter output.  Unfortunately, this
154 makes the annotation client dependant on not just the annotations, but
155 also the @sc{cli} output.  This is because the client is forced to
156 assume that specific @value{GDBN} commands provide specific information.
157 Any change to @value{GDBN}'s @sc{cli} output modifies or removes that
158 information and, consequently, likely breaks the client.
159
160 Since the @sc{gdb/mi} output is independent of the @sc{cli}, it does not
161 have this problem.
162
163 @section Scalability
164
165 The annotation interface relies on value annotations (@pxref{Value
166 Annotations}) and the display mechanism as a way of obtaining up-to-date
167 value information.  These mechanisms are not scalable.
168
169 In a graphical environment, where many values can be displayed
170 simultaneously, a serious performance problem occurs when the client
171 tries to first extract from @value{GDBN}, and then re-display, all those
172 values.  The client should instead only request and update the values
173 that changed.
174
175 The @sc{gdb/mi} Variable Objects provide just that mechanism.
176
177 @section Correctness
178
179 The annotation interface assumes that a variable's value can only be
180 changed when the target is running.  This assumption is not correct.  A
181 single assignment to a single variable can result in the entire target,
182 and all displayed values, needing an update.
183
184 The @sc{gdb/mi} Variable Objects include a mechanism for efficiently
185 reporting such changes.
186
187 @section Reliability
188
189 The @sc{gdb/mi} interface includes a dedicated test directory
190 (@file{gdb/gdb.mi}), and any addition or fix to @sc{gdb/mi} must include
191 testsuite changes.
192
193 @section Maintainability
194
195 The annotation mechanism was implemented by interspersing @sc{cli} print
196 statements with various annotations.  As a consequence, any @sc{cli}
197 output change can alter the annotation output.
198
199 Since the @sc{gdb/mi} output is independent of the @sc{cli}, and the
200 @sc{gdb/mi} is increasingly implemented independent of the @sc{cli}
201 code, its long term maintenance is much easier.
202
203 @node Migrating to GDB/MI
204 @chapter Migrating to @sc{gdb/mi}
205
206 By using the @samp{interp mi} command, it is possible for annotation
207 clients to invoke @sc{gdb/mi} commands, and hence access the
208 @sc{gdb/mi}.  By doing this, existing annotation clients have a
209 migration path from this obsolete interface to @sc{gdb/mi}.
210
211 @node Server Prefix
212 @chapter The Server Prefix
213 @cindex server prefix for annotations
214
215 To issue a command to @value{GDBN} without affecting certain aspects of
216 the state which is seen by users, prefix it with @samp{server }.  This
217 means that this command will not affect the command history, nor will it
218 affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
219 pressed on a line by itself.
220
221 The server prefix does not affect the recording of values into the value
222 history; to print a value without recording it into the value history,
223 use the @code{output} command instead of the @code{print} command.
224
225 @node Value Annotations
226 @chapter Values
227
228 @emph{Value Annotations have been removed.  @sc{gdb/mi} instead provides
229 Variable Objects.}
230
231 @cindex annotations for values
232 When a value is printed in various contexts, @value{GDBN} uses
233 annotations to delimit the value from the surrounding text.
234
235 @findex value-history-begin
236 @findex value-history-value
237 @findex value-history-end
238 If a value is printed using @code{print} and added to the value history,
239 the annotation looks like
240
241 @smallexample
242 ^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
243 @var{history-string}
244 ^Z^Zvalue-history-value
245 @var{the-value}
246 ^Z^Zvalue-history-end
247 @end smallexample
248
249 @noindent
250 where @var{history-number} is the number it is getting in the value
251 history, @var{history-string} is a string, such as @samp{$5 = }, which
252 introduces the value to the user, @var{the-value} is the output
253 corresponding to the value itself, and @var{value-flags} is @samp{*} for
254 a value which can be dereferenced and @samp{-} for a value which cannot.
255
256 @findex value-begin
257 @findex value-end
258 If the value is not added to the value history (it is an invalid float
259 or it is printed with the @code{output} command), the annotation is similar:
260
261 @smallexample
262 ^Z^Zvalue-begin @var{value-flags}
263 @var{the-value}
264 ^Z^Zvalue-end
265 @end smallexample
266
267 @findex arg-begin
268 @findex arg-name-end
269 @findex arg-value
270 @findex arg-end
271 When @value{GDBN} prints an argument to a function (for example, in the output
272 from the @code{backtrace} command), it annotates it as follows:
273
274 @smallexample
275 ^Z^Zarg-begin
276 @var{argument-name}
277 ^Z^Zarg-name-end
278 @var{separator-string}
279 ^Z^Zarg-value @var{value-flags}
280 @var{the-value}
281 ^Z^Zarg-end
282 @end smallexample
283
284 @noindent
285 where @var{argument-name} is the name of the argument,
286 @var{separator-string} is text which separates the name from the value
287 for the user's benefit (such as @samp{=}), and @var{value-flags} and
288 @var{the-value} have the same meanings as in a
289 @code{value-history-begin} annotation.
290
291 @findex field-begin
292 @findex field-name-end
293 @findex field-value
294 @findex field-end
295 When printing a structure, @value{GDBN} annotates it as follows:
296
297 @smallexample
298 ^Z^Zfield-begin @var{value-flags}
299 @var{field-name}
300 ^Z^Zfield-name-end
301 @var{separator-string}
302 ^Z^Zfield-value
303 @var{the-value}
304 ^Z^Zfield-end
305 @end smallexample
306
307 @noindent
308 where @var{field-name} is the name of the field, @var{separator-string}
309 is text which separates the name from the value for the user's benefit
310 (such as @samp{=}), and @var{value-flags} and @var{the-value} have the
311 same meanings as in a @code{value-history-begin} annotation.
312
313 When printing an array, @value{GDBN} annotates it as follows:
314
315 @smallexample
316 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
317 @end smallexample
318
319 @noindent
320 where @var{array-index} is the index of the first element being
321 annotated and @var{value-flags} has the same meaning as in a
322 @code{value-history-begin} annotation.  This is followed by any number
323 of elements, where is element can be either a single element:
324
325 @findex elt
326 @smallexample
327 @samp{,} @var{whitespace}         ; @r{omitted for the first element}
328 @var{the-value}
329 ^Z^Zelt
330 @end smallexample
331
332 or a repeated element
333
334 @findex elt-rep
335 @findex elt-rep-end
336 @smallexample
337 @samp{,} @var{whitespace}         ; @r{omitted for the first element}
338 @var{the-value}
339 ^Z^Zelt-rep @var{number-of-repetitions}
340 @var{repetition-string}
341 ^Z^Zelt-rep-end
342 @end smallexample
343
344 In both cases, @var{the-value} is the output for the value of the
345 element and @var{whitespace} can contain spaces, tabs, and newlines.  In
346 the repeated case, @var{number-of-repetitions} is the number of
347 consecutive array elements which contain that value, and
348 @var{repetition-string} is a string which is designed to convey to the
349 user that repetition is being depicted.
350
351 @findex array-section-end
352 Once all the array elements have been output, the array annotation is
353 ended with
354
355 @smallexample
356 ^Z^Zarray-section-end
357 @end smallexample
358
359 @node Frame Annotations
360 @chapter Frames
361
362 @emph{Value Annotations have been removed.  @sc{gdb/mi} instead provides
363 a number of frame commands.}
364
365 @emph{Frame annotations are no longer available.  The @sc{gdb/mi}
366 provides @samp{-stack-list-arguments}, @samp{-stack-list-locals}, and
367 @samp{-stack-list-frames} commands.}
368
369 @cindex annotations for frames
370 Whenever @value{GDBN} prints a frame, it annotates it.  For example, this applies
371 to frames printed when @value{GDBN} stops, output from commands such as
372 @code{backtrace} or @code{up}, etc.
373
374 @findex frame-begin
375 The frame annotation begins with
376
377 @smallexample
378 ^Z^Zframe-begin @var{level} @var{address}
379 @var{level-string}
380 @end smallexample
381
382 @noindent
383 where @var{level} is the number of the frame (0 is the innermost frame,
384 and other frames have positive numbers), @var{address} is the address of
385 the code executing in that frame, and @var{level-string} is a string
386 designed to convey the level to the user.  @var{address} is in the form
387 @samp{0x} followed by one or more lowercase hex digits (note that this
388 does not depend on the language).  The frame ends with
389
390 @findex frame-end
391 @smallexample
392 ^Z^Zframe-end
393 @end smallexample
394
395 Between these annotations is the main body of the frame, which can
396 consist of
397
398 @itemize @bullet
399 @item
400 @findex function-call
401 @smallexample
402 ^Z^Zfunction-call
403 @var{function-call-string}
404 @end smallexample
405
406 where @var{function-call-string} is text designed to convey to the user
407 that this frame is associated with a function call made by @value{GDBN} to a
408 function in the program being debugged.
409
410 @item
411 @findex signal-handler-caller
412 @smallexample
413 ^Z^Zsignal-handler-caller
414 @var{signal-handler-caller-string}
415 @end smallexample
416
417 where @var{signal-handler-caller-string} is text designed to convey to
418 the user that this frame is associated with whatever mechanism is used
419 by this operating system to call a signal handler (it is the frame which
420 calls the signal handler, not the frame for the signal handler itself).
421
422 @item
423 A normal frame.
424
425 @findex frame-address
426 @findex frame-address-end
427 This can optionally (depending on whether this is thought of as
428 interesting information for the user to see) begin with
429
430 @smallexample
431 ^Z^Zframe-address
432 @var{address}
433 ^Z^Zframe-address-end
434 @var{separator-string}
435 @end smallexample
436
437 where @var{address} is the address executing in the frame (the same
438 address as in the @code{frame-begin} annotation, but printed in a form
439 which is intended for user consumption---in particular, the syntax varies
440 depending on the language), and @var{separator-string} is a string
441 intended to separate this address from what follows for the user's
442 benefit.
443
444 @findex frame-function-name
445 @findex frame-args
446 Then comes
447
448 @smallexample
449 ^Z^Zframe-function-name
450 @var{function-name}
451 ^Z^Zframe-args
452 @var{arguments}
453 @end smallexample
454
455 where @var{function-name} is the name of the function executing in the
456 frame, or @samp{??} if not known, and @var{arguments} are the arguments
457 to the frame, with parentheses around them (each argument is annotated
458 individually as well, @pxref{Value Annotations}).
459
460 @findex frame-source-begin
461 @findex frame-source-file
462 @findex frame-source-file-end
463 @findex frame-source-line
464 @findex frame-source-end
465 If source information is available, a reference to it is then printed:
466
467 @smallexample
468 ^Z^Zframe-source-begin
469 @var{source-intro-string}
470 ^Z^Zframe-source-file
471 @var{filename}
472 ^Z^Zframe-source-file-end
473 :
474 ^Z^Zframe-source-line
475 @var{line-number}
476 ^Z^Zframe-source-end
477 @end smallexample
478
479 where @var{source-intro-string} separates for the user's benefit the
480 reference from the text which precedes it, @var{filename} is the name of
481 the source file, and @var{line-number} is the line number within that
482 file (the first line is line 1).
483
484 @findex frame-where
485 If @value{GDBN} prints some information about where the frame is from (which
486 library, which load segment, etc.; currently only done on the RS/6000),
487 it is annotated with
488
489 @smallexample
490 ^Z^Zframe-where
491 @var{information}
492 @end smallexample
493
494 Then, if source is to actually be displayed for this frame (for example,
495 this is not true for output from the @code{backtrace} command), then a
496 @code{source} annotation (@pxref{Source Annotations}) is displayed.  Unlike
497 most annotations, this is output instead of the normal text which would be
498 output, not in addition.
499 @end itemize
500
501 @node Displays
502 @chapter Displays
503
504 @emph{Display Annotations have been removed.  @sc{gdb/mi} instead
505 provides Variable Objects.}
506
507 @findex display-begin
508 @findex display-number-end
509 @findex display-format
510 @findex display-expression
511 @findex display-expression-end
512 @findex display-value
513 @findex display-end
514 @cindex annotations for display
515 When @value{GDBN} is told to display something using the @code{display} command,
516 the results of the display are annotated:
517
518 @smallexample
519 ^Z^Zdisplay-begin
520 @var{number}
521 ^Z^Zdisplay-number-end
522 @var{number-separator}
523 ^Z^Zdisplay-format
524 @var{format}
525 ^Z^Zdisplay-expression
526 @var{expression}
527 ^Z^Zdisplay-expression-end
528 @var{expression-separator}
529 ^Z^Zdisplay-value
530 @var{value}
531 ^Z^Zdisplay-end
532 @end smallexample
533
534 @noindent
535 where @var{number} is the number of the display, @var{number-separator}
536 is intended to separate the number from what follows for the user,
537 @var{format} includes information such as the size, format, or other
538 information about how the value is being displayed, @var{expression} is
539 the expression being displayed, @var{expression-separator} is intended
540 to separate the expression from the text that follows for the user,
541 and @var{value} is the actual value being displayed.
542
543 @node Prompting
544 @chapter Annotation for @value{GDBN} Input
545
546 @cindex annotations for prompts
547 When @value{GDBN} prompts for input, it annotates this fact so it is possible
548 to know when to send output, when the output from a given command is
549 over, etc.
550
551 Different kinds of input each have a different @dfn{input type}.  Each
552 input type has three annotations: a @code{pre-} annotation, which
553 denotes the beginning of any prompt which is being output, a plain
554 annotation, which denotes the end of the prompt, and then a @code{post-}
555 annotation which denotes the end of any echo which may (or may not) be
556 associated with the input.  For example, the @code{prompt} input type
557 features the following annotations:
558
559 @smallexample
560 ^Z^Zpre-prompt
561 ^Z^Zprompt
562 ^Z^Zpost-prompt
563 @end smallexample
564
565 The input types are
566
567 @table @code
568 @findex pre-prompt
569 @findex prompt
570 @findex post-prompt
571 @item prompt
572 When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
573
574 @findex pre-commands
575 @findex commands
576 @findex post-commands
577 @item commands
578 When @value{GDBN} prompts for a set of commands, like in the @code{commands}
579 command.  The annotations are repeated for each command which is input.
580
581 @findex pre-overload-choice
582 @findex overload-choice
583 @findex post-overload-choice
584 @item overload-choice
585 When @value{GDBN} wants the user to select between various overloaded functions.
586
587 @findex pre-query
588 @findex query
589 @findex post-query
590 @item query
591 When @value{GDBN} wants the user to confirm a potentially dangerous operation.
592
593 @findex pre-prompt-for-continue
594 @findex prompt-for-continue
595 @findex post-prompt-for-continue
596 @item prompt-for-continue
597 When @value{GDBN} is asking the user to press return to continue.  Note: Don't
598 expect this to work well; instead use @code{set height 0} to disable
599 prompting.  This is because the counting of lines is buggy in the
600 presence of annotations.
601 @end table
602
603 @node Errors
604 @chapter Errors
605 @cindex annotations for errors, warnings and interrupts
606
607 @findex quit
608 @smallexample
609 ^Z^Zquit
610 @end smallexample
611
612 This annotation occurs right before @value{GDBN} responds to an interrupt.
613
614 @findex error
615 @smallexample
616 ^Z^Zerror
617 @end smallexample
618
619 This annotation occurs right before @value{GDBN} responds to an error.
620
621 Quit and error annotations indicate that any annotations which @value{GDBN} was
622 in the middle of may end abruptly.  For example, if a
623 @code{value-history-begin} annotation is followed by a @code{error}, one
624 cannot expect to receive the matching @code{value-history-end}.  One
625 cannot expect not to receive it either, however; an error annotation
626 does not necessarily mean that @value{GDBN} is immediately returning all the way
627 to the top level.
628
629 @findex error-begin
630 A quit or error annotation may be preceded by
631
632 @smallexample
633 ^Z^Zerror-begin
634 @end smallexample
635
636 Any output between that and the quit or error annotation is the error
637 message.
638
639 Warning messages are not yet annotated.
640 @c If we want to change that, need to fix warning(), type_error(),
641 @c range_error(), and possibly other places.
642
643 @node Breakpoint Info
644 @chapter Information on Breakpoints
645
646 @emph{Breakpoint Annotations have been removed.  @sc{gdb/mi} instead
647 provides breakpoint commands.}
648
649 @cindex annotations for breakpoints
650 The output from the @code{info breakpoints} command is annotated as follows:
651
652 @findex breakpoints-headers
653 @findex breakpoints-table
654 @smallexample
655 ^Z^Zbreakpoints-headers
656 @var{header-entry}
657 ^Z^Zbreakpoints-table
658 @end smallexample
659
660 @noindent
661 where @var{header-entry} has the same syntax as an entry (see below) but
662 instead of containing data, it contains strings which are intended to
663 convey the meaning of each field to the user.  This is followed by any
664 number of entries.  If a field does not apply for this entry, it is
665 omitted.  Fields may contain trailing whitespace.  Each entry consists
666 of:
667
668 @findex record
669 @findex field
670 @smallexample
671 ^Z^Zrecord
672 ^Z^Zfield 0
673 @var{number}
674 ^Z^Zfield 1
675 @var{type}
676 ^Z^Zfield 2
677 @var{disposition}
678 ^Z^Zfield 3
679 @var{enable}
680 ^Z^Zfield 4
681 @var{address}
682 ^Z^Zfield 5
683 @var{what}
684 ^Z^Zfield 6
685 @var{frame}
686 ^Z^Zfield 7
687 @var{condition}
688 ^Z^Zfield 8
689 @var{ignore-count}
690 ^Z^Zfield 9
691 @var{commands}
692 @end smallexample
693
694 Note that @var{address} is intended for user consumption---the syntax
695 varies depending on the language.
696
697 The output ends with
698
699 @findex breakpoints-table-end
700 @smallexample
701 ^Z^Zbreakpoints-table-end
702 @end smallexample
703
704 @node Invalidation
705 @chapter Invalidation Notices
706
707 @cindex annotations for invalidation messages
708 The following annotations say that certain pieces of state may have
709 changed.
710
711 @table @code
712 @findex frames-invalid
713 @item ^Z^Zframes-invalid
714
715 The frames (for example, output from the @code{backtrace} command) may
716 have changed.
717
718 @findex breakpoints-invalid
719 @item ^Z^Zbreakpoints-invalid
720
721 The breakpoints may have changed.  For example, the user just added or
722 deleted a breakpoint.
723 @end table
724
725 @node Annotations for Running
726 @chapter Running the Program
727 @cindex annotations for running programs
728
729 @findex starting
730 @findex stopping
731 When the program starts executing due to a @value{GDBN} command such as
732 @code{step} or @code{continue}, 
733
734 @smallexample
735 ^Z^Zstarting
736 @end smallexample
737
738 is output.  When the program stops, 
739
740 @smallexample
741 ^Z^Zstopped
742 @end smallexample
743
744 is output.  Before the @code{stopped} annotation, a variety of
745 annotations describe how the program stopped.
746
747 @table @code
748 @findex exited
749 @item ^Z^Zexited @var{exit-status}
750 The program exited, and @var{exit-status} is the exit status (zero for
751 successful exit, otherwise nonzero).
752
753 @findex signalled
754 @findex signal-name
755 @findex signal-name-end
756 @findex signal-string
757 @findex signal-string-end
758 @item ^Z^Zsignalled
759 The program exited with a signal.  After the @code{^Z^Zsignalled}, the
760 annotation continues:
761
762 @smallexample
763 @var{intro-text}
764 ^Z^Zsignal-name
765 @var{name}
766 ^Z^Zsignal-name-end
767 @var{middle-text}
768 ^Z^Zsignal-string
769 @var{string}
770 ^Z^Zsignal-string-end
771 @var{end-text}
772 @end smallexample
773
774 @noindent
775 where @var{name} is the name of the signal, such as @code{SIGILL} or
776 @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
777 as @code{Illegal Instruction} or @code{Segmentation fault}.
778 @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
779 user's benefit and have no particular format.
780
781 @findex signal
782 @item ^Z^Zsignal
783 The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
784 just saying that the program received the signal, not that it was
785 terminated with it.
786
787 @findex breakpoint
788 @item ^Z^Zbreakpoint @var{number}
789 The program hit breakpoint number @var{number}.
790
791 @findex watchpoint
792 @item ^Z^Zwatchpoint @var{number}
793 The program hit watchpoint number @var{number}.
794 @end table
795
796 @node Source Annotations
797 @chapter Displaying Source
798 @cindex annotations for source display
799
800 @findex source
801 The following annotation is used instead of displaying source code:
802
803 @smallexample
804 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
805 @end smallexample
806
807 where @var{filename} is an absolute file name indicating which source
808 file, @var{line} is the line number within that file (where 1 is the
809 first line in the file), @var{character} is the character position
810 within the file (where 0 is the first character in the file) (for most
811 debug formats this will necessarily point to the beginning of a line),
812 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
813 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
814 @var{addr} is the address in the target program associated with the
815 source which is being displayed.  @var{addr} is in the form @samp{0x}
816 followed by one or more lowercase hex digits (note that this does not
817 depend on the language).
818
819 @node Multi-threaded Apps
820 @chapter Multi-threaded Applications
821 @cindex annotations for multi-threaded apps
822
823 The following annotations report thread related changes of state.
824
825 @table @code
826 @findex new-thread@r{, annotation}
827 @item ^Z^Znew-thread
828
829 This annotation is issued once for each thread that is created apart from
830 the main thread, which is not reported.
831
832 @findex thread-changed@r{, annotation}
833 @item ^Z^Zthread-changed
834
835 The selected thread has changed.  This may occur at the request of the
836 user with the @code{thread} command, or as a result of execution,
837 e.g., another thread hits a breakpoint.
838
839 @end table
840
841 @node GNU Free Documentation License
842 @appendix GNU Free Documentation License
843 @include fdl.texi
844
845 @ignore
846 @node Index
847 @unnumbered Index
848
849 @printindex fn
850 @end ignore
851
852 @bye