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