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