gdb/doc/annotate.texi

   1 \input texinfo   @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename annotate.info
   4 @settitle GDB Annotations
   5 @setchapternewpage off
   6 @c %**end of header
   7
   8 @set EDITION 0.4
   9 @set DATE April 1994
  10
  11 @ifinfo
  12 This file documents GDB annotations.
  13
  14 This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB
  15 Annotations}.  Copyright 1994 Free Software Foundation
  16
  17 Permission is granted to make and distribute verbatim copies of
  18 this manual provided the copyright notice and this permission notice
  19 are preserved on all copies.
  20
  21 @ignore
  22 Permission is granted to process this file through TeX and print the
  23 results, provided the printed document carries copying permission
  24 notice identical to this one except for the removal of this paragraph
  25 (this paragraph not being relevant to the printed manual).
  26
  27 @end ignore
  28 Permission is granted to copy and distribute modified versions of this
  29 manual under the conditions for verbatim copying, provided also that the
  30 entire resulting derived work is distributed under the terms of a
  31 permission notice identical to this one.
  32
  33 Permission is granted to copy and distribute translations of this manual
  34 into another language, under the above conditions for modified versions.
  35 @end ifinfo
  36
  37 @titlepage
  38 @title GDB Annotations
  39 @subtitle Edition @value{EDITION}
  40 @subtitle @value{DATE}
  41 @author Cygnus Support
  42 @page
  43 @vskip 0pt plus 1filll
  44 Permission is granted to make and distribute verbatim copies of
  45 this manual provided the copyright notice and this permission notice
  46 are preserved on all copies.
  47
  48 Copyright @copyright{} 1994 Free Software Foundation
  49 @end titlepage
  50
  51 @ifinfo
  52 @node Top
  53 @top GDB Annotations
  54
  55 This file describes annotations in GDB, the GNU symbolic debugger.
  56 Annotations are designed to interface GDB to graphical user interfaces
  57 or other similar programs which want to interact with GDB at a
  58 relatively high level.
  59
  60 This is Edition @value{EDITION}, @value{DATE}.
  61
  62 @menu
  63 * General::             What annotations are; the general syntax.
  64 * Server::              Issuing a command without affecting user state.
  65 * Values::              Values are marked as such.
  66 * Prompting::           GDB annotations marking GDB's need for input.
  67 * Errors::              Annotations for error messages.
  68 * Breakpoint Info::     Information on breakpoints.
  69 * Invalidation::        Some annotations describe things now invalid.
  70 * Source::              Annotations describing source code.
  71 @end menu
  72 @end ifinfo
  73
  74 @node General
  75 @chapter What is an Annotation?
  76
  77 To produce annotations, start GDB with the @code{--annotate=2} option.
  78
  79 Annotations start with a newline character, two @samp{control-z}
  80 characters, and the name of the annotation.  If there is no additional
  81 information associated with this annotation, the name of the annotation
  82 is followed immediately by a newline.  If there is additional
  83 information, the name of the annotation is followed by a space, the
  84 additional information, and a newline.  The additional information
  85 cannot contain newline characters.
  86
  87 Any output not beginning with a newline and two @samp{control-z}
  88 characters denotes literal output from GDB.  Currently there is no need
  89 for GDB to output a newline followed by two @samp{control-z} characters,
  90 but if there was such a need, the annotations could be extended with an
  91 @samp{escape} annotation which means those three characters as output.
  92
  93 A simple example of starting up GDB with annotations is:
  94
  95 @example
  96 $ gdb --annotate=2
  97 GDB is free software and you are welcome to distribute copies of it
  98  under certain conditions; type "show copying" to see the conditions.
  99 There is absolutely no warranty for GDB; type "show warranty" for details.
 100 GDB 4.12.3 (sparc-sun-sunos4.1.3),
 101 Copyright 1994 Free Software Foundation, Inc.
 102
 103 ^Z^Zpre-prompt
 104 (gdb)
 105 ^Z^Zprompt
 106 quit
 107
 108 ^Z^Zpost-prompt
 109 $
 110 @end example
 111
 112 Here @samp{quit} is input to GDB; the rest is output from GDB.  The three
 113 lines beginning @samp{^Z^Z} (where @samp{^Z} denotes a @samp{control-z}
 114 character) are annotations; the rest is output from GDB.
 115
 116 @node Server
 117 @chapter The Server Prefix
 118
 119 To issue a command to GDB without affecting certain aspects of the state
 120 which is seen by users, prefix it with @samp{server }.  This means that
 121 this command will not affect the command history, nor will it affect
 122 GDB's notion of which command to repeat if @key{RET} is pressed on a
 123 line by itself.
 124
 125 The server prefix does not affect the recording of values into the value
 126 history; to print a value without recording it into the value history,
 127 use the @code{output} command instead of the @code{print} command.
 128
 129 @node Values
 130 @chapter Values
 131
 132 When a value is printed in various contexts, GDB uses annotations to
 133 delimit the value from the surrounding text.
 134
 135 If a value is printed using @code{print} and added to the value history,
 136 the annotation looks like
 137
 138 @example
 139 ^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
 140 @var{history-string}
 141 ^Z^Zvalue-history-value
 142 @var{the-value}
 143 ^Z^Zvalue-history-end
 144 @end example
 145
 146 where @var{history-number} is the number it is getting in the value
 147 history, @var{history-string} is a string, such as @samp{$5 = }, which
 148 introduces the value to the user, @var{the-value} is the output
 149 corresponding to the value itself, and @var{value-flags} is @samp{*} for
 150 a value which can be dereferenced and @samp{-} for a value which cannot.
 151
 152 If the value is not added to the value history (it is an invalid float
 153 or it is printed with the @code{output} command), the annotation is similar:
 154
 155 @example
 156 ^Z^Zvalue-begin @var{value-flags}
 157 @var{the-value}
 158 ^Z^Zvalue-end
 159 @end example
 160
 161 When GDB prints an argument to a function (for example, in the output
 162 from the @code{backtrace} command), it annotates it as follows:
 163
 164 @example
 165 ^Z^Zarg-begin
 166 @var{argument-name}
 167 ^Z^Zarg-name-end
 168 @var{separator-string}
 169 ^Z^Zarg-value @var{value-flags}
 170 @var{the-value}
 171 ^Z^Zarg-end
 172 @end example
 173
 174 where @var{argument-name} is the name of the argument,
 175 @var{separator-string} is text which separates the name from the value
 176 for the user's benefit (such as @samp{=}), and @var{value-flags} and
 177 @var{the-value} have the same meanings as in a
 178 @code{value-history-begin} annotation.
 179
 180 When printing a structure, GDB annotates it as follows:
 181
 182 @example
 183 ^Z^Zfield-begin @var{value-flags}
 184 @var{field-name}
 185 ^Z^Zfield-name-end
 186 @var{separator-string}
 187 ^Z^Zfield-value
 188 @var{the-value}
 189 ^Z^Zfield-end
 190 @end example
 191
 192 where @var{field-name} is the name of the field, @var{separator-string}
 193 is text which separates the name from the value for the user's benefit
 194 (such as @samp{=}), and @var{value-flags} and @var{the-value} have the
 195 same meanings as in a @code{value-history-begin} annotation.
 196
 197 When printing an array, GDB annotates it as follows:
 198
 199 @example
 200 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
 201 @end example
 202
 203 where @var{array-index} is the index of the first element being
 204 annotated and @var{value-flags} has the same meaning as in a
 205 @code{value-history-begin} annotation.  This is followed by any number
 206 of elements, where is element can be either a single element:
 207
 208 @example
 209 @samp{,} @var{whitespace}         ; @r{omitted for the first element}
 210 @var{the-value}
 211 ^Z^Zelt
 212 @end example
 213
 214 or a repeated element
 215
 216 @example
 217 @samp{,} @var{whitespace}         ; @r{omitted for the first element}
 218 @var{the-value}
 219 ^Z^Zelt-rep @var{number-of-repititions}
 220 @var{repetition-string}
 221 ^Z^Zelt-rep-end
 222 @end example
 223
 224 In both cases, @var{the-value} is the output for the value of the
 225 element and @var{whitespace} can contain spaces, tabs, and newlines.  In
 226 the repeated case, @var{number-of-repititons} is the number of
 227 consecutive array elements which contain that value, and
 228 @var{repetition-string} is a string which is designed to convey to the
 229 user that repitition is being depicted.
 230
 231 Once all the array elements have been output, the array annotation is
 232 ended with
 233
 234 @example
 235 ^Z^Zarray-section-end
 236 @end example
 237
 238 @node Prompting
 239 @chapter Annotation for GDB Input
 240
 241 When GDB prompts for input, it annotates this fact so it is possible
 242 to know when to send output, when the output from a given command is
 243 over, etc.
 244
 245 Different kinds of input each have a different @dfn{input type}.  Each
 246 input type has three annotations: a @code{pre-} annotation, which
 247 denotes the beginning of any prompt which is being output, a plain
 248 annotation, which denotes the end of the prompt, and then a @code{post-}
 249 annotation which denotes the end of any echo which may (or may not) be
 250 associated with the input.  For example, the @code{prompt} input type
 251 features the following annotations:
 252
 253 @example
 254 ^Z^Zpre-prompt
 255 ^Z^Zprompt
 256 ^Z^Zpost-prompt
 257 @end example
 258
 259 The input types are
 260
 261 @table @code
 262 @item prompt
 263 When GDB is prompting for a command (the main GDB prompt).
 264
 265 @item commands
 266 When GDB prompts for a set of commands, like in the @code{commands}
 267 command.  The annotations are repeated for each command which is input.
 268
 269 @item overload-choice
 270 When GDB wants the user to select between various overloaded functions.
 271
 272 @item query
 273 When GDB wants the user to confirm a potentially dangerous operation.
 274
 275 @item prompt-for-continue
 276 When GDB is asking the user to press return to continue.  Note: Don't
 277 expect this to work well; instead use @code{set height 0} to disable
 278 prompting.  This is because the counting of lines is buggy in the
 279 presence of annotations.
 280 @end table
 281
 282 @node Errors
 283 @chapter Errors
 284
 285 @example
 286 ^Z^Zquit
 287 @end example
 288
 289 This annotation occurs right before GDB responds to an interrupt.
 290
 291 @example
 292 ^Z^Zerror
 293 @end example
 294
 295 This annotation occurs right before GDB responds to an error.
 296
 297 Quit and error annotations indicate that any annotations which GDB was
 298 in the middle of may end abruptly.  For example, if a
 299 @code{value-history-begin} annotation is followed by a @code{error}, one
 300 cannot expect to receive the matching @code{value-history-end}.  One
 301 cannot expect not to receive it either, however; an error annotation
 302 does not necessarily mean that GDB is immediately returning all the way
 303 to the top level.
 304
 305 A quit or error annotation may be preceded by
 306
 307 @example
 308 ^Z^Zerror-begin
 309 @end example
 310
 311 Any output between that and the quit or error annotation is the error
 312 message.
 313
 314 Warning messages are not yet annotated.
 315 @c If we want to change that, need to fix warning(), type_error(),
 316 @c range_error(), and possibly other places.
 317
 318 @node Breakpoint Info
 319 @chapter Information on Breakpoints
 320
 321 The output from the @code{info breakpoints} command is annotated as follows:
 322
 323 @example
 324 ^Z^Zbreakpoints-headers
 325 @var{headers}
 326 ^Z^Zbreakpoints-table
 327 @end example
 328
 329 where @var{headers} is a string which is designed to convey to the user
 330 the order and significance of the fields.  This is followed by any
 331 number of entries.  Each entry beings with a @code{field 0} annotation.
 332 Some fields can be omitted if they don't apply for this entry.  Fields
 333 have trailing whitespace so that if they are printed in order in a
 334 fixed-width font, they match up with the headers.  The fields for an
 335 entry are:
 336
 337 @example
 338 ^Z^Zfield 0
 339 @var{number}
 340 ^Z^Zfield 1
 341 @var{type}
 342 ^Z^Zfield 2
 343 @var{disposition}
 344 ^Z^Zfield 3
 345 @var{enable}
 346 ^Z^Zfield 4
 347 @var{address}
 348 ^Z^Zfield 5
 349 @var{what}
 350 ^Z^Zfield 6
 351 @var{frame}
 352 ^Z^Zfield 7
 353 @var{condition}
 354 ^Z^Zfield 8
 355 @var{ignore-count}
 356 ^Z^Zfield 9
 357 @var{commands}
 358 @end example
 359
 360 The output ends with
 361
 362 @example
 363 ^Z^Zbreakpoints-table-end
 364 @end example
 365
 366 @node Invalidation
 367 @chapter Invalidation Notices
 368
 369 The following annotations say that certain pieces of state may have
 370 changed.
 371
 372 @table @code
 373 @item ^Z^Zframes-invalid
 374
 375 The frames (for example, output from the @code{backtrace} command) may
 376 have changed.
 377
 378 @item ^Z^Zbreakpoints-invalid
 379
 380 The breakpoints may have changed.  For example, the user just added or
 381 deleted a breakpoint.
 382 @end table
 383
 384 @node Source
 385 @chapter Displaying Source
 386
 387 The following annotation is used instead of displaying source code:
 388
 389 @example
 390 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
 391 @end example
 392
 393 where @var{filename} is an absolute file name indicating which source
 394 file, @var{line} is the line number within that file (where 1 is the
 395 first line in the file), @var{character} is the character position
 396 within the file (where 0 is the first character in the file) (for most
 397 debug formats this will necessarily point to the beginning of a line),
 398 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
 399 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
 400 @var{addr} is the address in the target program associated with the
 401 source which is being displayed.
 402
 403 @bye