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