annotate.texinfo revision 1.9
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--2020 Free Software Foundation, Inc. 31 32Permission is granted to copy, distribute and/or modify this document 33under the terms of the GNU Free Documentation License, Version 1.3 or 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@findex thread-exited@r{, annotation} 840@item ^Z^Zthread-exited,id="@var{id}",group-id="@var{gid}" 841 842This annotation is issued once for each thread that exits. The @var{id} 843field contains the global @value{GDBN} identifier of the thread. The 844@var{gid} field identifies the thread group this thread belongs to. 845 846@end table 847 848@node GNU Free Documentation License 849@appendix GNU Free Documentation License 850@include fdl.texi 851 852@ignore 853@node Index 854@unnumbered Index 855 856@printindex fn 857@end ignore 858 859@bye 860