gdb/mi/gdbmi.texinfo

   1 @c  \input texinfo   @c -*-texinfo-*-
   2 @c  @c %**start of header
   3 @c  @setfilename gdbmi.info
   4 @c  @settitle GDB/MI Machine Interface
   5 @c  @setchapternewpage off
   6 @c  @c %**end of header
   7
   8 @c  @ifinfo
   9 @c  This file documents GDB/MI, a Machine Interface to GDB.
  10
  11 @c  Copyright 2000, 2001, 2002 Free Software Foundation, Inc.
  12 @c  Contributed by Cygnus Solutions.
  13
  14 @c  Permission is granted to copy, distribute and/or modify this document
  15 @c  under the terms of the GNU Free Documentation License, Version 1.1 or
  16 @c  any later version published by the Free Software Foundation; with no
  17 @c  Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
  18 @c  and with the Back-Cover Texts as in (a) below.
  19
  20 @c  (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
  21 @c  this GNU Manual, like GNU software.  Copies published by the Free
  22 @c  Software Foundation raise funds for GNU development.''
  23 @c  @end ifinfo
  24
  25 @c  @c  This title page illustrates only one of the
  26 @c  @c  two methods of forming a title page.
  27
  28 @c  @titlepage
  29 @c  @title GDB/MI
  30 @c  @subtitle Version 0.3
  31 @c  @subtitle Apr 2001
  32 @c  @author Andrew Cagney, Fernando Nasser and Elena Zannoni
  33
  34 @c  @c  The following two commands
  35 @c  @c  start the copyright page.
  36 @c  @page
  37 @c  @vskip 0pt plus 1filll
  38
  39 @c  Copyright @copyright{} 2000, 2001, 2002 Free Software Foundation, Inc.
  40
  41 @c  Permission is granted to copy, distribute and/or modify this document
  42 @c  under the terms of the GNU Free Documentation License, Version 1.1 or
  43 @c  any later version published by the Free Software Foundation; with no
  44 @c  Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
  45 @c  and with the Back-Cover Texts as in (a) below.
  46
  47 @c  (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
  48 @c  this GNU Manual, like GNU software.  Copies published by the Free
  49 @c  Software Foundation raise funds for GNU development.''
  50 @c  @end titlepage
  51
  52 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  53 @node GDB/MI
  54 @chapter The @sc{gdb/mi} Interface
  55
  56 @unnumberedsec Function and Purpose
  57
  58 @cindex @sc{gdb/mi}, its purpose
  59 @sc{gdb/mi} is a line based machine oriented text interface to @value{GDBN}.  It is
  60 specifically intended to support the development of systems which use
  61 the debugger as just one small component of a larger system.
  62
  63 This chapter is a specification of the @sc{gdb/mi} interface.  It is written
  64 in the form of a reference manual.
  65
  66 Note that @sc{gdb/mi} is still under construction, so some of the
  67 features described below are incomplete and subject to change.
  68
  69 @unnumberedsec Notation and Terminology
  70
  71 @cindex notational conventions, for @sc{gdb/mi}
  72 This chapter uses the following notation:
  73
  74 @itemize @bullet
  75 @item
  76 @code{|} separates two alternatives.
  77
  78 @item
  79 @code{[ @var{something} ]} indicates that @var{something} is optional:
  80 it may or may not be given.
  81
  82 @item
  83 @code{( @var{group} )*} means that @var{group} inside the parentheses
  84 may repeat zero or more times.
  85
  86 @item
  87 @code{( @var{group} )+} means that @var{group} inside the parentheses
  88 may repeat one or more times.
  89
  90 @item
  91 @code{"@var{string}"} means a literal @var{string}.
  92 @end itemize
  93
  94 @ignore
  95 @heading Dependencies
  96 @end ignore
  97
  98 @heading Acknowledgments
  99
 100 In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
 101 Elena Zannoni.
 102
 103 @menu
 104 * GDB/MI Command Syntax::
 105 * GDB/MI Compatibility with CLI::
 106 * GDB/MI Output Records::
 107 * GDB/MI Command Description Format::
 108 * GDB/MI Breakpoint Table Commands::
 109 * GDB/MI Data Manipulation::
 110 * GDB/MI Program Control::
 111 * GDB/MI Miscellaneous Commands::
 112 @ignore
 113 * GDB/MI Kod Commands::
 114 * GDB/MI Memory Overlay Commands::
 115 * GDB/MI Signal Handling Commands::
 116 @end ignore
 117 * GDB/MI Stack Manipulation::
 118 * GDB/MI Symbol Query::
 119 * GDB/MI Target Manipulation::
 120 * GDB/MI Thread Commands::
 121 * GDB/MI Tracepoint Commands::
 122 * GDB/MI Variable Objects::
 123 @end menu
 124
 125 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 126 @node GDB/MI Command Syntax
 127 @section @sc{gdb/mi} Command Syntax
 128
 129 @menu
 130 * GDB/MI Input Syntax::
 131 * GDB/MI Output Syntax::
 132 * GDB/MI Simple Examples::
 133 @end menu
 134
 135 @node GDB/MI Input Syntax
 136 @subsection @sc{gdb/mi} Input Syntax
 137
 138 @cindex input syntax for @sc{gdb/mi}
 139 @cindex @sc{gdb/mi}, input syntax
 140 @table @code
 141 @item @var{command} @expansion{}
 142 @code{@var{cli-command} | @var{mi-command}}
 143
 144 @item @var{cli-command} @expansion{}
 145 @code{[ @var{token} ] @var{cli-command} @var{nl}}, where
 146 @var{cli-command} is any existing @value{GDBN} CLI command.
 147
 148 @item @var{mi-command} @expansion{}
 149 @code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )*
 150 @code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}}
 151
 152 @item @var{token} @expansion{}
 153 "any sequence of digits"
 154
 155 @item @var{option} @expansion{}
 156 @code{"-" @var{parameter} [ " " @var{parameter} ]}
 157
 158 @item @var{parameter} @expansion{}
 159 @code{@var{non-blank-sequence} | @var{c-string}}
 160
 161 @item @var{operation} @expansion{}
 162 @emph{any of the operations described in this chapter}
 163
 164 @item @var{non-blank-sequence} @expansion{}
 165 @emph{anything, provided it doesn't contain special characters such as
 166 "-", @var{nl}, """ and of course " "}
 167
 168 @item @var{c-string} @expansion{}
 169 @code{""" @var{seven-bit-iso-c-string-content} """}
 170
 171 @item @var{nl} @expansion{}
 172 @code{CR | CR-LF}
 173 @end table
 174
 175 @noindent
 176 Notes:
 177
 178 @itemize @bullet
 179 @item
 180 The CLI commands are still handled by the @sc{mi} interpreter; their
 181 output is described below.
 182
 183 @item
 184 The @code{@var{token}}, when present, is passed back when the command
 185 finishes.
 186
 187 @item
 188 Some @sc{mi} commands accept optional arguments as part of the parameter
 189 list.  Each option is identified by a leading @samp{-} (dash) and may be
 190 followed by an optional argument parameter.  Options occur first in the
 191 parameter list and can be delimited from normal parameters using
 192 @samp{--} (this is useful when some parameters begin with a dash).
 193 @end itemize
 194
 195 Pragmatics:
 196
 197 @itemize @bullet
 198 @item
 199 We want easy access to the existing CLI syntax (for debugging).
 200
 201 @item
 202 We want it to be easy to spot a @sc{mi} operation.
 203 @end itemize
 204
 205 @node GDB/MI Output Syntax
 206 @subsection @sc{gdb/mi} Output Syntax
 207
 208 @cindex output syntax of @sc{gdb/mi}
 209 @cindex @sc{gdb/mi}, output syntax
 210 The output from @sc{gdb/mi} consists of zero or more out-of-band records
 211 followed, optionally, by a single result record.  This result record
 212 is for the most recent command.  The sequence of output records is
 213 terminated by @samp{(@value{GDBP})}.
 214
 215 If an input command was prefixed with a @code{@var{token}} then the
 216 corresponding output for that command will also be prefixed by that same
 217 @var{token}.
 218
 219 @table @code
 220 @item @var{output} @expansion{}
 221 @code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
 222
 223 @item @var{result-record} @expansion{}
 224 @code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
 225
 226 @item @var{out-of-band-record} @expansion{}
 227 @code{@var{async-record} | @var{stream-record}}
 228
 229 @item @var{async-record} @expansion{}
 230 @code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
 231
 232 @item @var{exec-async-output} @expansion{}
 233 @code{[ @var{token} ] "*" @var{async-output}}
 234
 235 @item @var{status-async-output} @expansion{}
 236 @code{[ @var{token} ] "+" @var{async-output}}
 237
 238 @item @var{notify-async-output} @expansion{}
 239 @code{[ @var{token} ] "=" @var{async-output}}
 240
 241 @item @var{async-output} @expansion{}
 242 @code{@var{async-class} ( "," @var{result} )* @var{nl}}
 243
 244 @item @var{result-class} @expansion{}
 245 @code{"done" | "running" | "connected" | "error" | "exit"}
 246
 247 @item @var{async-class} @expansion{}
 248 @code{"stopped" | @var{others}} (where @var{others} will be added
 249 depending on the needs---this is still in development).
 250
 251 @item @var{result} @expansion{}
 252 @code{ @var{variable} "=" @var{value}}
 253
 254 @item @var{variable} @expansion{}
 255 @code{ @var{string} }
 256
 257 @item @var{value} @expansion{}
 258 @code{ @var{const} | @var{tuple} | @var{list} }
 259
 260 @item @var{const} @expansion{}
 261 @code{@var{c-string}}
 262
 263 @item @var{tuple} @expansion{}
 264 @code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" }
 265
 266 @item @var{list} @expansion{}
 267 @code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "["
 268 @var{result} ( "," @var{result} )* "]" }
 269
 270 @item @var{stream-record} @expansion{}
 271 @code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
 272
 273 @item @var{console-stream-output} @expansion{}
 274 @code{"~" @var{c-string}}
 275
 276 @item @var{target-stream-output} @expansion{}
 277 @code{"@@" @var{c-string}}
 278
 279 @item @var{log-stream-output} @expansion{}
 280 @code{"&" @var{c-string}}
 281
 282 @item @var{nl} @expansion{}
 283 @code{CR | CR-LF}
 284
 285 @item @var{token} @expansion{}
 286 @emph{any sequence of digits}.
 287 @end table
 288
 289 @noindent
 290 Notes:
 291
 292 @itemize @bullet
 293 @item
 294 All output sequences end in a single line containing a period.
 295
 296 @item
 297 The @code{@var{token}} is from the corresponding request.  If an execution
 298 command is interrupted by the @samp{-exec-interrupt} command, the
 299 @var{token} associated with the @samp{*stopped} message is the one of the
 300 original execution command, not the one of the interrupt command.
 301
 302 @item
 303 @cindex status output in @sc{gdb/mi}
 304 @var{status-async-output} contains on-going status information about the
 305 progress of a slow operation.  It can be discarded.  All status output is
 306 prefixed by @samp{+}.
 307
 308 @item
 309 @cindex async output in @sc{gdb/mi}
 310 @var{exec-async-output} contains asynchronous state change on the target
 311 (stopped, started, disappeared).  All async output is prefixed by
 312 @samp{*}.
 313
 314 @item
 315 @cindex notify output in @sc{gdb/mi}
 316 @var{notify-async-output} contains supplementary information that the
 317 client should handle (e.g., a new breakpoint information).  All notify
 318 output is prefixed by @samp{=}.
 319
 320 @item
 321 @cindex console output in @sc{gdb/mi}
 322 @var{console-stream-output} is output that should be displayed as is in the
 323 console.  It is the textual response to a CLI command.  All the console
 324 output is prefixed by @samp{~}.
 325
 326 @item
 327 @cindex target output in @sc{gdb/mi}
 328 @var{target-stream-output} is the output produced by the target program.
 329 All the target output is prefixed by @samp{@@}.
 330
 331 @item
 332 @cindex log output in @sc{gdb/mi}
 333 @var{log-stream-output} is output text coming from @value{GDBN}'s internals, for
 334 instance messages that should be displayed as part of an error log.  All
 335 the log output is prefixed by @samp{&}.
 336
 337 @item
 338 @cindex list output in @sc{gdb/mi}
 339 New @sc{gdb/mi} commands should only output @var{lists} containing
 340 @var{values}.
 341
 342
 343 @end itemize
 344
 345 @xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
 346 details about the various output records.
 347
 348 @node GDB/MI Simple Examples
 349 @subsection Simple Examples of @sc{gdb/mi} Interaction
 350 @cindex @sc{gdb/mi}, simple examples
 351
 352 This subsection presents several simple examples of interaction using
 353 the @sc{gdb/mi} interface.  In these examples, @samp{->} means that the
 354 following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
 355 the output received from @sc{gdb/mi}.
 356
 357 @subsubheading Target Stop
 358 @c Ummm... There is no "-stop" command. This assumes async, no?
 359 Here's an example of stopping the inferior process:
 360
 361 @example
 362 -> -stop
 363 <- (@value{GDBP})
 364 @end example
 365
 366 @noindent
 367 and later:
 368
 369 @example
 370 <- *stop,reason="stop",address="0x123",source="a.c:123"
 371 <- (@value{GDBP})
 372 @end example
 373
 374 @subsubheading Simple CLI Command
 375
 376 Here's an example of a simple CLI command being passed through
 377 @sc{gdb/mi} and on to the CLI.
 378
 379 @example
 380 -> print 1+2
 381 <- &"print 1+2\n"
 382 <- ~"$1 = 3\n"
 383 <- ^done
 384 <- (@value{GDBP})
 385 @end example
 386
 387 @subsubheading Command With Side Effects
 388
 389 @example
 390 -> -symbol-file xyz.exe
 391 <- *breakpoint,nr="3",address="0x123",source="a.c:123"
 392 <- (@value{GDBP})
 393 @end example
 394
 395 @subsubheading A Bad Command
 396
 397 Here's what happens if you pass a non-existent command:
 398
 399 @example
 400 -> -rubbish
 401 <- ^error,msg="Undefined MI command: rubbish"
 402 <- (@value{GDBP})
 403 @end example
 404
 405 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 406 @node GDB/MI Compatibility with CLI
 407 @section @sc{gdb/mi} Compatibility with CLI
 408
 409 @cindex compatibility, @sc{gdb/mi} and CLI
 410 @cindex @sc{gdb/mi}, compatibility with CLI
 411 To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi}
 412 accepts existing CLI commands.  As specified by the syntax, such
 413 commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will
 414 respond.
 415
 416 This mechanism is provided as an aid to developers of @sc{gdb/mi}
 417 clients and not as a reliable interface into the CLI.  Since the command
 418 is being interpreteted in an environment that assumes @sc{gdb/mi}
 419 behaviour, the exact output of such commands is likely to end up being
 420 an un-supported hybrid of @sc{gdb/mi} and CLI output.
 421
 422 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 423 @node GDB/MI Output Records
 424 @section @sc{gdb/mi} Output Records
 425
 426 @menu
 427 * GDB/MI Result Records::
 428 * GDB/MI Stream Records::
 429 * GDB/MI Out-of-band Records::
 430 @end menu
 431
 432 @node GDB/MI Result Records
 433 @subsection @sc{gdb/mi} Result Records
 434
 435 @cindex result records in @sc{gdb/mi}
 436 @cindex @sc{gdb/mi}, result records
 437 In addition to a number of out-of-band notifications, the response to a
 438 @sc{gdb/mi} command includes one of the following result indications:
 439
 440 @table @code
 441 @findex ^done
 442 @item "^done" [ "," @var{results} ]
 443 The synchronous operation was successful, @code{@var{results}} are the return
 444 values.
 445
 446 @item "^running"
 447 @findex ^running
 448 @c Is this one correct?  Should it be an out-of-band notification?
 449 The asynchronous operation was successfully started.  The target is
 450 running.
 451
 452 @item "^error" "," @var{c-string}
 453 @findex ^error
 454 The operation failed.  The @code{@var{c-string}} contains the corresponding
 455 error message.
 456 @end table
 457
 458 @node GDB/MI Stream Records
 459 @subsection @sc{gdb/mi} Stream Records
 460
 461 @cindex @sc{gdb/mi}, stream records
 462 @cindex stream records in @sc{gdb/mi}
 463 @value{GDBN} internally maintains a number of output streams: the console, the
 464 target, and the log.  The output intended for each of these streams is
 465 funneled through the @sc{gdb/mi} interface using @dfn{stream records}.
 466
 467 Each stream record begins with a unique @dfn{prefix character} which
 468 identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
 469 Syntax}).  In addition to the prefix, each stream record contains a
 470 @code{@var{string-output}}.  This is either raw text (with an implicit new
 471 line) or a quoted C string (which does not contain an implicit newline).
 472
 473 @table @code
 474 @item "~" @var{string-output}
 475 The console output stream contains text that should be displayed in the
 476 CLI console window.  It contains the textual responses to CLI commands.
 477
 478 @item "@@" @var{string-output}
 479 The target output stream contains any textual output from the running
 480 target.
 481
 482 @item "&" @var{string-output}
 483 The log stream contains debugging messages being produced by @value{GDBN}'s
 484 internals.
 485 @end table
 486
 487 @node GDB/MI Out-of-band Records
 488 @subsection @sc{gdb/mi} Out-of-band Records
 489
 490 @cindex out-of-band records in @sc{gdb/mi}
 491 @cindex @sc{gdb/mi}, out-of-band records
 492 @dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
 493 additional changes that have occurred.  Those changes can either be a
 494 consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
 495 target activity (e.g., target stopped).
 496
 497 The following is a preliminary list of possible out-of-band records.
 498
 499 @table @code
 500 @item "*" "stop"
 501 @end table
 502
 503
 504 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 505 @node GDB/MI Command Description Format
 506 @section @sc{gdb/mi} Command Description Format
 507
 508 The remaining sections describe blocks of commands.  Each block of
 509 commands is laid out in a fashion similar to this section.
 510
 511 Note the the line breaks shown in the examples are here only for
 512 readability.  They don't appear in the real output.
 513 Also note that the commands with a non-available example (N.A.@:) are
 514 not yet implemented.
 515
 516 @subheading Motivation
 517
 518 The motivation for this collection of commands.
 519
 520 @subheading Introduction
 521
 522 A brief introduction to this collection of commands as a whole.
 523
 524 @subheading Commands
 525
 526 For each command in the block, the following is described:
 527
 528 @subsubheading Synopsis
 529
 530 @example
 531  -command @var{args}@dots{}
 532 @end example
 533
 534 @subsubheading @value{GDBN} Command
 535
 536 The corresponding @value{GDBN} CLI command.
 537
 538 @subsubheading Result
 539
 540 @subsubheading Out-of-band
 541
 542 @subsubheading Notes
 543
 544 @subsubheading Example
 545
 546
 547 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 548 @node GDB/MI Breakpoint Table Commands
 549 @section @sc{gdb/mi} Breakpoint table commands
 550
 551 @cindex breakpoint commands for @sc{gdb/mi}
 552 @cindex @sc{gdb/mi}, breakpoint commands
 553 This section documents @sc{gdb/mi} commands for manipulating
 554 breakpoints.
 555
 556 @subheading The @code{-break-after} Command
 557 @findex -break-after
 558
 559 @subsubheading Synopsis
 560
 561 @example
 562  -break-after @var{number} @var{count}
 563 @end example
 564
 565 The breakpoint number @var{number} is not in effect until it has been
 566 hit @var{count} times.  To see how this is reflected in the output of
 567 the @samp{-break-list} command, see the description of the
 568 @samp{-break-list} command below.
 569
 570 @subsubheading @value{GDBN} Command
 571
 572 The corresponding @value{GDBN} command is @samp{ignore}.
 573
 574 @subsubheading Example
 575
 576 @smallexample
 577 (@value{GDBP})
 578 -break-insert main
 579 ^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@}
 580 (@value{GDBP})
 581 -break-after 1 3
 582 ~
 583 ^done
 584 (@value{GDBP})
 585 -break-list
 586 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
 587 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
 588 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
 589 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
 590 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
 591 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
 592 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
 593 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
 594 addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
 595 ignore="3"@}]@}
 596 (@value{GDBP})
 597 @end smallexample
 598
 599 @ignore
 600 @subheading The @code{-break-catch} Command
 601 @findex -break-catch
 602
 603 @subheading The @code{-break-commands} Command
 604 @findex -break-commands
 605 @end ignore
 606
 607
 608 @subheading The @code{-break-condition} Command
 609 @findex -break-condition
 610
 611 @subsubheading Synopsis
 612
 613 @example
 614  -break-condition @var{number} @var{expr}
 615 @end example
 616
 617 Breakpoint @var{number} will stop the program only if the condition in
 618 @var{expr} is true.  The condition becomes part of the
 619 @samp{-break-list} output (see the description of the @samp{-break-list}
 620 command below).
 621
 622 @subsubheading @value{GDBN} Command
 623
 624 The corresponding @value{GDBN} command is @samp{condition}.
 625
 626 @subsubheading Example
 627
 628 @smallexample
 629 (@value{GDBP})
 630 -break-condition 1 1
 631 ^done
 632 (@value{GDBP})
 633 -break-list
 634 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
 635 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
 636 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
 637 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
 638 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
 639 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
 640 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
 641 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
 642 addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
 643 times="0",ignore="3"@}]@}
 644 (@value{GDBP})
 645 @end smallexample
 646
 647 @subheading The @code{-break-delete} Command
 648 @findex -break-delete
 649
 650 @subsubheading Synopsis
 651
 652 @example
 653  -break-delete ( @var{breakpoint} )+
 654 @end example
 655
 656 Delete the breakpoint(s) whose number(s) are specified in the argument
 657 list.  This is obviously reflected in the breakpoint list.
 658
 659 @subsubheading @value{GDBN} command
 660
 661 The corresponding @value{GDBN} command is @samp{delete}.
 662
 663 @subsubheading Example
 664
 665 @example
 666 (@value{GDBP})
 667 -break-delete 1
 668 ^done
 669 (@value{GDBP})
 670 -break-list
 671 ^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
 672 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
 673 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
 674 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
 675 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
 676 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
 677 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
 678 body=[]@}
 679 (@value{GDBP})
 680 @end example
 681
 682 @subheading The @code{-break-disable} Command
 683 @findex -break-disable
 684
 685 @subsubheading Synopsis
 686
 687 @example
 688  -break-disable ( @var{breakpoint} )+
 689 @end example
 690
 691 Disable the named @var{breakpoint}(s).  The field @samp{enabled} in the
 692 break list is now set to @samp{n} for the named @var{breakpoint}(s).
 693
 694 @subsubheading @value{GDBN} Command
 695
 696 The corresponding @value{GDBN} command is @samp{disable}.
 697
 698 @subsubheading Example
 699
 700 @smallexample
 701 (@value{GDBP})
 702 -break-disable 2
 703 ^done
 704 (@value{GDBP})
 705 -break-list
 706 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
 707 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
 708 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
 709 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
 710 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
 711 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
 712 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
 713 body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
 714 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@}
 715 (@value{GDBP})
 716 @end smallexample
 717
 718 @subheading The @code{-break-enable} Command
 719 @findex -break-enable
 720
 721 @subsubheading Synopsis
 722
 723 @example
 724  -break-enable ( @var{breakpoint} )+
 725 @end example
 726
 727 Enable (previously disabled) @var{breakpoint}(s).
 728
 729 @subsubheading @value{GDBN} Command
 730
 731 The corresponding @value{GDBN} command is @samp{enable}.
 732
 733 @subsubheading Example
 734
 735 @smallexample
 736 (@value{GDBP})
 737 -break-enable 2
 738 ^done
 739 (@value{GDBP})
 740 -break-list
 741 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
 742 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
 743 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
 744 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
 745 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
 746 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
 747 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
 748 body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
 749 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@}
 750 (@value{GDBP})
 751 @end smallexample
 752
 753 @subheading The @code{-break-info} Command
 754 @findex -break-info
 755
 756 @subsubheading Synopsis
 757
 758 @example
 759  -break-info @var{breakpoint}
 760 @end example
 761
 762 @c REDUNDANT???
 763 Get information about a single breakpoint.
 764
 765 @subsubheading @value{GDBN} command
 766
 767 The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
 768
 769 @subsubheading Example
 770 N.A.
 771
 772 @subheading The @code{-break-insert} Command
 773 @findex -break-insert
 774
 775 @subsubheading Synopsis
 776
 777 @example
 778  -break-insert [ -t ] [ -h ] [ -r ]
 779     [ -c @var{condition} ] [ -i @var{ignore-count} ]
 780     [ -p @var{thread} ] [ @var{line} | @var{addr} ]
 781 @end example
 782
 783 @noindent
 784 If specified, @var{line}, can be one of:
 785
 786 @itemize @bullet
 787 @item function
 788 @c @item +offset
 789 @c @item -offset
 790 @c @item linenum
 791 @item filename:linenum
 792 @item filename:function
 793 @item *address
 794 @end itemize
 795
 796 The possible optional parameters of this command are:
 797
 798 @table @samp
 799 @item -t
 800 Insert a tempoary breakpoint.
 801 @item -h
 802 Insert a hardware breakpoint.
 803 @item -c @var{condition}
 804 Make the breakpoint conditional on @var{condition}.
 805 @item -i @var{ignore-count}
 806 Initialize the @var{ignore-count}.
 807 @item -r
 808 Insert a regular breakpoint in all the functions whose names match the
 809 given regular expression.  Other flags are not applicable to regular
 810 expresson.
 811 @end table
 812
 813 @subsubheading Result
 814
 815 The result is in the form:
 816
 817 @example
 818  ^done,bkptno="@var{number}",func="@var{funcname}",
 819   file="@var{filename}",line="@var{lineno}"
 820 @end example
 821
 822 @noindent
 823 where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname}
 824 is the name of the function where the breakpoint was inserted,
 825 @var{filename} is the name of the source file which contains this
 826 function, and @var{lineno} is the source line number within that file.
 827
 828 Note: this format is open to change.
 829 @c An out-of-band breakpoint instead of part of the result?
 830
 831 @subsubheading @value{GDBN} Command
 832
 833 The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
 834 @samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
 835
 836 @subsubheading Example
 837
 838 @smallexample
 839 (@value{GDBP})
 840 -break-insert main
 841 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
 842 (@value{GDBP})
 843 -break-insert -t foo
 844 ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
 845 (@value{GDBP})
 846 -break-list
 847 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
 848 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
 849 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
 850 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
 851 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
 852 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
 853 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
 854 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
 855 addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@},
 856 bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
 857 addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}]@}
 858 (@value{GDBP})
 859 -break-insert -r foo.*
 860 ~int foo(int, int);
 861 ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
 862 (@value{GDBP})
 863 @end smallexample
 864
 865 @subheading The @code{-break-list} Command
 866 @findex -break-list
 867
 868 @subsubheading Synopsis
 869
 870 @example
 871  -break-list
 872 @end example
 873
 874 Displays the list of inserted breakpoints, showing the following fields:
 875
 876 @table @samp
 877 @item Number
 878 number of the breakpoint
 879 @item Type
 880 type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
 881 @item Disposition
 882 should the breakpoint be deleted or disabled when it is hit: @samp{keep}
 883 or @samp{nokeep}
 884 @item Enabled
 885 is the breakpoint enabled or no: @samp{y} or @samp{n}
 886 @item Address
 887 memory location at which the breakpoint is set
 888 @item What
 889 logical location of the breakpoint, expressed by function name, file
 890 name, line number
 891 @item Times
 892 number of times the breakpoint has been hit
 893 @end table
 894
 895 If there are no breakpoints or watchpoints, the @code{BreakpointTable}
 896 @code{body} field is an empty list.
 897
 898 @subsubheading @value{GDBN} Command
 899
 900 The corresponding @value{GDBN} command is @samp{info break}.
 901
 902 @subsubheading Example
 903
 904 @smallexample
 905 (@value{GDBP})
 906 -break-list
 907 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
 908 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
 909 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
 910 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
 911 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
 912 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
 913 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
 914 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
 915 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
 916 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
 917 addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}]@}
 918 (@value{GDBP})
 919 @end smallexample
 920
 921 Here's an example of the result when there are no breakpoints:
 922
 923 @smallexample
 924 (@value{GDBP})
 925 -break-list
 926 ^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
 927 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
 928 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
 929 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
 930 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
 931 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
 932 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
 933 body=[]@}
 934 (@value{GDBP})
 935 @end smallexample
 936
 937 @subheading The @code{-break-watch} Command
 938 @findex -break-watch
 939
 940 @subsubheading Synopsis
 941
 942 @example
 943  -break-watch [ -a | -r ]
 944 @end example
 945
 946 Create a watchpoint.  With the @samp{-a} option it will create an
 947 @dfn{access} watchpoint, i.e. a watchpoint that triggers either on a
 948 read from or on a write to the memory location.  With the @samp{-r}
 949 option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will
 950 trigger only when the memory location is accessed for reading.  Without
 951 either of the options, the watchpoint created is a regular watchpoint,
 952 i.e. it will trigger when the memory location is accessed for writing.
 953 @xref{Set Watchpoints, , Setting watchpoints}.
 954
 955 Note that @samp{-break-list} will report a single list of watchpoints and
 956 breakpoints inserted.
 957
 958 @subsubheading @value{GDBN} Command
 959
 960 The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and
 961 @samp{rwatch}.
 962
 963 @subsubheading Example
 964
 965 Setting a watchpoint on a variable in the @code{main} function:
 966
 967 @smallexample
 968 (@value{GDBP})
 969 -break-watch x
 970 ^done,wpt=@{number="2",exp="x"@}
 971 (@value{GDBP})
 972 -exec-continue
 973 ^running
 974 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
 975 value=@{old="-268439212",new="55"@},
 976 frame=@{func="main",args=[],file="recursive2.c",line="5"@}
 977 (@value{GDBP})
 978 @end smallexample
 979
 980 Setting a watchpoint on a variable local to a function.  @value{GDBN} will stop
 981 the program execution twice: first for the variable changing value, then
 982 for the watchpoint going out of scope.
 983
 984 @smallexample
 985 (@value{GDBP})
 986 -break-watch C
 987 ^done,wpt=@{number="5",exp="C"@}
 988 (@value{GDBP})
 989 -exec-continue
 990 ^running
 991 ^done,reason="watchpoint-trigger",
 992 wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
 993 frame=@{func="callee4",args=[],
 994 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
 995 (@value{GDBP})
 996 -exec-continue
 997 ^running
 998 ^done,reason="watchpoint-scope",wpnum="5",
 999 frame=@{func="callee3",args=[@{name="strarg",
1000 value="0x11940 \"A string argument.\""@}],
1001 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1002 (@value{GDBP})
1003 @end smallexample
1004
1005 Listing breakpoints and watchpoints, at different points in the program
1006 execution.  Note that once the watchpoint goes out of scope, it is
1007 deleted.
1008
1009 @smallexample
1010 (@value{GDBP})
1011 -break-watch C
1012 ^done,wpt=@{number="2",exp="C"@}
1013 (@value{GDBP})
1014 -break-list
1015 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
1016 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
1017 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
1018 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
1019 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
1020 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
1021 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
1022 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
1023 addr="0x00010734",func="callee4",
1024 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
1025 bkpt=@{number="2",type="watchpoint",disp="keep",
1026 enabled="y",addr="",what="C",times="0"@}]@}
1027 (@value{GDBP})
1028 -exec-continue
1029 ^running
1030 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
1031 value=@{old="-276895068",new="3"@},
1032 frame=@{func="callee4",args=[],
1033 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
1034 (@value{GDBP})
1035 -break-list
1036 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
1037 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
1038 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
1039 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
1040 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
1041 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
1042 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
1043 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
1044 addr="0x00010734",func="callee4",
1045 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
1046 bkpt=@{number="2",type="watchpoint",disp="keep",
1047 enabled="y",addr="",what="C",times="-5"@}]@}
1048 (@value{GDBP})
1049 -exec-continue
1050 ^running
1051 ^done,reason="watchpoint-scope",wpnum="2",
1052 frame=@{func="callee3",args=[@{name="strarg",
1053 value="0x11940 \"A string argument.\""@}],
1054 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1055 (@value{GDBP})
1056 -break-list
1057 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
1058 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
1059 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
1060 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
1061 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
1062 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
1063 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
1064 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
1065 addr="0x00010734",func="callee4",
1066 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}]@}
1067 (@value{GDBP})
1068 @end smallexample
1069
1070 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1071 @node GDB/MI Data Manipulation
1072 @section @sc{gdb/mi} Data Manipulation
1073
1074 @cindex data manipulation, in @sc{gdb/mi}
1075 @cindex @sc{gdb/mi}, data manipulation
1076 This section describes the @sc{gdb/mi} commands that manipulate data:
1077 examine memory and registers, evaluate expressions, etc.
1078
1079 @c REMOVED FROM THE INTERFACE.
1080 @c @subheading -data-assign
1081 @c Change the value of a program variable. Plenty of side effects.
1082 @c @subsubheading GDB command
1083 @c set variable
1084 @c @subsubheading Example
1085 @c N.A.
1086
1087 @subheading The @code{-data-disassemble} Command
1088 @findex -data-disassemble
1089
1090 @subsubheading Synopsis
1091
1092 @example
1093  -data-disassemble
1094     [ -s @var{start-addr} -e @var{end-addr} ]
1095   | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
1096   -- @var{mode}
1097 @end example
1098
1099 @noindent
1100 Where:
1101
1102 @table @samp
1103 @item @var{start-addr}
1104 is the beginning address (or @code{$pc})
1105 @item @var{end-addr}
1106 is the end address
1107 @item @var{filename}
1108 is the name of the file to disassemble
1109 @item @var{linenum}
1110 is the line number to disassemble around
1111 @item @var{lines}
1112 is the the number of disassembly lines to be produced.  If it is -1,
1113 the whole function will be disassembled, in case no @var{end-addr} is
1114 specified.  If @var{end-addr} is specified as a non-zero value, and
1115 @var{lines} is lower than the number of disassembly lines between
1116 @var{start-addr} and @var{end-addr}, only @var{lines} lines are
1117 displayed; if @var{lines} is higher than the number of lines between
1118 @var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
1119 are displayed.
1120 @item @var{mode}
1121 is either 0 (meaning only disassembly) or 1 (meaning mixed source and
1122 disassembly).
1123 @end table
1124
1125 @subsubheading Result
1126
1127 The output for each instruction is composed of four fields:
1128
1129 @itemize @bullet
1130 @item Address
1131 @item Func-name
1132 @item Offset
1133 @item Instruction
1134 @end itemize
1135
1136 Note that whatever included in the instruction field, is not manipulated
1137 directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format.
1138
1139 @subsubheading @value{GDBN} Command
1140
1141 There's no direct mapping from this command to the CLI.
1142
1143 @subsubheading Example
1144
1145 Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
1146
1147 @smallexample
1148 (@value{GDBP})
1149 -data-disassemble -s $pc -e "$pc + 20" -- 0
1150 ^done,
1151 asm_insns=[
1152 @{address="0x000107c0",func-name="main",offset="4",
1153 inst="mov  2, %o0"@},
1154 @{address="0x000107c4",func-name="main",offset="8",
1155 inst="sethi  %hi(0x11800), %o2"@},
1156 @{address="0x000107c8",func-name="main",offset="12",
1157 inst="or  %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
1158 @{address="0x000107cc",func-name="main",offset="16",
1159 inst="sethi  %hi(0x11800), %o2"@},
1160 @{address="0x000107d0",func-name="main",offset="20",
1161 inst="or  %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
1162 (@value{GDBP})
1163 @end smallexample
1164
1165 Disassemble the whole @code{main} function.  Line 32 is part of
1166 @code{main}.
1167
1168 @smallexample
1169 -data-disassemble -f basics.c -l 32 -- 0
1170 ^done,asm_insns=[
1171 @{address="0x000107bc",func-name="main",offset="0",
1172 inst="save  %sp, -112, %sp"@},
1173 @{address="0x000107c0",func-name="main",offset="4",
1174 inst="mov   2, %o0"@},
1175 @{address="0x000107c4",func-name="main",offset="8",
1176 inst="sethi %hi(0x11800), %o2"@},
1177 [@dots{}]
1178 @{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
1179 @{address="0x00010820",func-name="main",offset="100",inst="restore "@}]
1180 (@value{GDBP})
1181 @end smallexample
1182
1183 Disassemble 3 instructions from the start of @code{main}:
1184
1185 @smallexample
1186 (@value{GDBP})
1187 -data-disassemble -f basics.c -l 32 -n 3 -- 0
1188 ^done,asm_insns=[
1189 @{address="0x000107bc",func-name="main",offset="0",
1190 inst="save  %sp, -112, %sp"@},
1191 @{address="0x000107c0",func-name="main",offset="4",
1192 inst="mov  2, %o0"@},
1193 @{address="0x000107c4",func-name="main",offset="8",
1194 inst="sethi  %hi(0x11800), %o2"@}]
1195 (@value{GDBP})
1196 @end smallexample
1197
1198 Disassemble 3 instructions from the start of @code{main} in mixed mode:
1199
1200 @smallexample
1201 (@value{GDBP})
1202 -data-disassemble -f basics.c -l 32 -n 3 -- 1
1203 ^done,asm_insns=[
1204 src_and_asm_line=@{line="31",
1205 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1206   testsuite/gdb.mi/basics.c",line_asm_insn=[
1207 @{address="0x000107bc",func-name="main",offset="0",
1208 inst="save  %sp, -112, %sp"@}]@},
1209 src_and_asm_line=@{line="32",
1210 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1211   testsuite/gdb.mi/basics.c",line_asm_insn=[
1212 @{address="0x000107c0",func-name="main",offset="4",
1213 inst="mov  2, %o0"@},
1214 @{address="0x000107c4",func-name="main",offset="8",
1215 inst="sethi  %hi(0x11800), %o2"@}]@}]
1216 (@value{GDBP})
1217 @end smallexample
1218
1219
1220 @subheading The @code{-data-evaluate-expression} Command
1221 @findex -data-evaluate-expression
1222
1223 @subsubheading Synopsis
1224
1225 @example
1226  -data-evaluate-expression @var{expr}
1227 @end example
1228
1229 Evaluate @var{expr} as an expression.  The expression could contain an
1230 inferior function call.  The function call will execute synchronously.
1231 If the expression contains spaces, it must be enclosed in double quotes.
1232
1233 @subsubheading @value{GDBN} Command
1234
1235 The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
1236 @samp{call}.  In @code{gdbtk} only, there's a corresponding
1237 @samp{gdb_eval} command.
1238
1239 @subsubheading Example
1240
1241 In the following example, the numbers that precede the commands are the
1242 @dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
1243 Command Syntax}.  Notice how @sc{gdb/mi} returns the same tokens in its
1244 output.
1245
1246 @smallexample
1247 211-data-evaluate-expression A
1248 211^done,value="1"
1249 (@value{GDBP})
1250 311-data-evaluate-expression &A
1251 311^done,value="0xefffeb7c"
1252 (@value{GDBP})
1253 411-data-evaluate-expression A+3
1254 411^done,value="4"
1255 (@value{GDBP})
1256 511-data-evaluate-expression "A + 3"
1257 511^done,value="4"
1258 (@value{GDBP})
1259 @end smallexample
1260
1261
1262 @subheading The @code{-data-list-changed-registers} Command
1263 @findex -data-list-changed-registers
1264
1265 @subsubheading Synopsis
1266
1267 @example
1268  -data-list-changed-registers
1269 @end example
1270
1271 Display a list of the registers that have changed.
1272
1273 @subsubheading @value{GDBN} Command
1274
1275 @value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
1276 has the corresponding command @samp{gdb_changed_register_list}.
1277
1278 @subsubheading Example
1279
1280 On a PPC MBX board:
1281
1282 @smallexample
1283 (@value{GDBP})
1284 -exec-continue
1285 ^running
1286
1287 (@value{GDBP})
1288 *stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
1289 args=[],file="try.c",line="5"@}
1290 (@value{GDBP})
1291 -data-list-changed-registers
1292 ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
1293 "10","11","13","14","15","16","17","18","19","20","21","22","23",
1294 "24","25","26","27","28","30","31","64","65","66","67","69"]
1295 (@value{GDBP})
1296 @end smallexample
1297
1298
1299 @subheading The @code{-data-list-register-names} Command
1300 @findex -data-list-register-names
1301
1302 @subsubheading Synopsis
1303
1304 @example
1305  -data-list-register-names [ ( @var{regno} )+ ]
1306 @end example
1307
1308 Show a list of register names for the current target.  If no arguments
1309 are given, it shows a list of the names of all the registers.  If
1310 integer numbers are given as arguments, it will print a list of the
1311 names of the registers corresponding to the arguments.  To ensure
1312 consistency between a register name and its number, the output list may
1313 include empty register names.
1314
1315 @subsubheading @value{GDBN} Command
1316
1317 @value{GDBN} does not have a command which corresponds to
1318 @samp{-data-list-register-names}.  In @code{gdbtk} there is a
1319 corresponding command @samp{gdb_regnames}.
1320
1321 @subsubheading Example
1322
1323 For the PPC MBX board:
1324 @smallexample
1325 (@value{GDBP})
1326 -data-list-register-names
1327 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
1328 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
1329 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
1330 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
1331 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
1332 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
1333 "", "pc","ps","cr","lr","ctr","xer"]
1334 (@value{GDBP})
1335 -data-list-register-names 1 2 3
1336 ^done,register-names=["r1","r2","r3"]
1337 (@value{GDBP})
1338 @end smallexample
1339
1340 @subheading The @code{-data-list-register-values} Command
1341 @findex -data-list-register-values
1342
1343 @subsubheading Synopsis
1344
1345 @example
1346  -data-list-register-values @var{fmt} [ ( @var{regno} )*]
1347 @end example
1348
1349 Display the registers' contents.  @var{fmt} is the format according to
1350 which the registers' contents are to be returned, followed by an optional
1351 list of numbers specifying the registers to display.  A missing list of
1352 numbers indicates that the contents of all the registers must be returned.
1353
1354 Allowed formats for @var{fmt} are:
1355
1356 @table @code
1357 @item x
1358 Hexadecimal
1359 @item o
1360 Octal
1361 @item t
1362 Binary
1363 @item d
1364 Decimal
1365 @item r
1366 Raw
1367 @item N
1368 Natural
1369 @end table
1370
1371 @subsubheading @value{GDBN} Command
1372
1373 The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
1374 all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
1375
1376 @subsubheading Example
1377
1378 For a PPC MBX board (note: line breaks are for readability only, they
1379 don't appear in the actual output):
1380
1381 @smallexample
1382 (@value{GDBP})
1383 -data-list-register-values r 64 65
1384 ^done,register-values=[@{number="64",value="0xfe00a300"@},
1385 @{number="65",value="0x00029002"@}]
1386 (@value{GDBP})
1387 -data-list-register-values x
1388 ^done,register-values=[@{number="0",value="0xfe0043c8"@},
1389 @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
1390 @{number="3",value="0x0"@},@{number="4",value="0xa"@},
1391 @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
1392 @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
1393 @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
1394 @{number="11",value="0x1"@},@{number="12",value="0x0"@},
1395 @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
1396 @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
1397 @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
1398 @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
1399 @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
1400 @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
1401 @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
1402 @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
1403 @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
1404 @{number="31",value="0x0"@},@{number="32",value="0x0"@},
1405 @{number="33",value="0x0"@},@{number="34",value="0x0"@},
1406 @{number="35",value="0x0"@},@{number="36",value="0x0"@},
1407 @{number="37",value="0x0"@},@{number="38",value="0x0"@},
1408 @{number="39",value="0x0"@},@{number="40",value="0x0"@},
1409 @{number="41",value="0x0"@},@{number="42",value="0x0"@},
1410 @{number="43",value="0x0"@},@{number="44",value="0x0"@},
1411 @{number="45",value="0x0"@},@{number="46",value="0x0"@},
1412 @{number="47",value="0x0"@},@{number="48",value="0x0"@},
1413 @{number="49",value="0x0"@},@{number="50",value="0x0"@},
1414 @{number="51",value="0x0"@},@{number="52",value="0x0"@},
1415 @{number="53",value="0x0"@},@{number="54",value="0x0"@},
1416 @{number="55",value="0x0"@},@{number="56",value="0x0"@},
1417 @{number="57",value="0x0"@},@{number="58",value="0x0"@},
1418 @{number="59",value="0x0"@},@{number="60",value="0x0"@},
1419 @{number="61",value="0x0"@},@{number="62",value="0x0"@},
1420 @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
1421 @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
1422 @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
1423 @{number="69",value="0x20002b03"@}]
1424 (@value{GDBP})
1425 @end smallexample
1426
1427
1428 @subheading The @code{-data-read-memory} Command
1429 @findex -data-read-memory
1430
1431 @subsubheading Synopsis
1432
1433 @example
1434  -data-read-memory [ -o @var{byte-offset} ]
1435    @var{address} @var{word-format} @var{word-size}
1436    @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
1437 @end example
1438
1439 @noindent
1440 where:
1441
1442 @table @samp
1443 @item @var{address}
1444 An expression specifying the address of the first memory word to be
1445 read.  Complex expressions containing embedded white space should be
1446 quoted using the C convention.
1447
1448 @item @var{word-format}
1449 The format to be used to print the memory words.  The notation is the
1450 same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
1451 ,Output formats}).
1452
1453 @item @var{word-size}
1454 The size of each memory word in bytes.
1455
1456 @item @var{nr-rows}
1457 The number of rows in the output table.
1458
1459 @item @var{nr-cols}
1460 The number of columns in the output table.
1461
1462 @item @var{aschar}
1463 If present, indicates that each row should include an @sc{ascii} dump.  The
1464 value of @var{aschar} is used as a padding character when a byte is not a
1465 member of the printable @sc{ascii} character set (printable @sc{ascii}
1466 characters are those whose code is between 32 and 126, inclusively).
1467
1468 @item @var{byte-offset}
1469 An offset to add to the @var{address} before fetching memory.
1470 @end table
1471
1472 This command displays memory contents as a table of @var{nr-rows} by
1473 @var{nr-cols} words, each word being @var{word-size} bytes.  In total,
1474 @code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
1475 (returned as @samp{total-bytes}).  Should less than the requested number
1476 of bytes be returned by the target, the missing words are identified
1477 using @samp{N/A}.  The number of bytes read from the target is returned
1478 in @samp{nr-bytes} and the starting address used to read memory in
1479 @samp{addr}.
1480
1481 The address of the next/previous row or page is available in
1482 @samp{next-row} and @samp{prev-row}, @samp{next-page} and
1483 @samp{prev-page}.
1484
1485 @subsubheading @value{GDBN} Command
1486
1487 The corresponding @value{GDBN} command is @samp{x}.  @code{gdbtk} has
1488 @samp{gdb_get_mem} memory read command.
1489
1490 @subsubheading Example
1491
1492 Read six bytes of memory starting at @code{bytes+6} but then offset by
1493 @code{-6} bytes.  Format as three rows of two columns.  One byte per
1494 word.  Display each word in hex.
1495
1496 @smallexample
1497 (@value{GDBP})
1498 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
1499 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
1500 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
1501 prev-page="0x0000138a",memory=[
1502 @{addr="0x00001390",data=["0x00","0x01"]@},
1503 @{addr="0x00001392",data=["0x02","0x03"]@},
1504 @{addr="0x00001394",data=["0x04","0x05"]@}]
1505 (@value{GDBP})
1506 @end smallexample
1507
1508 Read two bytes of memory starting at address @code{shorts + 64} and
1509 display as a single word formatted in decimal.
1510
1511 @smallexample
1512 (@value{GDBP})
1513 5-data-read-memory shorts+64 d 2 1 1
1514 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
1515 next-row="0x00001512",prev-row="0x0000150e",
1516 next-page="0x00001512",prev-page="0x0000150e",memory=[
1517 @{addr="0x00001510",data=["128"]@}]
1518 (@value{GDBP})
1519 @end smallexample
1520
1521 Read thirty two bytes of memory starting at @code{bytes+16} and format
1522 as eight rows of four columns.  Include a string encoding with @samp{x}
1523 used as the non-printable character.
1524
1525 @smallexample
1526 (@value{GDBP})
1527 4-data-read-memory bytes+16 x 1 8 4 x
1528 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
1529 next-row="0x000013c0",prev-row="0x0000139c",
1530 next-page="0x000013c0",prev-page="0x00001380",memory=[
1531 @{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@},
1532 @{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@},
1533 @{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@},
1534 @{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@},
1535 @{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@},
1536 @{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@},
1537 @{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@},
1538 @{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}]
1539 (@value{GDBP})
1540 @end smallexample
1541
1542 @subheading The @code{-display-delete} Command
1543 @findex -display-delete
1544
1545 @subsubheading Synopsis
1546
1547 @example
1548  -display-delete @var{number}
1549 @end example
1550
1551 Delete the display @var{number}.
1552
1553 @subsubheading @value{GDBN} Command
1554
1555 The corresponding @value{GDBN} command is @samp{delete display}.
1556
1557 @subsubheading Example
1558 N.A.
1559
1560
1561 @subheading The @code{-display-disable} Command
1562 @findex -display-disable
1563
1564 @subsubheading Synopsis
1565
1566 @example
1567  -display-disable @var{number}
1568 @end example
1569
1570 Disable display @var{number}.
1571
1572 @subsubheading @value{GDBN} Command
1573
1574 The corresponding @value{GDBN} command is @samp{disable display}.
1575
1576 @subsubheading Example
1577 N.A.
1578
1579
1580 @subheading The @code{-display-enable} Command
1581 @findex -display-enable
1582
1583 @subsubheading Synopsis
1584
1585 @example
1586  -display-enable @var{number}
1587 @end example
1588
1589 Enable display @var{number}.
1590
1591 @subsubheading @value{GDBN} Command
1592
1593 The corresponding @value{GDBN} command is @samp{enable display}.
1594
1595 @subsubheading Example
1596 N.A.
1597
1598
1599 @subheading The @code{-display-insert} Command
1600 @findex -display-insert
1601
1602 @subsubheading Synopsis
1603
1604 @example
1605  -display-insert @var{expression}
1606 @end example
1607
1608 Display @var{expression} every time the program stops.
1609
1610 @subsubheading @value{GDBN} Command
1611
1612 The corresponding @value{GDBN} command is @samp{display}.
1613
1614 @subsubheading Example
1615 N.A.
1616
1617
1618 @subheading The @code{-display-list} Command
1619 @findex -display-list
1620
1621 @subsubheading Synopsis
1622
1623 @example
1624  -display-list
1625 @end example
1626
1627 List the displays.  Do not show the current values.
1628
1629 @subsubheading @value{GDBN} Command
1630
1631 The corresponding @value{GDBN} command is @samp{info display}.
1632
1633 @subsubheading Example
1634 N.A.
1635
1636
1637 @subheading The @code{-environment-cd} Command
1638 @findex -environment-cd
1639
1640 @subsubheading Synopsis
1641
1642 @example
1643  -environment-cd @var{pathdir}
1644 @end example
1645
1646 Set @value{GDBN}'s working directory.
1647
1648 @subsubheading @value{GDBN} Command
1649
1650 The corresponding @value{GDBN} command is @samp{cd}.
1651
1652 @subsubheading Example
1653
1654 @smallexample
1655 (@value{GDBP})
1656 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1657 ^done
1658 (@value{GDBP})
1659 @end smallexample
1660
1661
1662 @subheading The @code{-environment-directory} Command
1663 @findex -environment-directory
1664
1665 @subsubheading Synopsis
1666
1667 @example
1668  -environment-directory @var{pathdir}
1669 @end example
1670
1671 Add directory @var{pathdir} to beginning of search path for source files.
1672
1673 @subsubheading @value{GDBN} Command
1674
1675 The corresponding @value{GDBN} command is @samp{dir}.
1676
1677 @subsubheading Example
1678
1679 @smallexample
1680 (@value{GDBP})
1681 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1682 ^done
1683 (@value{GDBP})
1684 @end smallexample
1685
1686
1687 @subheading The @code{-environment-path} Command
1688 @findex -environment-path
1689
1690 @subsubheading Synopsis
1691
1692 @example
1693  -environment-path ( @var{pathdir} )+
1694 @end example
1695
1696 Add directories @var{pathdir} to beginning of search path for object files.
1697
1698 @subsubheading @value{GDBN} Command
1699
1700 The corresponding @value{GDBN} command is @samp{path}.
1701
1702 @subsubheading Example
1703
1704 @smallexample
1705 (@value{GDBP})
1706 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
1707 ^done
1708 (@value{GDBP})
1709 @end smallexample
1710
1711
1712 @subheading The @code{-environment-pwd} Command
1713 @findex -environment-pwd
1714
1715 @subsubheading Synopsis
1716
1717 @example
1718  -environment-pwd
1719 @end example
1720
1721 Show the current working directory.
1722
1723 @subsubheading @value{GDBN} command
1724
1725 The corresponding @value{GDBN} command is @samp{pwd}.
1726
1727 @subsubheading Example
1728
1729 @smallexample
1730 (@value{GDBP})
1731 -environment-pwd
1732 ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
1733 ^done
1734 (@value{GDBP})
1735 @end smallexample
1736
1737 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1738 @node GDB/MI Program Control
1739 @section @sc{gdb/mi} Program control
1740
1741 @subsubheading Program termination
1742
1743 As a result of execution, the inferior program can run to completion, if
1744 it doesn't encounter any breakpoints.  In this case the output will
1745 include an exit code, if the program has exited exceptionally.
1746
1747 @subsubheading Examples
1748
1749 @noindent
1750 Program exited normally:
1751
1752 @smallexample
1753 (@value{GDBP})
1754 -exec-run
1755 ^running
1756 (@value{GDBP})
1757 x = 55
1758 *stopped,reason="exited-normally"
1759 (@value{GDBP})
1760 @end smallexample
1761
1762 @noindent
1763 Program exited exceptionally:
1764
1765 @smallexample
1766 (@value{GDBP})
1767 -exec-run
1768 ^running
1769 (@value{GDBP})
1770 x = 55
1771 *stopped,reason="exited",exit-code="01"
1772 (@value{GDBP})
1773 @end smallexample
1774
1775 Another way the program can terminate is if it receives a signal such as
1776 @code{SIGINT}.  In this case, @sc{gdb/mi} displays this:
1777
1778 @smallexample
1779 (@value{GDBP})
1780 *stopped,reason="exited-signalled",signal-name="SIGINT",
1781 signal-meaning="Interrupt"
1782 @end smallexample
1783
1784
1785 @subheading The @code{-exec-abort} Command
1786 @findex -exec-abort
1787
1788 @subsubheading Synopsis
1789
1790 @example
1791  -exec-abort
1792 @end example
1793
1794 Kill the inferior running program.
1795
1796 @subsubheading @value{GDBN} Command
1797
1798 The corresponding @value{GDBN} command is @samp{kill}.
1799
1800 @subsubheading Example
1801 N.A.
1802
1803
1804 @subheading The @code{-exec-arguments} Command
1805 @findex -exec-arguments
1806
1807 @subsubheading Synopsis
1808
1809 @example
1810  -exec-arguments @var{args}
1811 @end example
1812
1813 Set the inferior program arguments, to be used in the next
1814 @samp{-exec-run}.
1815
1816 @subsubheading @value{GDBN} Command
1817
1818 The corresponding @value{GDBN} command is @samp{set args}.
1819
1820 @subsubheading Example
1821
1822 @c FIXME!
1823 Don't have one around.
1824
1825
1826 @subheading The @code{-exec-continue} Command
1827 @findex -exec-continue
1828
1829 @subsubheading Synopsis
1830
1831 @example
1832  -exec-continue
1833 @end example
1834
1835 Asynchronous command.  Resumes the execution of the inferior program
1836 until a breakpoint is encountered, or until the inferior exits.
1837
1838 @subsubheading @value{GDBN} Command
1839
1840 The corresponding @value{GDBN} corresponding is @samp{continue}.
1841
1842 @subsubheading Example
1843
1844 @smallexample
1845 -exec-continue
1846 ^running
1847 (@value{GDBP})
1848 @@Hello world
1849 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
1850 file="hello.c",line="13"@}
1851 (@value{GDBP})
1852 @end smallexample
1853
1854
1855 @subheading The @code{-exec-finish} Command
1856 @findex -exec-finish
1857
1858 @subsubheading Synopsis
1859
1860 @example
1861  -exec-finish
1862 @end example
1863
1864 Asynchronous command.  Resumes the execution of the inferior program
1865 until the current function is exited.  Displays the results returned by
1866 the function.
1867
1868 @subsubheading @value{GDBN} Command
1869
1870 The corresponding @value{GDBN} command is @samp{finish}.
1871
1872 @subsubheading Example
1873
1874 Function returning @code{void}.
1875
1876 @smallexample
1877 -exec-finish
1878 ^running
1879 (@value{GDBP})
1880 @@hello from foo
1881 *stopped,reason="function-finished",frame=@{func="main",args=[],
1882 file="hello.c",line="7"@}
1883 (@value{GDBP})
1884 @end smallexample
1885
1886 Function returning other than @code{void}.  The name of the internal
1887 @value{GDBN} variable storing the result is printed, together with the
1888 value itself.
1889
1890 @smallexample
1891 -exec-finish
1892 ^running
1893 (@value{GDBP})
1894 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
1895 args=[@{name="a",value="1"],@{name="b",value="9"@}@},
1896 file="recursive2.c",line="14"@},
1897 gdb-result-var="$1",return-value="0"
1898 (@value{GDBP})
1899 @end smallexample
1900
1901
1902 @subheading The @code{-exec-interrupt} Command
1903 @findex -exec-interrupt
1904
1905 @subsubheading Synopsis
1906
1907 @example
1908  -exec-interrupt
1909 @end example
1910
1911 Asynchronous command.  Interrupts the background execution of the target.
1912 Note how the token associated with the stop message is the one for the
1913 execution command that has been interrupted.  The token for the interrupt
1914 itself only appears in the @samp{^done} output.  If the user is trying to
1915 interrupt a non-running program, an error message will be printed.
1916
1917 @subsubheading @value{GDBN} Command
1918
1919 The corresponding @value{GDBN} command is @samp{interrupt}.
1920
1921 @subsubheading Example
1922
1923 @smallexample
1924 (@value{GDBP})
1925 111-exec-continue
1926 111^running
1927
1928 (@value{GDBP})
1929 222-exec-interrupt
1930 222^done
1931 (@value{GDBP})
1932 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1933 frame=@{addr="0x00010140",func="foo",args=[],file="try.c",line="13"@}
1934 (@value{GDBP})
1935
1936 (@value{GDBP})
1937 -exec-interrupt
1938 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1939 (@value{GDBP})
1940 @end smallexample
1941
1942
1943 @subheading The @code{-exec-next} Command
1944 @findex -exec-next
1945
1946 @subsubheading Synopsis
1947
1948 @example
1949  -exec-next
1950 @end example
1951
1952 Asynchronous command.  Resumes execution of the inferior program, stopping
1953 when the beginning of the next source line is reached.
1954
1955 @subsubheading @value{GDBN} Command
1956
1957 The corresponding @value{GDBN} command is @samp{next}.
1958
1959 @subsubheading Example
1960
1961 @smallexample
1962 -exec-next
1963 ^running
1964 (@value{GDBP})
1965 *stopped,reason="end-stepping-range",line="8",file="hello.c"
1966 (@value{GDBP})
1967 @end smallexample
1968
1969
1970 @subheading The @code{-exec-next-instruction} Command
1971 @findex -exec-next-instruction
1972
1973 @subsubheading Synopsis
1974
1975 @example
1976  -exec-next-instruction
1977 @end example
1978
1979 Asynchronous command.  Executes one machine instruction.  If the
1980 instruction is a function call continues until the function returns.  If
1981 the program stops at an instruction in the middle of a source line, the
1982 address will be printed as well.
1983
1984 @subsubheading @value{GDBN} Command
1985
1986 The corresponding @value{GDBN} command is @samp{nexti}.
1987
1988 @subsubheading Example
1989
1990 @smallexample
1991 (@value{GDBP})
1992 -exec-next-instruction
1993 ^running
1994
1995 (@value{GDBP})
1996 *stopped,reason="end-stepping-range",
1997 addr="0x000100d4",line="5",file="hello.c"
1998 (@value{GDBP})
1999 @end smallexample
2000
2001
2002 @subheading The @code{-exec-return} Command
2003 @findex -exec-return
2004
2005 @subsubheading Synopsis
2006
2007 @example
2008  -exec-return
2009 @end example
2010
2011 Makes current function return immediately.  Doesn't execute the inferior.
2012 Displays the new current frame.
2013
2014 @subsubheading @value{GDBN} Command
2015
2016 The corresponding @value{GDBN} command is @samp{return}.
2017
2018 @subsubheading Example
2019
2020 @smallexample
2021 (@value{GDBP})
2022 200-break-insert callee4
2023 200^done,bkpt=@{number="1",addr="0x00010734",
2024 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
2025 (@value{GDBP})
2026 000-exec-run
2027 000^running
2028 (@value{GDBP})
2029 000*stopped,reason="breakpoint-hit",bkptno="1",
2030 frame=@{func="callee4",args=[],
2031 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
2032 (@value{GDBP})
2033 205-break-delete
2034 205^done
2035 (@value{GDBP})
2036 111-exec-return
2037 111^done,frame=@{level="0 ",func="callee3",
2038 args=[@{name="strarg",
2039 value="0x11940 \"A string argument.\""@}],
2040 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
2041 (@value{GDBP})
2042 @end smallexample
2043
2044
2045 @subheading The @code{-exec-run} Command
2046 @findex -exec-run
2047
2048 @subsubheading Synopsis
2049
2050 @example
2051  -exec-run
2052 @end example
2053
2054 Asynchronous command.  Starts execution of the inferior from the
2055 beginning.  The inferior executes until either a breakpoint is
2056 encountered or the program exits.
2057
2058 @subsubheading @value{GDBN} Command
2059
2060 The corresponding @value{GDBN} command is @samp{run}.
2061
2062 @subsubheading Example
2063
2064 @smallexample
2065 (@value{GDBP})
2066 -break-insert main
2067 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
2068 (@value{GDBP})
2069 -exec-run
2070 ^running
2071 (@value{GDBP})
2072 *stopped,reason="breakpoint-hit",bkptno="1",
2073 frame=@{func="main",args=[],file="recursive2.c",line="4"@}
2074 (@value{GDBP})
2075 @end smallexample
2076
2077
2078 @subheading The @code{-exec-show-arguments} Command
2079 @findex -exec-show-arguments
2080
2081 @subsubheading Synopsis
2082
2083 @example
2084  -exec-show-arguments
2085 @end example
2086
2087 Print the arguments of the program.
2088
2089 @subsubheading @value{GDBN} Command
2090
2091 The corresponding @value{GDBN} command is @samp{show args}.
2092
2093 @subsubheading Example
2094 N.A.
2095
2096 @c @subheading -exec-signal
2097
2098 @subheading The @code{-exec-step} Command
2099 @findex -exec-step
2100
2101 @subsubheading Synopsis
2102
2103 @example
2104  -exec-step
2105 @end example
2106
2107 Asynchronous command.  Resumes execution of the inferior program, stopping
2108 when the beginning of the next source line is reached, if the next
2109 source line is not a function call.  If it is, stop at the first
2110 instruction of the called function.
2111
2112 @subsubheading @value{GDBN} Command
2113
2114 The corresponding @value{GDBN} command is @samp{step}.
2115
2116 @subsubheading Example
2117
2118 Stepping into a function:
2119
2120 @smallexample
2121 -exec-step
2122 ^running
2123 (@value{GDBP})
2124 *stopped,reason="end-stepping-range",
2125 frame=@{func="foo",args=[@{name="a",value="10"@},
2126 @{name="b",value="0"@}],file="recursive2.c",line="11"@}
2127 (@value{GDBP})
2128 @end smallexample
2129
2130 Regular stepping:
2131
2132 @smallexample
2133 -exec-step
2134 ^running
2135 (@value{GDBP})
2136 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
2137 (@value{GDBP})
2138 @end smallexample
2139
2140
2141 @subheading The @code{-exec-step-instruction} Command
2142 @findex -exec-step-instruction
2143
2144 @subsubheading Synopsis
2145
2146 @example
2147  -exec-step-instruction
2148 @end example
2149
2150 Asynchronous command.  Resumes the inferior which executes one machine
2151 instruction.  The output, once @value{GDBN} has stopped, will vary depending on
2152 whether we have stopped in the middle of a source line or not.  In the
2153 former case, the address at which the program stopped will be printed as
2154 well.
2155
2156 @subsubheading @value{GDBN} Command
2157
2158 The corresponding @value{GDBN} command is @samp{stepi}.
2159
2160 @subsubheading Example
2161
2162 @smallexample
2163 (@value{GDBP})
2164 -exec-step-instruction
2165 ^running
2166
2167 (@value{GDBP})
2168 *stopped,reason="end-stepping-range",
2169 frame=@{func="foo",args=[],file="try.c",line="10"@}
2170 (@value{GDBP})
2171 -exec-step-instruction
2172 ^running
2173
2174 (@value{GDBP})
2175 *stopped,reason="end-stepping-range",
2176 frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@}
2177 (@value{GDBP})
2178 @end smallexample
2179
2180
2181 @subheading The @code{-exec-until} Command
2182 @findex -exec-until
2183
2184 @subsubheading Synopsis
2185
2186 @example
2187  -exec-until [ @var{location} ]
2188 @end example
2189
2190 Asynchronous command.  Executes the inferior until the @var{location}
2191 specified in the argument is reached.  If there is no argument, the inferior
2192 executes until a source line greater than the current one is reached.
2193 The reason for stopping in this case will be @samp{location-reached}.
2194
2195 @subsubheading @value{GDBN} Command
2196
2197 The corresponding @value{GDBN} command is @samp{until}.
2198
2199 @subsubheading Example
2200
2201 @smallexample
2202 (@value{GDBP})
2203 -exec-until recursive2.c:6
2204 ^running
2205 (@value{GDBP})
2206 x = 55
2207 *stopped,reason="location-reached",frame=@{func="main",args=[],
2208 file="recursive2.c",line="6"@}
2209 (@value{GDBP})
2210 @end smallexample
2211
2212 @ignore
2213 @subheading -file-clear
2214 Is this going away????
2215 @end ignore
2216
2217
2218 @subheading The @code{-file-exec-and-symbols} Command
2219 @findex -file-exec-and-symbols
2220
2221 @subsubheading Synopsis
2222
2223 @example
2224  -file-exec-and-symbols @var{file}
2225 @end example
2226
2227 Specify the executable file to be debugged.  This file is the one from
2228 which the symbol table is also read.  If no file is specified, the
2229 command clears the executable and symbol information.  If breakpoints
2230 are set when using this command with no arguments, @value{GDBN} will produce
2231 error messages.  Otherwise, no output is produced, except a completion
2232 notification.
2233
2234 @subsubheading @value{GDBN} Command
2235
2236 The corresponding @value{GDBN} command is @samp{file}.
2237
2238 @subsubheading Example
2239
2240 @smallexample
2241 (@value{GDBP})
2242 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2243 ^done
2244 (@value{GDBP})
2245 @end smallexample
2246
2247
2248 @subheading The @code{-file-exec-file} Command
2249 @findex -file-exec-file
2250
2251 @subsubheading Synopsis
2252
2253 @example
2254  -file-exec-file @var{file}
2255 @end example
2256
2257 Specify the executable file to be debugged.  Unlike
2258 @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
2259 from this file.  If used without argument, @value{GDBN} clears the information
2260 about the executable file.  No output is produced, except a completion
2261 notification.
2262
2263 @subsubheading @value{GDBN} Command
2264
2265 The corresponding @value{GDBN} command is @samp{exec-file}.
2266
2267 @subsubheading Example
2268
2269 @smallexample
2270 (@value{GDBP})
2271 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2272 ^done
2273 (@value{GDBP})
2274 @end smallexample
2275
2276
2277 @subheading The @code{-file-list-exec-sections} Command
2278 @findex -file-list-exec-sections
2279
2280 @subsubheading Synopsis
2281
2282 @example
2283  -file-list-exec-sections
2284 @end example
2285
2286 List the sections of the current executable file.
2287
2288 @subsubheading @value{GDBN} Command
2289
2290 The @value{GDBN} command @samp{info file} shows, among the rest, the same
2291 information as this command.  @code{gdbtk} has a corresponding command
2292 @samp{gdb_load_info}.
2293
2294 @subsubheading Example
2295 N.A.
2296
2297
2298 @subheading The @code{-file-list-exec-source-files} Command
2299 @findex -file-list-exec-source-files
2300
2301 @subsubheading Synopsis
2302
2303 @example
2304  -file-list-exec-source-files
2305 @end example
2306
2307 List the source files for the current executable.
2308
2309 @subsubheading @value{GDBN} Command
2310
2311 There's no @value{GDBN} command which directly corresponds to this one.
2312 @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
2313
2314 @subsubheading Example
2315 N.A.
2316
2317
2318 @subheading The @code{-file-list-shared-libraries} Command
2319 @findex -file-list-shared-libraries
2320
2321 @subsubheading Synopsis
2322
2323 @example
2324  -file-list-shared-libraries
2325 @end example
2326
2327 List the shared libraries in the program.
2328
2329 @subsubheading @value{GDBN} Command
2330
2331 The corresponding @value{GDBN} command is @samp{info shared}.
2332
2333 @subsubheading Example
2334 N.A.
2335
2336
2337 @subheading The @code{-file-list-symbol-files} Command
2338 @findex -file-list-symbol-files
2339
2340 @subsubheading Synopsis
2341
2342 @example
2343  -file-list-symbol-files
2344 @end example
2345
2346 List symbol files.
2347
2348 @subsubheading @value{GDBN} Command
2349
2350 The corresponding @value{GDBN} command is @samp{info file} (part of it).
2351
2352 @subsubheading Example
2353 N.A.
2354
2355
2356 @subheading The @code{-file-symbol-file} Command
2357 @findex -file-symbol-file
2358
2359 @subsubheading Synopsis
2360
2361 @example
2362  -file-symbol-file @var{file}
2363 @end example
2364
2365 Read symbol table info from the specified @var{file} argument.  When
2366 used without arguments, clears @value{GDBN}'s symbol table info.  No output is
2367 produced, except for a completion notification.
2368
2369 @subsubheading @value{GDBN} Command
2370
2371 The corresponding @value{GDBN} command is @samp{symbol-file}.
2372
2373 @subsubheading Example
2374
2375 @smallexample
2376 (@value{GDBP})
2377 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2378 ^done
2379 (@value{GDBP})
2380 @end smallexample
2381
2382 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2383 @node GDB/MI Miscellaneous Commands
2384 @section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
2385
2386 @c @subheading -gdb-complete
2387
2388 @subheading The @code{-gdb-exit} Command
2389 @findex -gdb-exit
2390
2391 @subsubheading Synopsis
2392
2393 @example
2394  -gdb-exit
2395 @end example
2396
2397 Exit @value{GDBN} immediately.
2398
2399 @subsubheading @value{GDBN} Command
2400
2401 Approximately corresponds to @samp{quit}.
2402
2403 @subsubheading Example
2404
2405 @smallexample
2406 (@value{GDBP})
2407 -gdb-exit
2408 @end smallexample
2409
2410 @subheading The @code{-gdb-set} Command
2411 @findex -gdb-set
2412
2413 @subsubheading Synopsis
2414
2415 @example
2416  -gdb-set
2417 @end example
2418
2419 Set an internal @value{GDBN} variable.
2420 @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
2421
2422 @subsubheading @value{GDBN} Command
2423
2424 The corresponding @value{GDBN} command is @samp{set}.
2425
2426 @subsubheading Example
2427
2428 @smallexample
2429 (@value{GDBP})
2430 -gdb-set $foo=3
2431 ^done
2432 (@value{GDBP})
2433 @end smallexample
2434
2435
2436 @subheading The @code{-gdb-show} Command
2437 @findex -gdb-show
2438
2439 @subsubheading Synopsis
2440
2441 @example
2442  -gdb-show
2443 @end example
2444
2445 Show the current value of a @value{GDBN} variable.
2446
2447 @subsubheading @value{GDBN} command
2448
2449 The corresponding @value{GDBN} command is @samp{show}.
2450
2451 @subsubheading Example
2452
2453 @smallexample
2454 (@value{GDBP})
2455 -gdb-show annotate
2456 ^done,value="0"
2457 (@value{GDBP})
2458 @end smallexample
2459
2460 @c @subheading -gdb-source
2461
2462
2463 @subheading The @code{-gdb-version} Command
2464 @findex -gdb-version
2465
2466 @subsubheading Synopsis
2467
2468 @example
2469  -gdb-version
2470 @end example
2471
2472 Show version information for @value{GDBN}.  Used mostly in testing.
2473
2474 @subsubheading @value{GDBN} Command
2475
2476 There's no equivalent @value{GDBN} command.  @value{GDBN} by default shows this
2477 information when you start an interactive session.
2478
2479 @subsubheading Example
2480
2481 @c This example modifies the actual output from GDB to avoid overfull
2482 @c box in TeX.
2483 @smallexample
2484 (@value{GDBP})
2485 -gdb-version
2486 ~GNU gdb 5.2.1
2487 ~Copyright 2000 Free Software Foundation, Inc.
2488 ~GDB is free software, covered by the GNU General Public License, and
2489 ~you are welcome to change it and/or distribute copies of it under
2490 ~ certain conditions.
2491 ~Type "show copying" to see the conditions.
2492 ~There is absolutely no warranty for GDB.  Type "show warranty" for
2493 ~ details.
2494 ~This GDB was configured as
2495  "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
2496 ^done
2497 (@value{GDBP})
2498 @end smallexample
2499
2500 @ignore
2501 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2502 @node GDB/MI Kod Commands
2503 @section @sc{gdb/mi} Kod Commands
2504
2505 The Kod commands are not implemented.
2506
2507 @c @subheading -kod-info
2508
2509 @c @subheading -kod-list
2510
2511 @c @subheading -kod-list-object-types
2512
2513 @c @subheading -kod-show
2514
2515 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2516 @node GDB/MI Memory Overlay Commands
2517 @section @sc{gdb/mi} Memory Overlay Commands
2518
2519 The memory overlay commands are not implemented.
2520
2521 @c @subheading -overlay-auto
2522
2523 @c @subheading -overlay-list-mapping-state
2524
2525 @c @subheading -overlay-list-overlays
2526
2527 @c @subheading -overlay-map
2528
2529 @c @subheading -overlay-off
2530
2531 @c @subheading -overlay-on
2532
2533 @c @subheading -overlay-unmap
2534
2535 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2536 @node GDB/MI Signal Handling Commands
2537 @section @sc{gdb/mi} Signal Handling Commands
2538
2539 Signal handling commands are not implemented.
2540
2541 @c @subheading -signal-handle
2542
2543 @c @subheading -signal-list-handle-actions
2544
2545 @c @subheading -signal-list-signal-types
2546 @end ignore
2547
2548
2549 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2550 @node GDB/MI Stack Manipulation
2551 @section @sc{gdb/mi} Stack Manipulation Commands
2552
2553
2554 @subheading The @code{-stack-info-frame} Command
2555 @findex -stack-info-frame
2556
2557 @subsubheading Synopsis
2558
2559 @example
2560  -stack-info-frame
2561 @end example
2562
2563 Get info on the current frame.
2564
2565 @subsubheading @value{GDBN} Command
2566
2567 The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
2568 (without arguments).
2569
2570 @subsubheading Example
2571 N.A.
2572
2573 @subheading The @code{-stack-info-depth} Command
2574 @findex -stack-info-depth
2575
2576 @subsubheading Synopsis
2577
2578 @example
2579  -stack-info-depth [ @var{max-depth} ]
2580 @end example
2581
2582 Return the depth of the stack.  If the integer argument @var{max-depth}
2583 is specified, do not count beyond @var{max-depth} frames.
2584
2585 @subsubheading @value{GDBN} Command
2586
2587 There's no equivalent @value{GDBN} command.
2588
2589 @subsubheading Example
2590
2591 For a stack with frame levels 0 through 11:
2592
2593 @smallexample
2594 (@value{GDBP})
2595 -stack-info-depth
2596 ^done,depth="12"
2597 (@value{GDBP})
2598 -stack-info-depth 4
2599 ^done,depth="4"
2600 (@value{GDBP})
2601 -stack-info-depth 12
2602 ^done,depth="12"
2603 (@value{GDBP})
2604 -stack-info-depth 11
2605 ^done,depth="11"
2606 (@value{GDBP})
2607 -stack-info-depth 13
2608 ^done,depth="12"
2609 (@value{GDBP})
2610 @end smallexample
2611
2612 @subheading The @code{-stack-list-arguments} Command
2613 @findex -stack-list-arguments
2614
2615 @subsubheading Synopsis
2616
2617 @example
2618  -stack-list-arguments @var{show-values}
2619     [ @var{low-frame} @var{high-frame} ]
2620 @end example
2621
2622 Display a list of the arguments for the frames between @var{low-frame}
2623 and @var{high-frame} (inclusive).  If @var{low-frame} and
2624 @var{high-frame} are not provided, list the arguments for the whole call
2625 stack.
2626
2627 The @var{show-values} argument must have a value of 0 or 1.  A value of
2628 0 means that only the names of the arguments are listed, a value of 1
2629 means that both names and values of the arguments are printed.
2630
2631 @subsubheading @value{GDBN} Command
2632
2633 @value{GDBN} does not have an equivalent command.  @code{gdbtk} has a
2634 @samp{gdb_get_args} command which partially overlaps with the
2635 functionality of @samp{-stack-list-arguments}.
2636
2637 @subsubheading Example
2638
2639 @smallexample
2640 (@value{GDBP})
2641 -stack-list-frames
2642 ^done,
2643 stack=[
2644 frame=@{level="0 ",addr="0x00010734",func="callee4",
2645 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
2646 frame=@{level="1 ",addr="0x0001076c",func="callee3",
2647 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
2648 frame=@{level="2 ",addr="0x0001078c",func="callee2",
2649 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
2650 frame=@{level="3 ",addr="0x000107b4",func="callee1",
2651 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
2652 frame=@{level="4 ",addr="0x000107e0",func="main",
2653 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
2654 (@value{GDBP})
2655 -stack-list-arguments 0
2656 ^done,
2657 stack-args=[
2658 frame=@{level="0",args=[]@},
2659 frame=@{level="1",args=[name="strarg"]@},
2660 frame=@{level="2",args=[name="intarg",name="strarg"]@},
2661 frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@},
2662 frame=@{level="4",args=[]@}]
2663 (@value{GDBP})
2664 -stack-list-arguments 1
2665 ^done,
2666 stack-args=[
2667 frame=@{level="0",args=[]@},
2668 frame=@{level="1",
2669  args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
2670 frame=@{level="2",args=[
2671 @{name="intarg",value="2"@},
2672 @{name="strarg",value="0x11940 \"A string argument.\""@}]@},
2673 @{frame=@{level="3",args=[
2674 @{name="intarg",value="2"@},
2675 @{name="strarg",value="0x11940 \"A string argument.\""@},
2676 @{name="fltarg",value="3.5"@}]@},
2677 frame=@{level="4",args=[]@}]
2678 (@value{GDBP})
2679 -stack-list-arguments 0 2 2
2680 ^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}]
2681 (@value{GDBP})
2682 -stack-list-arguments 1 2 2
2683 ^done,stack-args=[frame=@{level="2",
2684 args=[@{name="intarg",value="2"@},
2685 @{name="strarg",value="0x11940 \"A string argument.\""@}]@}]
2686 (@value{GDBP})
2687 @end smallexample
2688
2689 @c @subheading -stack-list-exception-handlers
2690
2691
2692 @subheading The @code{-stack-list-frames} Command
2693 @findex -stack-list-frames
2694
2695 @subsubheading Synopsis
2696
2697 @example
2698  -stack-list-frames [ @var{low-frame} @var{high-frame} ]
2699 @end example
2700
2701 List the frames currently on the stack.  For each frame it displays the
2702 following info:
2703
2704 @table @samp
2705 @item @var{level}
2706 The frame number, 0 being the topmost frame, i.e. the innermost function.
2707 @item @var{addr}
2708 The @code{$pc} value for that frame.
2709 @item @var{func}
2710 Function name.
2711 @item @var{file}
2712 File name of the source file where the function lives.
2713 @item @var{line}
2714 Line number corresponding to the @code{$pc}.
2715 @end table
2716
2717 If invoked without arguments, this command prints a backtrace for the
2718 whole stack.  If given two integer arguments, it shows the frames whose
2719 levels are between the two arguments (inclusive).  If the two arguments
2720 are equal, it shows the single frame at the corresponding level.
2721
2722 @subsubheading @value{GDBN} Command
2723
2724 The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
2725
2726 @subsubheading Example
2727
2728 Full stack backtrace:
2729
2730 @smallexample
2731 (@value{GDBP})
2732 -stack-list-frames
2733 ^done,stack=
2734 [frame=@{level="0 ",addr="0x0001076c",func="foo",
2735   file="recursive2.c",line="11"@},
2736 frame=@{level="1 ",addr="0x000107a4",func="foo",
2737   file="recursive2.c",line="14"@},
2738 frame=@{level="2 ",addr="0x000107a4",func="foo",
2739   file="recursive2.c",line="14"@},
2740 frame=@{level="3 ",addr="0x000107a4",func="foo",
2741   file="recursive2.c",line="14"@},
2742 frame=@{level="4 ",addr="0x000107a4",func="foo",
2743   file="recursive2.c",line="14"@},
2744 frame=@{level="5 ",addr="0x000107a4",func="foo",
2745   file="recursive2.c",line="14"@},
2746 frame=@{level="6 ",addr="0x000107a4",func="foo",
2747   file="recursive2.c",line="14"@},
2748 frame=@{level="7 ",addr="0x000107a4",func="foo",
2749   file="recursive2.c",line="14"@},
2750 frame=@{level="8 ",addr="0x000107a4",func="foo",
2751   file="recursive2.c",line="14"@},
2752 frame=@{level="9 ",addr="0x000107a4",func="foo",
2753   file="recursive2.c",line="14"@},
2754 frame=@{level="10",addr="0x000107a4",func="foo",
2755   file="recursive2.c",line="14"@},
2756 frame=@{level="11",addr="0x00010738",func="main",
2757   file="recursive2.c",line="4"@}]
2758 (@value{GDBP})
2759 @end smallexample
2760
2761 Show frames between @var{low_frame} and @var{high_frame}:
2762
2763 @smallexample
2764 (@value{GDBP})
2765 -stack-list-frames 3 5
2766 ^done,stack=
2767 [frame=@{level="3 ",addr="0x000107a4",func="foo",
2768   file="recursive2.c",line="14"@},
2769 frame=@{level="4 ",addr="0x000107a4",func="foo",
2770   file="recursive2.c",line="14"@},
2771 frame=@{level="5 ",addr="0x000107a4",func="foo",
2772   file="recursive2.c",line="14"@}]
2773 (@value{GDBP})
2774 @end smallexample
2775
2776 Show a single frame:
2777
2778 @smallexample
2779 (@value{GDBP})
2780 -stack-list-frames 3 3
2781 ^done,stack=
2782 [frame=@{level="3 ",addr="0x000107a4",func="foo",
2783   file="recursive2.c",line="14"@}]
2784 (@value{GDBP})
2785 @end smallexample
2786
2787
2788 @subheading The @code{-stack-list-locals} Command
2789 @findex -stack-list-locals
2790
2791 @subsubheading Synopsis
2792
2793 @example
2794  -stack-list-locals @var{print-values}
2795 @end example
2796
2797 Display the local variable names for the current frame.  With an
2798 argument of 0 prints only the names of the variables, with argument of 1
2799 prints also their values.
2800
2801 @subsubheading @value{GDBN} Command
2802
2803 @samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
2804
2805 @subsubheading Example
2806
2807 @smallexample
2808 (@value{GDBP})
2809 -stack-list-locals 0
2810 ^done,locals=[name="A",name="B",name="C"]
2811 (@value{GDBP})
2812 -stack-list-locals 1
2813 ^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
2814   @{name="C",value="3"@}]
2815 (@value{GDBP})
2816 @end smallexample
2817
2818
2819 @subheading The @code{-stack-select-frame} Command
2820 @findex -stack-select-frame
2821
2822 @subsubheading Synopsis
2823
2824 @example
2825  -stack-select-frame @var{framenum}
2826 @end example
2827
2828 Change the current frame.  Select a different frame @var{framenum} on
2829 the stack.
2830
2831 @subsubheading @value{GDBN} Command
2832
2833 The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
2834 @samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
2835
2836 @subsubheading Example
2837
2838 @smallexample
2839 (@value{GDBP})
2840 -stack-select-frame 2
2841 ^done
2842 (@value{GDBP})
2843 @end smallexample
2844
2845 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2846 @node GDB/MI Symbol Query
2847 @section @sc{gdb/mi} Symbol Query Commands
2848
2849
2850 @subheading The @code{-symbol-info-address} Command
2851 @findex -symbol-info-address
2852
2853 @subsubheading Synopsis
2854
2855 @example
2856  -symbol-info-address @var{symbol}
2857 @end example
2858
2859 Describe where @var{symbol} is stored.
2860
2861 @subsubheading @value{GDBN} Command
2862
2863 The corresponding @value{GDBN} command is @samp{info address}.
2864
2865 @subsubheading Example
2866 N.A.
2867
2868
2869 @subheading The @code{-symbol-info-file} Command
2870 @findex -symbol-info-file
2871
2872 @subsubheading Synopsis
2873
2874 @example
2875  -symbol-info-file
2876 @end example
2877
2878 Show the file for the symbol.
2879
2880 @subsubheading @value{GDBN} Command
2881
2882 There's no equivalent @value{GDBN} command.  @code{gdbtk} has
2883 @samp{gdb_find_file}.
2884
2885 @subsubheading Example
2886 N.A.
2887
2888
2889 @subheading The @code{-symbol-info-function} Command
2890 @findex -symbol-info-function
2891
2892 @subsubheading Synopsis
2893
2894 @example
2895  -symbol-info-function
2896 @end example
2897
2898 Show which function the symbol lives in.
2899
2900 @subsubheading @value{GDBN} Command
2901
2902 @samp{gdb_get_function} in @code{gdbtk}.
2903
2904 @subsubheading Example
2905 N.A.
2906
2907
2908 @subheading The @code{-symbol-info-line} Command
2909 @findex -symbol-info-line
2910
2911 @subsubheading Synopsis
2912
2913 @example
2914  -symbol-info-line
2915 @end example
2916
2917 Show the core addresses of the code for a source line.
2918
2919 @subsubheading @value{GDBN} Command
2920
2921 The corresponding @value{GDBN} comamnd is @samp{info line}.
2922 @code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
2923
2924 @subsubheading Example
2925 N.A.
2926
2927
2928 @subheading The @code{-symbol-info-symbol} Command
2929 @findex -symbol-info-symbol
2930
2931 @subsubheading Synopsis
2932
2933 @example
2934  -symbol-info-symbol @var{addr}
2935 @end example
2936
2937 Describe what symbol is at location @var{addr}.
2938
2939 @subsubheading @value{GDBN} Command
2940
2941 The corresponding @value{GDBN} command is @samp{info symbol}.
2942
2943 @subsubheading Example
2944 N.A.
2945
2946
2947 @subheading The @code{-symbol-list-functions} Command
2948 @findex -symbol-list-functions
2949
2950 @subsubheading Synopsis
2951
2952 @example
2953  -symbol-list-functions
2954 @end example
2955
2956 List the functions in the executable.
2957
2958 @subsubheading @value{GDBN} Command
2959
2960 @samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
2961 @samp{gdb_search} in @code{gdbtk}.
2962
2963 @subsubheading Example
2964 N.A.
2965
2966
2967 @subheading The @code{-symbol-list-types} Command
2968 @findex -symbol-list-types
2969
2970 @subsubheading Synopsis
2971
2972 @example
2973  -symbol-list-types
2974 @end example
2975
2976 List all the type names.
2977
2978 @subsubheading @value{GDBN} Command
2979
2980 The corresponding commands are @samp{info types} in @value{GDBN},
2981 @samp{gdb_search} in @code{gdbtk}.
2982
2983 @subsubheading Example
2984 N.A.
2985
2986
2987 @subheading The @code{-symbol-list-variables} Command
2988 @findex -symbol-list-variables
2989
2990 @subsubheading Synopsis
2991
2992 @example
2993  -symbol-list-variables
2994 @end example
2995
2996 List all the global and static variable names.
2997
2998 @subsubheading @value{GDBN} Command
2999
3000 @samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
3001
3002 @subsubheading Example
3003 N.A.
3004
3005
3006 @subheading The @code{-symbol-locate} Command
3007 @findex -symbol-locate
3008
3009 @subsubheading Synopsis
3010
3011 @example
3012  -symbol-locate
3013 @end example
3014
3015 @subsubheading @value{GDBN} Command
3016
3017 @samp{gdb_loc} in @code{gdbtk}.
3018
3019 @subsubheading Example
3020 N.A.
3021
3022
3023 @subheading The @code{-symbol-type} Command
3024 @findex -symbol-type
3025
3026 @subsubheading Synopsis
3027
3028 @example
3029  -symbol-type @var{variable}
3030 @end example
3031
3032 Show type of @var{variable}.
3033
3034 @subsubheading @value{GDBN} Command
3035
3036 The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
3037 @samp{gdb_obj_variable}.
3038
3039 @subsubheading Example
3040 N.A.
3041
3042
3043 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3044 @node GDB/MI Target Manipulation
3045 @section @sc{gdb/mi} Target Manipulation Commands
3046
3047
3048 @subheading The @code{-target-attach} Command
3049 @findex -target-attach
3050
3051 @subsubheading Synopsis
3052
3053 @example
3054  -target-attach @var{pid} | @var{file}
3055 @end example
3056
3057 Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
3058
3059 @subsubheading @value{GDBN} command
3060
3061 The corresponding @value{GDBN} command is @samp{attach}.
3062
3063 @subsubheading Example
3064 N.A.
3065
3066
3067 @subheading The @code{-target-compare-sections} Command
3068 @findex -target-compare-sections
3069
3070 @subsubheading Synopsis
3071
3072 @example
3073  -target-compare-sections [ @var{section} ]
3074 @end example
3075
3076 Compare data of section @var{section} on target to the exec file.
3077 Without the argument, all sections are compared.
3078
3079 @subsubheading @value{GDBN} Command
3080
3081 The @value{GDBN} equivalent is @samp{compare-sections}.
3082
3083 @subsubheading Example
3084 N.A.
3085
3086
3087 @subheading The @code{-target-detach} Command
3088 @findex -target-detach
3089
3090 @subsubheading Synopsis
3091
3092 @example
3093  -target-detach
3094 @end example
3095
3096 Disconnect from the remote target.  There's no output.
3097
3098 @subsubheading @value{GDBN} command
3099
3100 The corresponding @value{GDBN} command is @samp{detach}.
3101
3102 @subsubheading Example
3103
3104 @smallexample
3105 (@value{GDBP})
3106 -target-detach
3107 ^done
3108 (@value{GDBP})
3109 @end smallexample
3110
3111
3112 @subheading The @code{-target-download} Command
3113 @findex -target-download
3114
3115 @subsubheading Synopsis
3116
3117 @example
3118  -target-download
3119 @end example
3120
3121 Loads the executable onto the remote target.
3122 It prints out an update message every half second, which includes the fields:
3123
3124 @table @samp
3125 @item section
3126 The name of the section.
3127 @item section-sent
3128 The size of what has been sent so far for that section.
3129 @item section-size
3130 The size of the section.
3131 @item total-sent
3132 The total size of what was sent so far (the current and the previous sections).
3133 @item total-size
3134 The size of the overall executable to download.
3135 @end table
3136
3137 @noindent
3138 Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
3139 @sc{gdb/mi} Output Syntax}).
3140
3141 In addition, it prints the name and size of the sections, as they are
3142 downloaded.  These messages include the following fields:
3143
3144 @table @samp
3145 @item section
3146 The name of the section.
3147 @item section-size
3148 The size of the section.
3149 @item total-size
3150 The size of the overall executable to download.
3151 @end table
3152
3153 @noindent
3154 At the end, a summary is printed.
3155
3156 @subsubheading @value{GDBN} Command
3157
3158 The corresponding @value{GDBN} command is @samp{load}.
3159
3160 @subsubheading Example
3161
3162 Note: each status message appears on a single line.  Here the messages
3163 have been broken down so that they can fit onto a page.
3164
3165 @smallexample
3166 (@value{GDBP})
3167 -target-download
3168 +download,@{section=".text",section-size="6668",total-size="9880"@}
3169 +download,@{section=".text",section-sent="512",section-size="6668",
3170 total-sent="512",total-size="9880"@}
3171 +download,@{section=".text",section-sent="1024",section-size="6668",
3172 total-sent="1024",total-size="9880"@}
3173 +download,@{section=".text",section-sent="1536",section-size="6668",
3174 total-sent="1536",total-size="9880"@}
3175 +download,@{section=".text",section-sent="2048",section-size="6668",
3176 total-sent="2048",total-size="9880"@}
3177 +download,@{section=".text",section-sent="2560",section-size="6668",
3178 total-sent="2560",total-size="9880"@}
3179 +download,@{section=".text",section-sent="3072",section-size="6668",
3180 total-sent="3072",total-size="9880"@}
3181 +download,@{section=".text",section-sent="3584",section-size="6668",
3182 total-sent="3584",total-size="9880"@}
3183 +download,@{section=".text",section-sent="4096",section-size="6668",
3184 total-sent="4096",total-size="9880"@}
3185 +download,@{section=".text",section-sent="4608",section-size="6668",
3186 total-sent="4608",total-size="9880"@}
3187 +download,@{section=".text",section-sent="5120",section-size="6668",
3188 total-sent="5120",total-size="9880"@}
3189 +download,@{section=".text",section-sent="5632",section-size="6668",
3190 total-sent="5632",total-size="9880"@}
3191 +download,@{section=".text",section-sent="6144",section-size="6668",
3192 total-sent="6144",total-size="9880"@}
3193 +download,@{section=".text",section-sent="6656",section-size="6668",
3194 total-sent="6656",total-size="9880"@}
3195 +download,@{section=".init",section-size="28",total-size="9880"@}
3196 +download,@{section=".fini",section-size="28",total-size="9880"@}
3197 +download,@{section=".data",section-size="3156",total-size="9880"@}
3198 +download,@{section=".data",section-sent="512",section-size="3156",
3199 total-sent="7236",total-size="9880"@}
3200 +download,@{section=".data",section-sent="1024",section-size="3156",
3201 total-sent="7748",total-size="9880"@}
3202 +download,@{section=".data",section-sent="1536",section-size="3156",
3203 total-sent="8260",total-size="9880"@}
3204 +download,@{section=".data",section-sent="2048",section-size="3156",
3205 total-sent="8772",total-size="9880"@}
3206 +download,@{section=".data",section-sent="2560",section-size="3156",
3207 total-sent="9284",total-size="9880"@}
3208 +download,@{section=".data",section-sent="3072",section-size="3156",
3209 total-sent="9796",total-size="9880"@}
3210 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
3211 write-rate="429"
3212 (@value{GDBP})
3213 @end smallexample
3214
3215
3216 @subheading The @code{-target-exec-status} Command
3217 @findex -target-exec-status
3218
3219 @subsubheading Synopsis
3220
3221 @example
3222  -target-exec-status
3223 @end example
3224
3225 Provide information on the state of the target (whether it is running or
3226 not, for instance).
3227
3228 @subsubheading @value{GDBN} Command
3229
3230 There's no equivalent @value{GDBN} command.
3231
3232 @subsubheading Example
3233 N.A.
3234
3235
3236 @subheading The @code{-target-list-available-targets} Command
3237 @findex -target-list-available-targets
3238
3239 @subsubheading Synopsis
3240
3241 @example
3242  -target-list-available-targets
3243 @end example
3244
3245 List the possible targets to connect to.
3246
3247 @subsubheading @value{GDBN} Command
3248
3249 The corresponding @value{GDBN} command is @samp{help target}.
3250
3251 @subsubheading Example
3252 N.A.
3253
3254
3255 @subheading The @code{-target-list-current-targets} Command
3256 @findex -target-list-current-targets
3257
3258 @subsubheading Synopsis
3259
3260 @example
3261  -target-list-current-targets
3262 @end example
3263
3264 Describe the current target.
3265
3266 @subsubheading @value{GDBN} Command
3267
3268 The corresponding information is printed by @samp{info file} (among
3269 other things).
3270
3271 @subsubheading Example
3272 N.A.
3273
3274
3275 @subheading The @code{-target-list-parameters} Command
3276 @findex -target-list-parameters
3277
3278 @subsubheading Synopsis
3279
3280 @example
3281  -target-list-parameters
3282 @end example
3283
3284 @c ????
3285
3286 @subsubheading @value{GDBN} Command
3287
3288 No equivalent.
3289
3290 @subsubheading Example
3291 N.A.
3292
3293
3294 @subheading The @code{-target-select} Command
3295 @findex -target-select
3296
3297 @subsubheading Synopsis
3298
3299 @example
3300  -target-select @var{type} @var{parameters @dots{}}
3301 @end example
3302
3303 Connect @value{GDBN} to the remote target.  This command takes two args:
3304
3305 @table @samp
3306 @item @var{type}
3307 The type of target, for instance @samp{async}, @samp{remote}, etc.
3308 @item @var{parameters}
3309 Device names, host names and the like.  @xref{Target Commands, ,
3310 Commands for managing targets}, for more details.
3311 @end table
3312
3313 The output is a connection notification, followed by the address at
3314 which the target program is, in the following form:
3315
3316 @smallexample
3317 ^connected,addr="@var{address}",func="@var{function name}",
3318   args=[@var{arg list}]
3319 @end smallexample
3320
3321 @subsubheading @value{GDBN} Command
3322
3323 The corresponding @value{GDBN} command is @samp{target}.
3324
3325 @subsubheading Example
3326
3327 @smallexample
3328 (@value{GDBP})
3329 -target-select async /dev/ttya
3330 ^connected,addr="0xfe00a300",func="??",args=[]
3331 (@value{GDBP})
3332 @end smallexample
3333
3334 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3335 @node GDB/MI Thread Commands
3336 @section @sc{gdb/mi} Thread Commands
3337
3338
3339 @subheading The @code{-thread-info} Command
3340 @findex -thread-info
3341
3342 @subsubheading Synopsis
3343
3344 @example
3345  -thread-info
3346 @end example
3347
3348 @subsubheading @value{GDBN} command
3349
3350 No equivalent.
3351
3352 @subsubheading Example
3353 N.A.
3354
3355
3356 @subheading The @code{-thread-list-all-threads} Command
3357 @findex -thread-list-all-threads
3358
3359 @subsubheading Synopsis
3360
3361 @example
3362  -thread-list-all-threads
3363 @end example
3364
3365 @subsubheading @value{GDBN} Command
3366
3367 The equivalent @value{GDBN} command is @samp{info threads}.
3368
3369 @subsubheading Example
3370 N.A.
3371
3372
3373 @subheading The @code{-thread-list-ids} Command
3374 @findex -thread-list-ids
3375
3376 @subsubheading Synopsis
3377
3378 @example
3379  -thread-list-ids
3380 @end example
3381
3382 Produces a list of the currently known @value{GDBN} thread ids.  At the
3383 end of the list it also prints the total number of such threads.
3384
3385 @subsubheading @value{GDBN} Command
3386
3387 Part of @samp{info threads} supplies the same information.
3388
3389 @subsubheading Example
3390
3391 No threads present, besides the main process:
3392
3393 @smallexample
3394 (@value{GDBP})
3395 -thread-list-ids
3396 ^done,thread-ids=@{@},number-of-threads="0"
3397 (@value{GDBP})
3398 @end smallexample
3399
3400
3401 Several threads:
3402
3403 @smallexample
3404 (@value{GDBP})
3405 -thread-list-ids
3406 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3407 number-of-threads="3"
3408 (@value{GDBP})
3409 @end smallexample
3410
3411
3412 @subheading The @code{-thread-select} Command
3413 @findex -thread-select
3414
3415 @subsubheading Synopsis
3416
3417 @example
3418  -thread-select @var{threadnum}
3419 @end example
3420
3421 Make @var{threadnum} the current thread.  It prints the number of the new
3422 current thread, and the topmost frame for that thread.
3423
3424 @subsubheading @value{GDBN} Command
3425
3426 The corresponding @value{GDBN} command is @samp{thread}.
3427
3428 @subsubheading Example
3429
3430 @smallexample
3431 (@value{GDBP})
3432 -exec-next
3433 ^running
3434 (@value{GDBP})
3435 *stopped,reason="end-stepping-range",thread-id="2",line="187",
3436 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
3437 (@value{GDBP})
3438 -thread-list-ids
3439 ^done,
3440 thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3441 number-of-threads="3"
3442 (@value{GDBP})
3443 -thread-select 3
3444 ^done,new-thread-id="3",
3445 frame=@{level="0 ",func="vprintf",
3446 args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
3447 @{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
3448 (@value{GDBP})
3449 @end smallexample
3450
3451 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3452 @node GDB/MI Tracepoint Commands
3453 @section @sc{gdb/mi} Tracepoint Commands
3454
3455 The tracepoint commands are not yet implemented.
3456
3457 @c @subheading -trace-actions
3458
3459 @c @subheading -trace-delete
3460
3461 @c @subheading -trace-disable
3462
3463 @c @subheading -trace-dump
3464
3465 @c @subheading -trace-enable
3466
3467 @c @subheading -trace-exists
3468
3469 @c @subheading -trace-find
3470
3471 @c @subheading -trace-frame-number
3472
3473 @c @subheading -trace-info
3474
3475 @c @subheading -trace-insert
3476
3477 @c @subheading -trace-list
3478
3479 @c @subheading -trace-pass-count
3480
3481 @c @subheading -trace-save
3482
3483 @c @subheading -trace-start
3484
3485 @c @subheading -trace-stop
3486
3487
3488 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3489 @node GDB/MI Variable Objects
3490 @section @sc{gdb/mi} Variable Objects
3491
3492
3493 @subheading Motivation for Variable Objects in @sc{gdb/mi}
3494
3495 For the implementation of a variable debugger window (locals, watched
3496 expressions, etc.), we are proposing the adaptation of the existing code
3497 used by @code{Insight}.
3498
3499 The two main reasons for that are:
3500
3501 @enumerate 1
3502 @item
3503 It has been proven in practice (it is already on its second generation).
3504
3505 @item
3506 It will shorten development time (needless to say how important it is
3507 now).
3508 @end enumerate
3509
3510 The original interface was designed to be used by Tcl code, so it was
3511 slightly changed so it could be used through @sc{gdb/mi}.  This section
3512 describes the @sc{gdb/mi} operations that will be available and gives some
3513 hints about their use.
3514
3515 @emph{Note}: In addition to the set of operations described here, we
3516 expect the @sc{gui} implementation of a variable window to require, at
3517 least, the following operations:
3518
3519 @itemize @bullet
3520 @item @code{-gdb-show} @code{output-radix}
3521 @item @code{-stack-list-arguments}
3522 @item @code{-stack-list-locals}
3523 @item @code{-stack-select-frame}
3524 @end itemize
3525
3526 @subheading Introduction to Variable Objects in @sc{gdb/mi}
3527
3528 @cindex variable objects in @sc{gdb/mi}
3529 The basic idea behind variable objects is the creation of a named object
3530 to represent a variable, an expression, a memory location or even a CPU
3531 register.  For each object created, a set of operations is available for
3532 examining or changing its properties.
3533
3534 Furthermore, complex data types, such as C structures, are represented
3535 in a tree format.  For instance, the @code{struct} type variable is the
3536 root and the children will represent the struct members.  If a child
3537 is itself of a complex type, it will also have children of its own.
3538 Appropriate language differences are handled for C, C@t{++} and Java.
3539
3540 When returning the actual values of the objects, this facility allows
3541 for the individual selection of the display format used in the result
3542 creation.  It can be chosen among: binary, decimal, hexadecimal, octal
3543 and natural.  Natural refers to a default format automatically
3544 chosen based on the variable type (like decimal for an @code{int}, hex
3545 for pointers, etc.).
3546
3547 The following is the complete set of @sc{gdb/mi} operations defined to
3548 access this functionality:
3549
3550 @multitable @columnfractions .4 .6
3551 @item @strong{Operation}
3552 @tab @strong{Description}
3553
3554 @item @code{-var-create}
3555 @tab create a variable object
3556 @item @code{-var-delete}
3557 @tab delete the variable object and its children
3558 @item @code{-var-set-format}
3559 @tab set the display format of this variable
3560 @item @code{-var-show-format}
3561 @tab show the display format of this variable
3562 @item @code{-var-info-num-children}
3563 @tab tells how many children this object has
3564 @item @code{-var-list-children}
3565 @tab return a list of the object's children
3566 @item @code{-var-info-type}
3567 @tab show the type of this variable object
3568 @item @code{-var-info-expression}
3569 @tab print what this variable object represents
3570 @item @code{-var-show-attributes}
3571 @tab is this variable editable? does it exist here?
3572 @item @code{-var-evaluate-expression}
3573 @tab get the value of this variable
3574 @item @code{-var-assign}
3575 @tab set the value of this variable
3576 @item @code{-var-update}
3577 @tab update the variable and its children
3578 @end multitable
3579
3580 In the next subsection we describe each operation in detail and suggest
3581 how it can be used.
3582
3583 @subheading Description And Use of Operations on Variable Objects
3584
3585 @subheading The @code{-var-create} Command
3586 @findex -var-create
3587
3588 @subsubheading Synopsis
3589
3590 @example
3591  -var-create @{@var{name} | "-"@}
3592     @{@var{frame-addr} | "*"@} @var{expression}
3593 @end example
3594
3595 This operation creates a variable object, which allows the monitoring of
3596 a variable, the result of an expression, a memory cell or a CPU
3597 register.
3598
3599 The @var{name} parameter is the string by which the object can be
3600 referenced.  It must be unique.  If @samp{-} is specified, the varobj
3601 system will generate a string ``varNNNNNN'' automatically.  It will be
3602 unique provided that one does not specify @var{name} on that format.
3603 The command fails if a duplicate name is found.
3604
3605 The frame under which the expression should be evaluated can be
3606 specified by @var{frame-addr}.  A @samp{*} indicates that the current
3607 frame should be used.
3608
3609 @var{expression} is any expression valid on the current language set (must not
3610 begin with a @samp{*}), or one of the following:
3611
3612 @itemize @bullet
3613 @item
3614 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
3615
3616 @item
3617 @samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
3618
3619 @item
3620 @samp{$@var{regname}} --- a CPU register name
3621 @end itemize
3622
3623 @subsubheading Result
3624
3625 This operation returns the name, number of children and the type of the
3626 object created.  Type is returned as a string as the ones generated by
3627 the @value{GDBN} CLI:
3628
3629 @example
3630  name="@var{name}",numchild="N",type="@var{type}"
3631 @end example
3632
3633
3634 @subheading The @code{-var-delete} Command
3635 @findex -var-delete
3636
3637 @subsubheading Synopsis
3638
3639 @example
3640  -var-delete @var{name}
3641 @end example
3642
3643 Deletes a previously created variable object and all of its children.
3644
3645 Returns an error if the object @var{name} is not found.
3646
3647
3648 @subheading The @code{-var-set-format} Command
3649 @findex -var-set-format
3650
3651 @subsubheading Synopsis
3652
3653 @example
3654  -var-set-format @var{name} @var{format-spec}
3655 @end example
3656
3657 Sets the output format for the value of the object @var{name} to be
3658 @var{format-spec}.
3659
3660 The syntax for the @var{format-spec} is as follows:
3661
3662 @example
3663  @var{format-spec} @expansion{}
3664  @{binary | decimal | hexadecimal | octal | natural@}
3665 @end example
3666
3667
3668 @subheading The @code{-var-show-format} Command
3669 @findex -var-show-format
3670
3671 @subsubheading Synopsis
3672
3673 @example
3674  -var-show-format @var{name}
3675 @end example
3676
3677 Returns the format used to display the value of the object @var{name}.
3678
3679 @example
3680  @var{format} @expansion{}
3681  @var{format-spec}
3682 @end example
3683
3684
3685 @subheading The @code{-var-info-num-children} Command
3686 @findex -var-info-num-children
3687
3688 @subsubheading Synopsis
3689
3690 @example
3691  -var-info-num-children @var{name}
3692 @end example
3693
3694 Returns the number of children of a variable object @var{name}:
3695
3696 @example
3697  numchild=@var{n}
3698 @end example
3699
3700
3701 @subheading The @code{-var-list-children} Command
3702 @findex -var-list-children
3703
3704 @subsubheading Synopsis
3705
3706 @example
3707  -var-list-children @var{name}
3708 @end example
3709
3710 Returns a list of the children of the specified variable object:
3711
3712 @example
3713  numchild=@var{n},children=@{@{name=@var{name},
3714  numchild=@var{n},type=@var{type}@},@r{(repeats N times)}@}
3715 @end example
3716
3717
3718 @subheading The @code{-var-info-type} Command
3719 @findex -var-info-type
3720
3721 @subsubheading Synopsis
3722
3723 @example
3724  -var-info-type @var{name}
3725 @end example
3726
3727 Returns the type of the specified variable @var{name}.  The type is
3728 returned as a string in the same format as it is output by the
3729 @value{GDBN} CLI:
3730
3731 @example
3732  type=@var{typename}
3733 @end example
3734
3735
3736 @subheading The @code{-var-info-expression} Command
3737 @findex -var-info-expression
3738
3739 @subsubheading Synopsis
3740
3741 @example
3742  -var-info-expression @var{name}
3743 @end example
3744
3745 Returns what is represented by the variable object @var{name}:
3746
3747 @example
3748  lang=@var{lang-spec},exp=@var{expression}
3749 @end example
3750
3751 @noindent
3752 where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
3753
3754 @subheading The @code{-var-show-attributes} Command
3755 @findex -var-show-attributes
3756
3757 @subsubheading Synopsis
3758
3759 @example
3760  -var-show-attributes @var{name}
3761 @end example
3762
3763 List attributes of the specified variable object @var{name}:
3764
3765 @example
3766  status=@var{attr} [ ( ,@var{attr} )* ]
3767 @end example
3768
3769 @noindent
3770 where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
3771
3772 @subheading The @code{-var-evaluate-expression} Command
3773 @findex -var-evaluate-expression
3774
3775 @subsubheading Synopsis
3776
3777 @example
3778  -var-evaluate-expression @var{name}
3779 @end example
3780
3781 Evaluates the expression that is represented by the specified variable
3782 object and returns its value as a string in the current format specified
3783 for the object:
3784
3785 @example
3786  value=@var{value}
3787 @end example
3788
3789 @subheading The @code{-var-assign} Command
3790 @findex -var-assign
3791
3792 @subsubheading Synopsis
3793
3794 @example
3795  -var-assign @var{name} @var{expression}
3796 @end example
3797
3798 Assigns the value of @var{expression} to the variable object specified
3799 by @var{name}.  The object must be @samp{editable}.
3800
3801 @subheading The @code{-var-update} Command
3802 @findex -var-update
3803
3804 @subsubheading Synopsis
3805
3806 @example
3807  -var-update @{@var{name} | "*"@}
3808 @end example
3809
3810 Update the value of the variable object @var{name} by evaluating its
3811 expression after fetching all the new values from memory or registers.
3812 A @samp{*} causes all existing variable objects to be updated.