Upgrade GDB from 7.4.1 to 7.6.1 on the vendor branch
[dragonfly.git] / contrib / gdb-7 / gdb / doc / annotate.texinfo
CommitLineData
5796c8dc
SS
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
ef5ccd6c 30Copyright @copyright{} 1994-2013 Free Software Foundation, Inc.
5796c8dc
SS
31
32Permission is granted to copy, distribute and/or modify this document
cf7f2e2d 33under the terms of the GNU Free Documentation License, Version 1.3 or
5796c8dc
SS
34any later version published by the Free Software Foundation; with no
35Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
36Texts. A copy of the license is included in the section entitled ``GNU
37Free Documentation License''.
38@end copying
39
40@ifnottex
41This 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
60This document describes the obsolete level two annotation interface
61implemented in older @value{GDBN} versions.
62
63@ignore
64This 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
94To produce obsolete level two annotations, start @value{GDBN} with the
95@code{--annotate=2} option.
96
97Annotations start with a newline character, two @samp{control-z}
98characters, and the name of the annotation. If there is no additional
99information associated with this annotation, the name of the annotation
100is followed immediately by a newline. If there is additional
101information, the name of the annotation is followed by a space, the
102additional information, and a newline. The additional information
103cannot contain newline characters.
104
105Any output not beginning with a newline and two @samp{control-z}
106characters denotes literal output from @value{GDBN}. Currently there is
107no need for @value{GDBN} to output a newline followed by two
108@samp{control-z} characters, but if there was such a need, the
109annotations could be extended with an @samp{escape} annotation which
110means those three characters as output.
111
112A simple example of starting up @value{GDBN} with annotations is:
113
114@smallexample
115$ gdb --annotate=2
116GNU GDB 5.0
117Copyright 2000 Free Software Foundation, Inc.
118GDB is free software, covered by the GNU General Public License,
119and you are welcome to change it and/or distribute copies of it
120under certain conditions.
121Type "show copying" to see the conditions.
122There is absolutely no warranty for GDB. Type "show warranty"
123for details.
124This GDB was configured as "sparc-sun-sunos4.1.3"
125
126^Z^Zpre-prompt
127(gdb)
128^Z^Zprompt
129quit
130
131^Z^Zpost-prompt
132$
133@end smallexample
134
135Here @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}
137denotes a @samp{control-z} character) are annotations; the rest is
138output from @value{GDBN}.
139
140@node Limitations
141@chapter Limitations of the Annotation Interface
142
143The level two annotations mechanism is known to have a number of
144technical and architectural limitations. As a consequence, in 2001,
145with the release of @value{GDBN} 5.1 and the addition of @sc{gdb/mi},
146the annotation interface was marked as deprecated.
147
148This chapter discusses the known problems.
149
150@section Dependant on @sc{cli} output
151
152The annotation interface works by interspersing markups with
153@value{GDBN} normal command-line interpreter output. Unfortunately, this
154makes the annotation client dependant on not just the annotations, but
155also the @sc{cli} output. This is because the client is forced to
156assume that specific @value{GDBN} commands provide specific information.
157Any change to @value{GDBN}'s @sc{cli} output modifies or removes that
158information and, consequently, likely breaks the client.
159
160Since the @sc{gdb/mi} output is independent of the @sc{cli}, it does not
161have this problem.
162
163@section Scalability
164
165The annotation interface relies on value annotations (@pxref{Value
166Annotations}) and the display mechanism as a way of obtaining up-to-date
167value information. These mechanisms are not scalable.
168
169In a graphical environment, where many values can be displayed
170simultaneously, a serious performance problem occurs when the client
171tries to first extract from @value{GDBN}, and then re-display, all those
172values. The client should instead only request and update the values
173that changed.
174
175The @sc{gdb/mi} Variable Objects provide just that mechanism.
176
177@section Correctness
178
179The annotation interface assumes that a variable's value can only be
180changed when the target is running. This assumption is not correct. A
181single assignment to a single variable can result in the entire target,
182and all displayed values, needing an update.
183
184The @sc{gdb/mi} Variable Objects include a mechanism for efficiently
185reporting such changes.
186
187@section Reliability
188
189The @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
191testsuite changes.
192
193@section Maintainability
194
195The annotation mechanism was implemented by interspersing @sc{cli} print
196statements with various annotations. As a consequence, any @sc{cli}
197output change can alter the annotation output.
198
199Since 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}
201code, its long term maintenance is much easier.
202
203@node Migrating to GDB/MI
204@chapter Migrating to @sc{gdb/mi}
205
206By using the @samp{interp mi} command, it is possible for annotation
207clients to invoke @sc{gdb/mi} commands, and hence access the
208@sc{gdb/mi}. By doing this, existing annotation clients have a
209migration 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
215To issue a command to @value{GDBN} without affecting certain aspects of
216the state which is seen by users, prefix it with @samp{server }. This
217means that this command will not affect the command history, nor will it
218affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
219pressed on a line by itself.
220
221The server prefix does not affect the recording of values into the value
222history; to print a value without recording it into the value history,
223use 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
229Variable Objects.}
230
231@cindex annotations for values
232When a value is printed in various contexts, @value{GDBN} uses
233annotations to delimit the value from the surrounding text.
234
235@findex value-history-begin
236@findex value-history-value
237@findex value-history-end
238If a value is printed using @code{print} and added to the value history,
239the 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
250where @var{history-number} is the number it is getting in the value
251history, @var{history-string} is a string, such as @samp{$5 = }, which
252introduces the value to the user, @var{the-value} is the output
253corresponding to the value itself, and @var{value-flags} is @samp{*} for
254a value which can be dereferenced and @samp{-} for a value which cannot.
255
256@findex value-begin
257@findex value-end
258If the value is not added to the value history (it is an invalid float
259or 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
271When @value{GDBN} prints an argument to a function (for example, in the output
272from 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
285where @var{argument-name} is the name of the argument,
286@var{separator-string} is text which separates the name from the value
287for 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
295When 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
308where @var{field-name} is the name of the field, @var{separator-string}
309is 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
311same meanings as in a @code{value-history-begin} annotation.
312
313When 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
320where @var{array-index} is the index of the first element being
321annotated and @var{value-flags} has the same meaning as in a
322@code{value-history-begin} annotation. This is followed by any number
323of 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
332or 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
344In both cases, @var{the-value} is the output for the value of the
345element and @var{whitespace} can contain spaces, tabs, and newlines. In
346the repeated case, @var{number-of-repetitions} is the number of
347consecutive array elements which contain that value, and
348@var{repetition-string} is a string which is designed to convey to the
349user that repetition is being depicted.
350
351@findex array-section-end
352Once all the array elements have been output, the array annotation is
353ended 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
363a number of frame commands.}
364
365@emph{Frame annotations are no longer available. The @sc{gdb/mi}
366provides @samp{-stack-list-arguments}, @samp{-stack-list-locals}, and
367@samp{-stack-list-frames} commands.}
368
369@cindex annotations for frames
370Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
371to frames printed when @value{GDBN} stops, output from commands such as
372@code{backtrace} or @code{up}, etc.
373
374@findex frame-begin
375The 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
383where @var{level} is the number of the frame (0 is the innermost frame,
384and other frames have positive numbers), @var{address} is the address of
385the code executing in that frame, and @var{level-string} is a string
386designed 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
388does not depend on the language). The frame ends with
389
390@findex frame-end
391@smallexample
392^Z^Zframe-end
393@end smallexample
394
395Between these annotations is the main body of the frame, which can
396consist 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
406where @var{function-call-string} is text designed to convey to the user
407that this frame is associated with a function call made by @value{GDBN} to a
408function 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
417where @var{signal-handler-caller-string} is text designed to convey to
418the user that this frame is associated with whatever mechanism is used
419by this operating system to call a signal handler (it is the frame which
420calls the signal handler, not the frame for the signal handler itself).
421
422@item
423A normal frame.
424
425@findex frame-address
426@findex frame-address-end
427This can optionally (depending on whether this is thought of as
428interesting 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
437where @var{address} is the address executing in the frame (the same
438address as in the @code{frame-begin} annotation, but printed in a form
439which is intended for user consumption---in particular, the syntax varies
440depending on the language), and @var{separator-string} is a string
441intended to separate this address from what follows for the user's
442benefit.
443
444@findex frame-function-name
445@findex frame-args
446Then comes
447
448@smallexample
449^Z^Zframe-function-name
450@var{function-name}
451^Z^Zframe-args
452@var{arguments}
453@end smallexample
454
455where @var{function-name} is the name of the function executing in the
456frame, or @samp{??} if not known, and @var{arguments} are the arguments
457to the frame, with parentheses around them (each argument is annotated
458individually 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
465If 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
479where @var{source-intro-string} separates for the user's benefit the
480reference from the text which precedes it, @var{filename} is the name of
481the source file, and @var{line-number} is the line number within that
482file (the first line is line 1).
483
484@findex frame-where
485If @value{GDBN} prints some information about where the frame is from (which
486library, which load segment, etc.; currently only done on the RS/6000),
487it is annotated with
488
489@smallexample
490^Z^Zframe-where
491@var{information}
492@end smallexample
493
494Then, if source is to actually be displayed for this frame (for example,
495this is not true for output from the @code{backtrace} command), then a
496@code{source} annotation (@pxref{Source Annotations}) is displayed. Unlike
497most annotations, this is output instead of the normal text which would be
498output, 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
505provides 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
515When @value{GDBN} is told to display something using the @code{display} command,
516the 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
535where @var{number} is the number of the display, @var{number-separator}
536is intended to separate the number from what follows for the user,
537@var{format} includes information such as the size, format, or other
538information about how the value is being displayed, @var{expression} is
539the expression being displayed, @var{expression-separator} is intended
540to separate the expression from the text that follows for the user,
541and @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
547When @value{GDBN} prompts for input, it annotates this fact so it is possible
548to know when to send output, when the output from a given command is
549over, etc.
550
551Different kinds of input each have a different @dfn{input type}. Each
552input type has three annotations: a @code{pre-} annotation, which
553denotes the beginning of any prompt which is being output, a plain
554annotation, which denotes the end of the prompt, and then a @code{post-}
555annotation which denotes the end of any echo which may (or may not) be
556associated with the input. For example, the @code{prompt} input type
557features the following annotations:
558
559@smallexample
560^Z^Zpre-prompt
561^Z^Zprompt
562^Z^Zpost-prompt
563@end smallexample
564
565The input types are
566
567@table @code
568@findex pre-prompt
569@findex prompt
570@findex post-prompt
571@item prompt
572When @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
578When @value{GDBN} prompts for a set of commands, like in the @code{commands}
579command. 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
585When @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
591When @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
597When @value{GDBN} is asking the user to press return to continue. Note: Don't
598expect this to work well; instead use @code{set height 0} to disable
599prompting. This is because the counting of lines is buggy in the
600presence 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
612This annotation occurs right before @value{GDBN} responds to an interrupt.
613
614@findex error
615@smallexample
616^Z^Zerror
617@end smallexample
618
619This annotation occurs right before @value{GDBN} responds to an error.
620
621Quit and error annotations indicate that any annotations which @value{GDBN} was
622in the middle of may end abruptly. For example, if a
623@code{value-history-begin} annotation is followed by a @code{error}, one
624cannot expect to receive the matching @code{value-history-end}. One
625cannot expect not to receive it either, however; an error annotation
626does not necessarily mean that @value{GDBN} is immediately returning all the way
627to the top level.
628
629@findex error-begin
630A quit or error annotation may be preceded by
631
632@smallexample
633^Z^Zerror-begin
634@end smallexample
635
636Any output between that and the quit or error annotation is the error
637message.
638
639Warning 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
647provides breakpoint commands.}
648
649@cindex annotations for breakpoints
650The 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
661where @var{header-entry} has the same syntax as an entry (see below) but
662instead of containing data, it contains strings which are intended to
663convey the meaning of each field to the user. This is followed by any
664number of entries. If a field does not apply for this entry, it is
665omitted. Fields may contain trailing whitespace. Each entry consists
666of:
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
694Note that @var{address} is intended for user consumption---the syntax
695varies depending on the language.
696
697The 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
708The following annotations say that certain pieces of state may have
709changed.
710
711@table @code
712@findex frames-invalid
713@item ^Z^Zframes-invalid
714
715The frames (for example, output from the @code{backtrace} command) may
716have changed.
717
718@findex breakpoints-invalid
719@item ^Z^Zbreakpoints-invalid
720
721The breakpoints may have changed. For example, the user just added or
722deleted 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
731When 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
738is output. When the program stops,
739
740@smallexample
741^Z^Zstopped
742@end smallexample
743
744is output. Before the @code{stopped} annotation, a variety of
745annotations describe how the program stopped.
746
747@table @code
748@findex exited
749@item ^Z^Zexited @var{exit-status}
750The program exited, and @var{exit-status} is the exit status (zero for
751successful 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
759The program exited with a signal. After the @code{^Z^Zsignalled}, the
760annotation 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
775where @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
777as @code{Illegal Instruction} or @code{Segmentation fault}.
778@var{intro-text}, @var{middle-text}, and @var{end-text} are for the
779user's benefit and have no particular format.
780
781@findex signal
782@item ^Z^Zsignal
783The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
784just saying that the program received the signal, not that it was
785terminated with it.
786
787@findex breakpoint
788@item ^Z^Zbreakpoint @var{number}
789The program hit breakpoint number @var{number}.
790
791@findex watchpoint
792@item ^Z^Zwatchpoint @var{number}
793The 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
801The 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
807where @var{filename} is an absolute file name indicating which source
808file, @var{line} is the line number within that file (where 1 is the
809first line in the file), @var{character} is the character position
810within the file (where 0 is the first character in the file) (for most
811debug 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
813line, 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
815source which is being displayed. @var{addr} is in the form @samp{0x}
816followed by one or more lowercase hex digits (note that this does not
817depend on the language).
818
819@node Multi-threaded Apps
820@chapter Multi-threaded Applications
821@cindex annotations for multi-threaded apps
822
823The following annotations report thread related changes of state.
824
825@table @code
826@findex new-thread@r{, annotation}
827@item ^Z^Znew-thread
828
829This annotation is issued once for each thread that is created apart from
830the main thread, which is not reported.
831
832@findex thread-changed@r{, annotation}
833@item ^Z^Zthread-changed
834
835The selected thread has changed. This may occur at the request of the
836user with the @code{thread} command, or as a result of execution,
837e.g., another thread hits a breakpoint.
838
839@end table
840
cf7f2e2d
JM
841@node GNU Free Documentation License
842@appendix GNU Free Documentation License
5796c8dc 843@include fdl.texi
5796c8dc
SS
844
845@ignore
846@node Index
847@unnumbered Index
848
849@printindex fn
850@end ignore
851
852@bye