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