1This is annotate.info, produced by makeinfo version 4.8 from 2../.././gdb/doc/annotate.texinfo. 3 4INFO-DIR-SECTION Software development 5START-INFO-DIR-ENTRY 6* Annotate: (annotate). The obsolete annotation interface. 7END-INFO-DIR-ENTRY 8 9 This file documents GDB's obsolete annotations. 10 11 Copyright (C) 1994, 1995, 2000, 2001, 2003 Free Software Foundation, 12Inc. 13 14 Permission is granted to copy, distribute and/or modify this document 15under the terms of the GNU Free Documentation License, Version 1.1 or 16any later version published by the Free Software Foundation; with no 17Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 18Texts. A copy of the license is included in the section entitled "GNU 19Free Documentation License". 20 21 22File: annotate.info, Node: Top, Next: Annotations Overview, Up: (dir) 23 24GDB Annotations 25*************** 26 27This document describes the obsolete level two annotation interface 28implemented in older GDB versions. 29 30* Menu: 31 32* Annotations Overview:: What annotations are; the general syntax. 33* Limitations:: Limitations of the annotation interface. 34* Migrating to GDB/MI:: Migrating to GDB/MI 35* Server Prefix:: Issuing a command without affecting user state. 36* Value Annotations:: Values are marked as such. 37* Frame Annotations:: Stack frames are annotated. 38* Displays:: GDB can be told to display something periodically. 39* Prompting:: Annotations marking GDB's need for input. 40* Errors:: Annotations for error messages. 41* Breakpoint Info:: Information on breakpoints. 42* Invalidation:: Some annotations describe things now invalid. 43* Annotations for Running:: 44 Whether the program is running, how it stopped, etc. 45* Source Annotations:: Annotations describing source code. 46 47* GNU Free Documentation License:: 48 49 50File: annotate.info, Node: Annotations Overview, Next: Limitations, Prev: Top, Up: Top 51 521 What is an Annotation? 53************************ 54 55To produce obsolete level two annotations, start GDB with the 56`--annotate=2' option. 57 58 Annotations start with a newline character, two `control-z' 59characters, and the name of the annotation. If there is no additional 60information associated with this annotation, the name of the annotation 61is followed immediately by a newline. If there is additional 62information, the name of the annotation is followed by a space, the 63additional information, and a newline. The additional information 64cannot contain newline characters. 65 66 Any output not beginning with a newline and two `control-z' 67characters denotes literal output from GDB. Currently there is no need 68for GDB to output a newline followed by two `control-z' characters, but 69if there was such a need, the annotations could be extended with an 70`escape' annotation which means those three characters as output. 71 72 A simple example of starting up GDB with annotations is: 73 74 $ gdb --annotate=2 75 GNU GDB 5.0 76 Copyright 2000 Free Software Foundation, Inc. 77 GDB is free software, covered by the GNU General Public License, 78 and you are welcome to change it and/or distribute copies of it 79 under certain conditions. 80 Type "show copying" to see the conditions. 81 There is absolutely no warranty for GDB. Type "show warranty" 82 for details. 83 This GDB was configured as "sparc-sun-sunos4.1.3" 84 85 ^Z^Zpre-prompt 86 (gdb) 87 ^Z^Zprompt 88 quit 89 90 ^Z^Zpost-prompt 91 $ 92 93 Here `quit' is input to GDB; the rest is output from GDB. The three 94lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are 95annotations; the rest is output from GDB. 96 97 98File: annotate.info, Node: Limitations, Next: Migrating to GDB/MI, Prev: Annotations Overview, Up: Top 99 1002 Limitations of the Annotation Interface 101***************************************** 102 103The level two annotations mechanism is known to have a number of 104technical and architectural limitations. As a consequence, in 2001, 105with the release of GDB 5.1 and the addition of GDB/MI, the annotation 106interface was marked as deprecated. 107 108 This chapter discusses the known problems. 109 1102.1 Dependant on CLI output 111=========================== 112 113The annotation interface works by interspersing markups with GDB normal 114command-line interpreter output. Unfortunately, this makes the 115annotation client dependant on not just the annotations, but also the 116CLI output. This is because the client is forced to assume that 117specific GDB commands provide specific information. Any change to 118GDB's CLI output modifies or removes that information and, 119consequently, likely breaks the client. 120 121 Since the GDB/MI output is independent of the CLI, it does not have 122this problem. 123 1242.2 Scalability 125=============== 126 127The annotation interface relies on value annotations (*note Value 128Annotations::) and the display mechanism as a way of obtaining 129up-to-date value information. These mechanisms are not scalable. 130 131 In a graphical environment, where many values can be displayed 132simultaneously, a serious performance problem occurs when the client 133tries to first extract from GDB, and then re-display, all those values. 134The client should instead only request and update the values that 135changed. 136 137 The GDB/MI Variable Objects provide just that mechanism. 138 1392.3 Correctness 140=============== 141 142The annotation interface assumes that a variable's value can only be 143changed when the target is running. This assumption is not correct. A 144single assignment to a single variable can result in the entire target, 145and all displayed values, needing an update. 146 147 The GDB/MI Variable Objects include a mechanism for efficiently 148reporting such changes. 149 1502.4 Reliability 151=============== 152 153The GDB/MI interface includes a dedicated test directory 154(`gdb/gdb.mi'), and any addition or fix to GDB/MI must include 155testsuite changes. 156 1572.5 Maintainability 158=================== 159 160The annotation mechanism was implemented by interspersing CLI print 161statements with various annotations. As a consequence, any CLI output 162change can alter the annotation output. 163 164 Since the GDB/MI output is independent of the CLI, and the GDB/MI is 165increasingly implemented independent of the CLI code, its long term 166maintenance is much easier. 167 168 169File: annotate.info, Node: Migrating to GDB/MI, Next: Server Prefix, Prev: Limitations, Up: Top 170 1713 Migrating to GDB/MI 172********************* 173 174By using the `interp mi' command, it is possible for annotation clients 175to invoke GDB/MI commands, and hence access the GDB/MI. By doing this, 176existing annotation clients have a migration path from this obsolete 177interface to GDB/MI. 178 179 180File: annotate.info, Node: Server Prefix, Next: Value Annotations, Prev: Migrating to GDB/MI, Up: Top 181 1824 The Server Prefix 183******************* 184 185To issue a command to GDB without affecting certain aspects of the 186state which is seen by users, prefix it with `server '. This means 187that this command will not affect the command history, nor will it 188affect GDB's notion of which command to repeat if <RET> is pressed on a 189line by itself. 190 191 The server prefix does not affect the recording of values into the 192value history; to print a value without recording it into the value 193history, use the `output' command instead of the `print' command. 194 195 196File: annotate.info, Node: Value Annotations, Next: Frame Annotations, Prev: Server Prefix, Up: Top 197 1985 Values 199******** 200 201_Value Annotations have been removed. GDB/MI instead provides Variable 202Objects._ 203 204 When a value is printed in various contexts, GDB uses annotations to 205delimit the value from the surrounding text. 206 207 If a value is printed using `print' and added to the value history, 208the annotation looks like 209 210 ^Z^Zvalue-history-begin HISTORY-NUMBER VALUE-FLAGS 211 HISTORY-STRING 212 ^Z^Zvalue-history-value 213 THE-VALUE 214 ^Z^Zvalue-history-end 215 216where HISTORY-NUMBER is the number it is getting in the value history, 217HISTORY-STRING is a string, such as `$5 = ', which introduces the value 218to the user, THE-VALUE is the output corresponding to the value itself, 219and VALUE-FLAGS is `*' for a value which can be dereferenced and `-' 220for a value which cannot. 221 222 If the value is not added to the value history (it is an invalid 223float or it is printed with the `output' command), the annotation is 224similar: 225 226 ^Z^Zvalue-begin VALUE-FLAGS 227 THE-VALUE 228 ^Z^Zvalue-end 229 230 When GDB prints an argument to a function (for example, in the output 231from the `backtrace' command), it annotates it as follows: 232 233 ^Z^Zarg-begin 234 ARGUMENT-NAME 235 ^Z^Zarg-name-end 236 SEPARATOR-STRING 237 ^Z^Zarg-value VALUE-FLAGS 238 THE-VALUE 239 ^Z^Zarg-end 240 241where ARGUMENT-NAME is the name of the argument, SEPARATOR-STRING is 242text which separates the name from the value for the user's benefit 243(such as `='), and VALUE-FLAGS and THE-VALUE have the same meanings as 244in a `value-history-begin' annotation. 245 246 When printing a structure, GDB annotates it as follows: 247 248 ^Z^Zfield-begin VALUE-FLAGS 249 FIELD-NAME 250 ^Z^Zfield-name-end 251 SEPARATOR-STRING 252 ^Z^Zfield-value 253 THE-VALUE 254 ^Z^Zfield-end 255 256where FIELD-NAME is the name of the field, SEPARATOR-STRING is text 257which separates the name from the value for the user's benefit (such as 258`='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a 259`value-history-begin' annotation. 260 261 When printing an array, GDB annotates it as follows: 262 263 ^Z^Zarray-section-begin ARRAY-INDEX VALUE-FLAGS 264 265where ARRAY-INDEX is the index of the first element being annotated and 266VALUE-FLAGS has the same meaning as in a `value-history-begin' 267annotation. This is followed by any number of elements, where is 268element can be either a single element: 269 270 `,' WHITESPACE ; omitted for the first element 271 THE-VALUE 272 ^Z^Zelt 273 274 or a repeated element 275 276 `,' WHITESPACE ; omitted for the first element 277 THE-VALUE 278 ^Z^Zelt-rep NUMBER-OF-REPETITIONS 279 REPETITION-STRING 280 ^Z^Zelt-rep-end 281 282 In both cases, THE-VALUE is the output for the value of the element 283and WHITESPACE can contain spaces, tabs, and newlines. In the repeated 284case, NUMBER-OF-REPETITIONS is the number of consecutive array elements 285which contain that value, and REPETITION-STRING is a string which is 286designed to convey to the user that repetition is being depicted. 287 288 Once all the array elements have been output, the array annotation is 289ended with 290 291 ^Z^Zarray-section-end 292 293 294File: annotate.info, Node: Frame Annotations, Next: Displays, Prev: Value Annotations, Up: Top 295 2966 Frames 297******** 298 299_Value Annotations have been removed. GDB/MI instead provides a number 300of frame commands._ 301 302 _Frame annotations are no longer available. The GDB/MI provides 303`-stack-list-arguments', `-stack-list-locals', and `-stack-list-frames' 304commands._ 305 306 Whenever GDB prints a frame, it annotates it. For example, this 307applies to frames printed when GDB stops, output from commands such as 308`backtrace' or `up', etc. 309 310 The frame annotation begins with 311 312 ^Z^Zframe-begin LEVEL ADDRESS 313 LEVEL-STRING 314 315where LEVEL is the number of the frame (0 is the innermost frame, and 316other frames have positive numbers), ADDRESS is the address of the code 317executing in that frame, and LEVEL-STRING is a string designed to 318convey the level to the user. ADDRESS is in the form `0x' followed by 319one or more lowercase hex digits (note that this does not depend on the 320language). The frame ends with 321 322 ^Z^Zframe-end 323 324 Between these annotations is the main body of the frame, which can 325consist of 326 327 * ^Z^Zfunction-call 328 FUNCTION-CALL-STRING 329 330 where FUNCTION-CALL-STRING is text designed to convey to the user 331 that this frame is associated with a function call made by GDB to a 332 function in the program being debugged. 333 334 * ^Z^Zsignal-handler-caller 335 SIGNAL-HANDLER-CALLER-STRING 336 337 where SIGNAL-HANDLER-CALLER-STRING is text designed to convey to 338 the user that this frame is associated with whatever mechanism is 339 used by this operating system to call a signal handler (it is the 340 frame which calls the signal handler, not the frame for the signal 341 handler itself). 342 343 * A normal frame. 344 345 This can optionally (depending on whether this is thought of as 346 interesting information for the user to see) begin with 347 348 ^Z^Zframe-address 349 ADDRESS 350 ^Z^Zframe-address-end 351 SEPARATOR-STRING 352 353 where ADDRESS is the address executing in the frame (the same 354 address as in the `frame-begin' annotation, but printed in a form 355 which is intended for user consumption--in particular, the syntax 356 varies depending on the language), and SEPARATOR-STRING is a string 357 intended to separate this address from what follows for the user's 358 benefit. 359 360 Then comes 361 362 ^Z^Zframe-function-name 363 FUNCTION-NAME 364 ^Z^Zframe-args 365 ARGUMENTS 366 367 where FUNCTION-NAME is the name of the function executing in the 368 frame, or `??' if not known, and ARGUMENTS are the arguments to 369 the frame, with parentheses around them (each argument is annotated 370 individually as well, *note Value Annotations::). 371 372 If source information is available, a reference to it is then 373 printed: 374 375 ^Z^Zframe-source-begin 376 SOURCE-INTRO-STRING 377 ^Z^Zframe-source-file 378 FILENAME 379 ^Z^Zframe-source-file-end 380 : 381 ^Z^Zframe-source-line 382 LINE-NUMBER 383 ^Z^Zframe-source-end 384 385 where SOURCE-INTRO-STRING separates for the user's benefit the 386 reference from the text which precedes it, FILENAME is the name of 387 the source file, and LINE-NUMBER is the line number within that 388 file (the first line is line 1). 389 390 If GDB prints some information about where the frame is from (which 391 library, which load segment, etc.; currently only done on the 392 RS/6000), it is annotated with 393 394 ^Z^Zframe-where 395 INFORMATION 396 397 Then, if source is to actually be displayed for this frame (for 398 example, this is not true for output from the `backtrace' 399 command), then a `source' annotation (*note Source Annotations::) 400 is displayed. Unlike most annotations, this is output instead of 401 the normal text which would be output, not in addition. 402 403 404File: annotate.info, Node: Displays, Next: Prompting, Prev: Frame Annotations, Up: Top 405 4067 Displays 407********** 408 409_Display Annotations have been removed. GDB/MI instead provides 410Variable Objects._ 411 412 When GDB is told to display something using the `display' command, 413the results of the display are annotated: 414 415 ^Z^Zdisplay-begin 416 NUMBER 417 ^Z^Zdisplay-number-end 418 NUMBER-SEPARATOR 419 ^Z^Zdisplay-format 420 FORMAT 421 ^Z^Zdisplay-expression 422 EXPRESSION 423 ^Z^Zdisplay-expression-end 424 EXPRESSION-SEPARATOR 425 ^Z^Zdisplay-value 426 VALUE 427 ^Z^Zdisplay-end 428 429where NUMBER is the number of the display, NUMBER-SEPARATOR is intended 430to separate the number from what follows for the user, FORMAT includes 431information such as the size, format, or other information about how 432the value is being displayed, EXPRESSION is the expression being 433displayed, EXPRESSION-SEPARATOR is intended to separate the expression 434from the text that follows for the user, and VALUE is the actual value 435being displayed. 436 437 438File: annotate.info, Node: Prompting, Next: Errors, Prev: Displays, Up: Top 439 4408 Annotation for GDB Input 441************************** 442 443When GDB prompts for input, it annotates this fact so it is possible to 444know when to send output, when the output from a given command is over, 445etc. 446 447 Different kinds of input each have a different "input type". Each 448input type has three annotations: a `pre-' annotation, which denotes 449the beginning of any prompt which is being output, a plain annotation, 450which denotes the end of the prompt, and then a `post-' annotation 451which denotes the end of any echo which may (or may not) be associated 452with the input. For example, the `prompt' input type features the 453following annotations: 454 455 ^Z^Zpre-prompt 456 ^Z^Zprompt 457 ^Z^Zpost-prompt 458 459 The input types are 460 461`prompt' 462 When GDB is prompting for a command (the main GDB prompt). 463 464`commands' 465 When GDB prompts for a set of commands, like in the `commands' 466 command. The annotations are repeated for each command which is 467 input. 468 469`overload-choice' 470 When GDB wants the user to select between various overloaded 471 functions. 472 473`query' 474 When GDB wants the user to confirm a potentially dangerous 475 operation. 476 477`prompt-for-continue' 478 When GDB is asking the user to press return to continue. Note: 479 Don't expect this to work well; instead use `set height 0' to 480 disable prompting. This is because the counting of lines is buggy 481 in the presence of annotations. 482 483 484File: annotate.info, Node: Errors, Next: Breakpoint Info, Prev: Prompting, Up: Top 485 4869 Errors 487******** 488 489 ^Z^Zquit 490 491 This annotation occurs right before GDB responds to an interrupt. 492 493 ^Z^Zerror 494 495 This annotation occurs right before GDB responds to an error. 496 497 Quit and error annotations indicate that any annotations which GDB 498was in the middle of may end abruptly. For example, if a 499`value-history-begin' annotation is followed by a `error', one cannot 500expect to receive the matching `value-history-end'. One cannot expect 501not to receive it either, however; an error annotation does not 502necessarily mean that GDB is immediately returning all the way to the 503top level. 504 505 A quit or error annotation may be preceded by 506 507 ^Z^Zerror-begin 508 509 Any output between that and the quit or error annotation is the error 510message. 511 512 Warning messages are not yet annotated. 513 514 515File: annotate.info, Node: Breakpoint Info, Next: Invalidation, Prev: Errors, Up: Top 516 51710 Information on Breakpoints 518***************************** 519 520_Breakpoint Annotations have been removed. GDB/MI instead provides 521breakpoint commands._ 522 523 The output from the `info breakpoints' command is annotated as 524follows: 525 526 ^Z^Zbreakpoints-headers 527 HEADER-ENTRY 528 ^Z^Zbreakpoints-table 529 530where HEADER-ENTRY has the same syntax as an entry (see below) but 531instead of containing data, it contains strings which are intended to 532convey the meaning of each field to the user. This is followed by any 533number of entries. If a field does not apply for this entry, it is 534omitted. Fields may contain trailing whitespace. Each entry consists 535of: 536 537 ^Z^Zrecord 538 ^Z^Zfield 0 539 NUMBER 540 ^Z^Zfield 1 541 TYPE 542 ^Z^Zfield 2 543 DISPOSITION 544 ^Z^Zfield 3 545 ENABLE 546 ^Z^Zfield 4 547 ADDRESS 548 ^Z^Zfield 5 549 WHAT 550 ^Z^Zfield 6 551 FRAME 552 ^Z^Zfield 7 553 CONDITION 554 ^Z^Zfield 8 555 IGNORE-COUNT 556 ^Z^Zfield 9 557 COMMANDS 558 559 Note that ADDRESS is intended for user consumption--the syntax 560varies depending on the language. 561 562 The output ends with 563 564 ^Z^Zbreakpoints-table-end 565 566 567File: annotate.info, Node: Invalidation, Next: Annotations for Running, Prev: Breakpoint Info, Up: Top 568 56911 Invalidation Notices 570*********************** 571 572The following annotations say that certain pieces of state may have 573changed. 574 575`^Z^Zframes-invalid' 576 The frames (for example, output from the `backtrace' command) may 577 have changed. 578 579`^Z^Zbreakpoints-invalid' 580 The breakpoints may have changed. For example, the user just 581 added or deleted a breakpoint. 582 583 584File: annotate.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Top 585 58612 Running the Program 587********************** 588 589When the program starts executing due to a GDB command such as `step' 590or `continue', 591 592 ^Z^Zstarting 593 594 is output. When the program stops, 595 596 ^Z^Zstopped 597 598 is output. Before the `stopped' annotation, a variety of 599annotations describe how the program stopped. 600 601`^Z^Zexited EXIT-STATUS' 602 The program exited, and EXIT-STATUS is the exit status (zero for 603 successful exit, otherwise nonzero). 604 605`^Z^Zsignalled' 606 The program exited with a signal. After the `^Z^Zsignalled', the 607 annotation continues: 608 609 INTRO-TEXT 610 ^Z^Zsignal-name 611 NAME 612 ^Z^Zsignal-name-end 613 MIDDLE-TEXT 614 ^Z^Zsignal-string 615 STRING 616 ^Z^Zsignal-string-end 617 END-TEXT 618 619 where NAME is the name of the signal, such as `SIGILL' or 620 `SIGSEGV', and STRING is the explanation of the signal, such as 621 `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT, 622 MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no 623 particular format. 624 625`^Z^Zsignal' 626 The syntax of this annotation is just like `signalled', but GDB is 627 just saying that the program received the signal, not that it was 628 terminated with it. 629 630`^Z^Zbreakpoint NUMBER' 631 The program hit breakpoint number NUMBER. 632 633`^Z^Zwatchpoint NUMBER' 634 The program hit watchpoint number NUMBER. 635 636 637File: annotate.info, Node: Source Annotations, Next: GNU Free Documentation License, Prev: Annotations for Running, Up: Top 638 63913 Displaying Source 640******************** 641 642The following annotation is used instead of displaying source code: 643 644 ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR 645 646 where FILENAME is an absolute file name indicating which source 647file, LINE is the line number within that file (where 1 is the first 648line in the file), CHARACTER is the character position within the file 649(where 0 is the first character in the file) (for most debug formats 650this will necessarily point to the beginning of a line), MIDDLE is 651`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at 652the beginning of the line, and ADDR is the address in the target 653program associated with the source which is being displayed. ADDR is 654in the form `0x' followed by one or more lowercase hex digits (note 655that this does not depend on the language). 656 657 658File: annotate.info, Node: GNU Free Documentation License, Prev: Source Annotations, Up: Top 659 66014 GNU Free Documentation License 661********************************* 662 663 Version 1.2, November 2002 664 665 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 666 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 667 668 Everyone is permitted to copy and distribute verbatim copies 669 of this license document, but changing it is not allowed. 670 671 0. PREAMBLE 672 673 The purpose of this License is to make a manual, textbook, or other 674 functional and useful document "free" in the sense of freedom: to 675 assure everyone the effective freedom to copy and redistribute it, 676 with or without modifying it, either commercially or 677 noncommercially. Secondarily, this License preserves for the 678 author and publisher a way to get credit for their work, while not 679 being considered responsible for modifications made by others. 680 681 This License is a kind of "copyleft", which means that derivative 682 works of the document must themselves be free in the same sense. 683 It complements the GNU General Public License, which is a copyleft 684 license designed for free software. 685 686 We have designed this License in order to use it for manuals for 687 free software, because free software needs free documentation: a 688 free program should come with manuals providing the same freedoms 689 that the software does. But this License is not limited to 690 software manuals; it can be used for any textual work, regardless 691 of subject matter or whether it is published as a printed book. 692 We recommend this License principally for works whose purpose is 693 instruction or reference. 694 695 1. APPLICABILITY AND DEFINITIONS 696 697 This License applies to any manual or other work, in any medium, 698 that contains a notice placed by the copyright holder saying it 699 can be distributed under the terms of this License. Such a notice 700 grants a world-wide, royalty-free license, unlimited in duration, 701 to use that work under the conditions stated herein. The 702 "Document", below, refers to any such manual or work. Any member 703 of the public is a licensee, and is addressed as "you". You 704 accept the license if you copy, modify or distribute the work in a 705 way requiring permission under copyright law. 706 707 A "Modified Version" of the Document means any work containing the 708 Document or a portion of it, either copied verbatim, or with 709 modifications and/or translated into another language. 710 711 A "Secondary Section" is a named appendix or a front-matter section 712 of the Document that deals exclusively with the relationship of the 713 publishers or authors of the Document to the Document's overall 714 subject (or to related matters) and contains nothing that could 715 fall directly within that overall subject. (Thus, if the Document 716 is in part a textbook of mathematics, a Secondary Section may not 717 explain any mathematics.) The relationship could be a matter of 718 historical connection with the subject or with related matters, or 719 of legal, commercial, philosophical, ethical or political position 720 regarding them. 721 722 The "Invariant Sections" are certain Secondary Sections whose 723 titles are designated, as being those of Invariant Sections, in 724 the notice that says that the Document is released under this 725 License. If a section does not fit the above definition of 726 Secondary then it is not allowed to be designated as Invariant. 727 The Document may contain zero Invariant Sections. If the Document 728 does not identify any Invariant Sections then there are none. 729 730 The "Cover Texts" are certain short passages of text that are 731 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 732 that says that the Document is released under this License. A 733 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 734 be at most 25 words. 735 736 A "Transparent" copy of the Document means a machine-readable copy, 737 represented in a format whose specification is available to the 738 general public, that is suitable for revising the document 739 straightforwardly with generic text editors or (for images 740 composed of pixels) generic paint programs or (for drawings) some 741 widely available drawing editor, and that is suitable for input to 742 text formatters or for automatic translation to a variety of 743 formats suitable for input to text formatters. A copy made in an 744 otherwise Transparent file format whose markup, or absence of 745 markup, has been arranged to thwart or discourage subsequent 746 modification by readers is not Transparent. An image format is 747 not Transparent if used for any substantial amount of text. A 748 copy that is not "Transparent" is called "Opaque". 749 750 Examples of suitable formats for Transparent copies include plain 751 ASCII without markup, Texinfo input format, LaTeX input format, 752 SGML or XML using a publicly available DTD, and 753 standard-conforming simple HTML, PostScript or PDF designed for 754 human modification. Examples of transparent image formats include 755 PNG, XCF and JPG. Opaque formats include proprietary formats that 756 can be read and edited only by proprietary word processors, SGML or 757 XML for which the DTD and/or processing tools are not generally 758 available, and the machine-generated HTML, PostScript or PDF 759 produced by some word processors for output purposes only. 760 761 The "Title Page" means, for a printed book, the title page itself, 762 plus such following pages as are needed to hold, legibly, the 763 material this License requires to appear in the title page. For 764 works in formats which do not have any title page as such, "Title 765 Page" means the text near the most prominent appearance of the 766 work's title, preceding the beginning of the body of the text. 767 768 A section "Entitled XYZ" means a named subunit of the Document 769 whose title either is precisely XYZ or contains XYZ in parentheses 770 following text that translates XYZ in another language. (Here XYZ 771 stands for a specific section name mentioned below, such as 772 "Acknowledgements", "Dedications", "Endorsements", or "History".) 773 To "Preserve the Title" of such a section when you modify the 774 Document means that it remains a section "Entitled XYZ" according 775 to this definition. 776 777 The Document may include Warranty Disclaimers next to the notice 778 which states that this License applies to the Document. These 779 Warranty Disclaimers are considered to be included by reference in 780 this License, but only as regards disclaiming warranties: any other 781 implication that these Warranty Disclaimers may have is void and 782 has no effect on the meaning of this License. 783 784 2. VERBATIM COPYING 785 786 You may copy and distribute the Document in any medium, either 787 commercially or noncommercially, provided that this License, the 788 copyright notices, and the license notice saying this License 789 applies to the Document are reproduced in all copies, and that you 790 add no other conditions whatsoever to those of this License. You 791 may not use technical measures to obstruct or control the reading 792 or further copying of the copies you make or distribute. However, 793 you may accept compensation in exchange for copies. If you 794 distribute a large enough number of copies you must also follow 795 the conditions in section 3. 796 797 You may also lend copies, under the same conditions stated above, 798 and you may publicly display copies. 799 800 3. COPYING IN QUANTITY 801 802 If you publish printed copies (or copies in media that commonly 803 have printed covers) of the Document, numbering more than 100, and 804 the Document's license notice requires Cover Texts, you must 805 enclose the copies in covers that carry, clearly and legibly, all 806 these Cover Texts: Front-Cover Texts on the front cover, and 807 Back-Cover Texts on the back cover. Both covers must also clearly 808 and legibly identify you as the publisher of these copies. The 809 front cover must present the full title with all words of the 810 title equally prominent and visible. You may add other material 811 on the covers in addition. Copying with changes limited to the 812 covers, as long as they preserve the title of the Document and 813 satisfy these conditions, can be treated as verbatim copying in 814 other respects. 815 816 If the required texts for either cover are too voluminous to fit 817 legibly, you should put the first ones listed (as many as fit 818 reasonably) on the actual cover, and continue the rest onto 819 adjacent pages. 820 821 If you publish or distribute Opaque copies of the Document 822 numbering more than 100, you must either include a 823 machine-readable Transparent copy along with each Opaque copy, or 824 state in or with each Opaque copy a computer-network location from 825 which the general network-using public has access to download 826 using public-standard network protocols a complete Transparent 827 copy of the Document, free of added material. If you use the 828 latter option, you must take reasonably prudent steps, when you 829 begin distribution of Opaque copies in quantity, to ensure that 830 this Transparent copy will remain thus accessible at the stated 831 location until at least one year after the last time you 832 distribute an Opaque copy (directly or through your agents or 833 retailers) of that edition to the public. 834 835 It is requested, but not required, that you contact the authors of 836 the Document well before redistributing any large number of 837 copies, to give them a chance to provide you with an updated 838 version of the Document. 839 840 4. MODIFICATIONS 841 842 You may copy and distribute a Modified Version of the Document 843 under the conditions of sections 2 and 3 above, provided that you 844 release the Modified Version under precisely this License, with 845 the Modified Version filling the role of the Document, thus 846 licensing distribution and modification of the Modified Version to 847 whoever possesses a copy of it. In addition, you must do these 848 things in the Modified Version: 849 850 A. Use in the Title Page (and on the covers, if any) a title 851 distinct from that of the Document, and from those of 852 previous versions (which should, if there were any, be listed 853 in the History section of the Document). You may use the 854 same title as a previous version if the original publisher of 855 that version gives permission. 856 857 B. List on the Title Page, as authors, one or more persons or 858 entities responsible for authorship of the modifications in 859 the Modified Version, together with at least five of the 860 principal authors of the Document (all of its principal 861 authors, if it has fewer than five), unless they release you 862 from this requirement. 863 864 C. State on the Title page the name of the publisher of the 865 Modified Version, as the publisher. 866 867 D. Preserve all the copyright notices of the Document. 868 869 E. Add an appropriate copyright notice for your modifications 870 adjacent to the other copyright notices. 871 872 F. Include, immediately after the copyright notices, a license 873 notice giving the public permission to use the Modified 874 Version under the terms of this License, in the form shown in 875 the Addendum below. 876 877 G. Preserve in that license notice the full lists of Invariant 878 Sections and required Cover Texts given in the Document's 879 license notice. 880 881 H. Include an unaltered copy of this License. 882 883 I. Preserve the section Entitled "History", Preserve its Title, 884 and add to it an item stating at least the title, year, new 885 authors, and publisher of the Modified Version as given on 886 the Title Page. If there is no section Entitled "History" in 887 the Document, create one stating the title, year, authors, 888 and publisher of the Document as given on its Title Page, 889 then add an item describing the Modified Version as stated in 890 the previous sentence. 891 892 J. Preserve the network location, if any, given in the Document 893 for public access to a Transparent copy of the Document, and 894 likewise the network locations given in the Document for 895 previous versions it was based on. These may be placed in 896 the "History" section. You may omit a network location for a 897 work that was published at least four years before the 898 Document itself, or if the original publisher of the version 899 it refers to gives permission. 900 901 K. For any section Entitled "Acknowledgements" or "Dedications", 902 Preserve the Title of the section, and preserve in the 903 section all the substance and tone of each of the contributor 904 acknowledgements and/or dedications given therein. 905 906 L. Preserve all the Invariant Sections of the Document, 907 unaltered in their text and in their titles. Section numbers 908 or the equivalent are not considered part of the section 909 titles. 910 911 M. Delete any section Entitled "Endorsements". Such a section 912 may not be included in the Modified Version. 913 914 N. Do not retitle any existing section to be Entitled 915 "Endorsements" or to conflict in title with any Invariant 916 Section. 917 918 O. Preserve any Warranty Disclaimers. 919 920 If the Modified Version includes new front-matter sections or 921 appendices that qualify as Secondary Sections and contain no 922 material copied from the Document, you may at your option 923 designate some or all of these sections as invariant. To do this, 924 add their titles to the list of Invariant Sections in the Modified 925 Version's license notice. These titles must be distinct from any 926 other section titles. 927 928 You may add a section Entitled "Endorsements", provided it contains 929 nothing but endorsements of your Modified Version by various 930 parties--for example, statements of peer review or that the text 931 has been approved by an organization as the authoritative 932 definition of a standard. 933 934 You may add a passage of up to five words as a Front-Cover Text, 935 and a passage of up to 25 words as a Back-Cover Text, to the end 936 of the list of Cover Texts in the Modified Version. Only one 937 passage of Front-Cover Text and one of Back-Cover Text may be 938 added by (or through arrangements made by) any one entity. If the 939 Document already includes a cover text for the same cover, 940 previously added by you or by arrangement made by the same entity 941 you are acting on behalf of, you may not add another; but you may 942 replace the old one, on explicit permission from the previous 943 publisher that added the old one. 944 945 The author(s) and publisher(s) of the Document do not by this 946 License give permission to use their names for publicity for or to 947 assert or imply endorsement of any Modified Version. 948 949 5. COMBINING DOCUMENTS 950 951 You may combine the Document with other documents released under 952 this License, under the terms defined in section 4 above for 953 modified versions, provided that you include in the combination 954 all of the Invariant Sections of all of the original documents, 955 unmodified, and list them all as Invariant Sections of your 956 combined work in its license notice, and that you preserve all 957 their Warranty Disclaimers. 958 959 The combined work need only contain one copy of this License, and 960 multiple identical Invariant Sections may be replaced with a single 961 copy. If there are multiple Invariant Sections with the same name 962 but different contents, make the title of each such section unique 963 by adding at the end of it, in parentheses, the name of the 964 original author or publisher of that section if known, or else a 965 unique number. Make the same adjustment to the section titles in 966 the list of Invariant Sections in the license notice of the 967 combined work. 968 969 In the combination, you must combine any sections Entitled 970 "History" in the various original documents, forming one section 971 Entitled "History"; likewise combine any sections Entitled 972 "Acknowledgements", and any sections Entitled "Dedications". You 973 must delete all sections Entitled "Endorsements." 974 975 6. COLLECTIONS OF DOCUMENTS 976 977 You may make a collection consisting of the Document and other 978 documents released under this License, and replace the individual 979 copies of this License in the various documents with a single copy 980 that is included in the collection, provided that you follow the 981 rules of this License for verbatim copying of each of the 982 documents in all other respects. 983 984 You may extract a single document from such a collection, and 985 distribute it individually under this License, provided you insert 986 a copy of this License into the extracted document, and follow 987 this License in all other respects regarding verbatim copying of 988 that document. 989 990 7. AGGREGATION WITH INDEPENDENT WORKS 991 992 A compilation of the Document or its derivatives with other 993 separate and independent documents or works, in or on a volume of 994 a storage or distribution medium, is called an "aggregate" if the 995 copyright resulting from the compilation is not used to limit the 996 legal rights of the compilation's users beyond what the individual 997 works permit. When the Document is included in an aggregate, this 998 License does not apply to the other works in the aggregate which 999 are not themselves derivative works of the Document. 1000 1001 If the Cover Text requirement of section 3 is applicable to these 1002 copies of the Document, then if the Document is less than one half 1003 of the entire aggregate, the Document's Cover Texts may be placed 1004 on covers that bracket the Document within the aggregate, or the 1005 electronic equivalent of covers if the Document is in electronic 1006 form. Otherwise they must appear on printed covers that bracket 1007 the whole aggregate. 1008 1009 8. TRANSLATION 1010 1011 Translation is considered a kind of modification, so you may 1012 distribute translations of the Document under the terms of section 1013 4. Replacing Invariant Sections with translations requires special 1014 permission from their copyright holders, but you may include 1015 translations of some or all Invariant Sections in addition to the 1016 original versions of these Invariant Sections. You may include a 1017 translation of this License, and all the license notices in the 1018 Document, and any Warranty Disclaimers, provided that you also 1019 include the original English version of this License and the 1020 original versions of those notices and disclaimers. In case of a 1021 disagreement between the translation and the original version of 1022 this License or a notice or disclaimer, the original version will 1023 prevail. 1024 1025 If a section in the Document is Entitled "Acknowledgements", 1026 "Dedications", or "History", the requirement (section 4) to 1027 Preserve its Title (section 1) will typically require changing the 1028 actual title. 1029 1030 9. TERMINATION 1031 1032 You may not copy, modify, sublicense, or distribute the Document 1033 except as expressly provided for under this License. Any other 1034 attempt to copy, modify, sublicense or distribute the Document is 1035 void, and will automatically terminate your rights under this 1036 License. However, parties who have received copies, or rights, 1037 from you under this License will not have their licenses 1038 terminated so long as such parties remain in full compliance. 1039 1040 10. FUTURE REVISIONS OF THIS LICENSE 1041 1042 The Free Software Foundation may publish new, revised versions of 1043 the GNU Free Documentation License from time to time. Such new 1044 versions will be similar in spirit to the present version, but may 1045 differ in detail to address new problems or concerns. See 1046 `http://www.gnu.org/copyleft/'. 1047 1048 Each version of the License is given a distinguishing version 1049 number. If the Document specifies that a particular numbered 1050 version of this License "or any later version" applies to it, you 1051 have the option of following the terms and conditions either of 1052 that specified version or of any later version that has been 1053 published (not as a draft) by the Free Software Foundation. If 1054 the Document does not specify a version number of this License, 1055 you may choose any version ever published (not as a draft) by the 1056 Free Software Foundation. 1057 105814.1 ADDENDUM: How to use this License for your documents 1059========================================================= 1060 1061To use this License in a document you have written, include a copy of 1062the License in the document and put the following copyright and license 1063notices just after the title page: 1064 1065 Copyright (C) YEAR YOUR NAME. 1066 Permission is granted to copy, distribute and/or modify this document 1067 under the terms of the GNU Free Documentation License, Version 1.2 1068 or any later version published by the Free Software Foundation; 1069 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 1070 Texts. A copy of the license is included in the section entitled ``GNU 1071 Free Documentation License''. 1072 1073 If you have Invariant Sections, Front-Cover Texts and Back-Cover 1074Texts, replace the "with...Texts." line with this: 1075 1076 with the Invariant Sections being LIST THEIR TITLES, with 1077 the Front-Cover Texts being LIST, and with the Back-Cover Texts 1078 being LIST. 1079 1080 If you have Invariant Sections without Cover Texts, or some other 1081combination of the three, merge those two alternatives to suit the 1082situation. 1083 1084 If your document contains nontrivial examples of program code, we 1085recommend releasing these examples in parallel under your choice of 1086free software license, such as the GNU General Public License, to 1087permit their use in free software. 1088 1089 1090 1091Tag Table: 1092Node: Top763 1093Node: Annotations Overview1862 1094Node: Limitations3661 1095Node: Migrating to GDB/MI6246 1096Node: Server Prefix6629 1097Node: Value Annotations7275 1098Node: Frame Annotations10445 1099Node: Displays14344 1100Node: Prompting15375 1101Node: Errors16878 1102Node: Breakpoint Info17768 1103Node: Invalidation18993 1104Node: Annotations for Running19472 1105Node: Source Annotations20985 1106Node: GNU Free Documentation License21942 1107 1108End Tag Table 1109