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 [ -r ] [ @var{pathdir} ]+
1669 @end example
1670
1671 Add directories @var{pathdir} to beginning of search path for source files.
1672 If the @samp{-r} option is used, the search path is reset to the default
1673 search path.  If directories @var{pathdir} are supplied in addition to the
1674 @samp{-r} option, the search path is first reset and then addition
1675 occurs as normal.
1676 Multiple directories may be specified, separated by blanks.  Specifying
1677 multiple directories in a single command
1678 results in the directories added to the beginning of the
1679 search path in the same order they were presented in the command.
1680 If blanks are needed as
1681 part of a directory name, double-quotes should be used around
1682 the name.  In the command output, the path will show up separated
1683 by the system directory-separator character.  The directory-seperator
1684 character must not be used
1685 in any directory name.
1686 If no directories are specified, the current search path is displayed.
1687
1688 @subsubheading @value{GDBN} Command
1689
1690 The corresponding @value{GDBN} command is @samp{dir}.
1691
1692 @subsubheading Example
1693
1694 @smallexample
1695 (@value{GDBP})
1696 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1697 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
1698 (@value{GDBP})
1699 -environment-directory ""
1700 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
1701 (@value{GDBP})
1702 -environment-directory -r /home/jjohnstn/src/gdb /usr/src
1703 ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
1704 (@value{GDBP})
1705 -environment-directory -r
1706 ^done,source-path="$cdir:$cwd"
1707 (@value{GDBP})
1708 @end smallexample
1709
1710
1711 @subheading The @code{-environment-path} Command
1712 @findex -environment-path
1713
1714 @subsubheading Synopsis
1715
1716 @example
1717  -environment-path [ -r ] [ @var{pathdir} ]+
1718 @end example
1719
1720 Add directories @var{pathdir} to beginning of search path for object files.
1721 If the @samp{-r} option is used, the search path is reset to the original
1722 search path that existed at gdb start-up.  If directories @var{pathdir} are
1723 supplied in addition to the
1724 @samp{-r} option, the search path is first reset and then addition
1725 occurs as normal.
1726 Multiple directories may be specified, separated by blanks.  Specifying
1727 multiple directories in a single command
1728 results in the directories added to the beginning of the
1729 search path in the same order they were presented in the command.
1730 If blanks are needed as
1731 part of a directory name, double-quotes should be used around
1732 the name.  In the command output, the path will show up separated
1733 by the system directory-separator character.  The directory-seperator
1734 character must not be used
1735 in any directory name.
1736 If no directories are specified, the current path is displayed.
1737
1738
1739 @subsubheading @value{GDBN} Command
1740
1741 The corresponding @value{GDBN} command is @samp{path}.
1742
1743 @subsubheading Example
1744
1745 @smallexample
1746 (@value{GDBP})
1747 -environment-path
1748 ^done,path="/usr/bin"
1749 (@value{GDBP})
1750 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
1751 ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
1752 (@value{GDBP})
1753 -environment-path -r /usr/local/bin
1754 ^done,path="/usr/local/bin:/usr/bin"
1755 (@value{GDBP})
1756 @end smallexample
1757
1758
1759 @subheading The @code{-environment-pwd} Command
1760 @findex -environment-pwd
1761
1762 @subsubheading Synopsis
1763
1764 @example
1765  -environment-pwd
1766 @end example
1767
1768 Show the current working directory.
1769
1770 @subsubheading @value{GDBN} command
1771
1772 The corresponding @value{GDBN} command is @samp{pwd}.
1773
1774 @subsubheading Example
1775
1776 @smallexample
1777 (@value{GDBP})
1778 -environment-pwd
1779 ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
1780 (@value{GDBP})
1781 @end smallexample
1782
1783 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1784 @node GDB/MI Program Control
1785 @section @sc{gdb/mi} Program control
1786
1787 @subsubheading Program termination
1788
1789 As a result of execution, the inferior program can run to completion, if
1790 it doesn't encounter any breakpoints.  In this case the output will
1791 include an exit code, if the program has exited exceptionally.
1792
1793 @subsubheading Examples
1794
1795 @noindent
1796 Program exited normally:
1797
1798 @smallexample
1799 (@value{GDBP})
1800 -exec-run
1801 ^running
1802 (@value{GDBP})
1803 x = 55
1804 *stopped,reason="exited-normally"
1805 (@value{GDBP})
1806 @end smallexample
1807
1808 @noindent
1809 Program exited exceptionally:
1810
1811 @smallexample
1812 (@value{GDBP})
1813 -exec-run
1814 ^running
1815 (@value{GDBP})
1816 x = 55
1817 *stopped,reason="exited",exit-code="01"
1818 (@value{GDBP})
1819 @end smallexample
1820
1821 Another way the program can terminate is if it receives a signal such as
1822 @code{SIGINT}.  In this case, @sc{gdb/mi} displays this:
1823
1824 @smallexample
1825 (@value{GDBP})
1826 *stopped,reason="exited-signalled",signal-name="SIGINT",
1827 signal-meaning="Interrupt"
1828 @end smallexample
1829
1830
1831 @subheading The @code{-exec-abort} Command
1832 @findex -exec-abort
1833
1834 @subsubheading Synopsis
1835
1836 @example
1837  -exec-abort
1838 @end example
1839
1840 Kill the inferior running program.
1841
1842 @subsubheading @value{GDBN} Command
1843
1844 The corresponding @value{GDBN} command is @samp{kill}.
1845
1846 @subsubheading Example
1847 N.A.
1848
1849
1850 @subheading The @code{-exec-arguments} Command
1851 @findex -exec-arguments
1852
1853 @subsubheading Synopsis
1854
1855 @example
1856  -exec-arguments @var{args}
1857 @end example
1858
1859 Set the inferior program arguments, to be used in the next
1860 @samp{-exec-run}.
1861
1862 @subsubheading @value{GDBN} Command
1863
1864 The corresponding @value{GDBN} command is @samp{set args}.
1865
1866 @subsubheading Example
1867
1868 @c FIXME!
1869 Don't have one around.
1870
1871
1872 @subheading The @code{-exec-continue} Command
1873 @findex -exec-continue
1874
1875 @subsubheading Synopsis
1876
1877 @example
1878  -exec-continue
1879 @end example
1880
1881 Asynchronous command.  Resumes the execution of the inferior program
1882 until a breakpoint is encountered, or until the inferior exits.
1883
1884 @subsubheading @value{GDBN} Command
1885
1886 The corresponding @value{GDBN} corresponding is @samp{continue}.
1887
1888 @subsubheading Example
1889
1890 @smallexample
1891 -exec-continue
1892 ^running
1893 (@value{GDBP})
1894 @@Hello world
1895 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
1896 file="hello.c",line="13"@}
1897 (@value{GDBP})
1898 @end smallexample
1899
1900
1901 @subheading The @code{-exec-finish} Command
1902 @findex -exec-finish
1903
1904 @subsubheading Synopsis
1905
1906 @example
1907  -exec-finish
1908 @end example
1909
1910 Asynchronous command.  Resumes the execution of the inferior program
1911 until the current function is exited.  Displays the results returned by
1912 the function.
1913
1914 @subsubheading @value{GDBN} Command
1915
1916 The corresponding @value{GDBN} command is @samp{finish}.
1917
1918 @subsubheading Example
1919
1920 Function returning @code{void}.
1921
1922 @smallexample
1923 -exec-finish
1924 ^running
1925 (@value{GDBP})
1926 @@hello from foo
1927 *stopped,reason="function-finished",frame=@{func="main",args=[],
1928 file="hello.c",line="7"@}
1929 (@value{GDBP})
1930 @end smallexample
1931
1932 Function returning other than @code{void}.  The name of the internal
1933 @value{GDBN} variable storing the result is printed, together with the
1934 value itself.
1935
1936 @smallexample
1937 -exec-finish
1938 ^running
1939 (@value{GDBP})
1940 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
1941 args=[@{name="a",value="1"],@{name="b",value="9"@}@},
1942 file="recursive2.c",line="14"@},
1943 gdb-result-var="$1",return-value="0"
1944 (@value{GDBP})
1945 @end smallexample
1946
1947
1948 @subheading The @code{-exec-interrupt} Command
1949 @findex -exec-interrupt
1950
1951 @subsubheading Synopsis
1952
1953 @example
1954  -exec-interrupt
1955 @end example
1956
1957 Asynchronous command.  Interrupts the background execution of the target.
1958 Note how the token associated with the stop message is the one for the
1959 execution command that has been interrupted.  The token for the interrupt
1960 itself only appears in the @samp{^done} output.  If the user is trying to
1961 interrupt a non-running program, an error message will be printed.
1962
1963 @subsubheading @value{GDBN} Command
1964
1965 The corresponding @value{GDBN} command is @samp{interrupt}.
1966
1967 @subsubheading Example
1968
1969 @smallexample
1970 (@value{GDBP})
1971 111-exec-continue
1972 111^running
1973
1974 (@value{GDBP})
1975 222-exec-interrupt
1976 222^done
1977 (@value{GDBP})
1978 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1979 frame=@{addr="0x00010140",func="foo",args=[],file="try.c",line="13"@}
1980 (@value{GDBP})
1981
1982 (@value{GDBP})
1983 -exec-interrupt
1984 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1985 (@value{GDBP})
1986 @end smallexample
1987
1988
1989 @subheading The @code{-exec-next} Command
1990 @findex -exec-next
1991
1992 @subsubheading Synopsis
1993
1994 @example
1995  -exec-next
1996 @end example
1997
1998 Asynchronous command.  Resumes execution of the inferior program, stopping
1999 when the beginning of the next source line is reached.
2000
2001 @subsubheading @value{GDBN} Command
2002
2003 The corresponding @value{GDBN} command is @samp{next}.
2004
2005 @subsubheading Example
2006
2007 @smallexample
2008 -exec-next
2009 ^running
2010 (@value{GDBP})
2011 *stopped,reason="end-stepping-range",line="8",file="hello.c"
2012 (@value{GDBP})
2013 @end smallexample
2014
2015
2016 @subheading The @code{-exec-next-instruction} Command
2017 @findex -exec-next-instruction
2018
2019 @subsubheading Synopsis
2020
2021 @example
2022  -exec-next-instruction
2023 @end example
2024
2025 Asynchronous command.  Executes one machine instruction.  If the
2026 instruction is a function call continues until the function returns.  If
2027 the program stops at an instruction in the middle of a source line, the
2028 address will be printed as well.
2029
2030 @subsubheading @value{GDBN} Command
2031
2032 The corresponding @value{GDBN} command is @samp{nexti}.
2033
2034 @subsubheading Example
2035
2036 @smallexample
2037 (@value{GDBP})
2038 -exec-next-instruction
2039 ^running
2040
2041 (@value{GDBP})
2042 *stopped,reason="end-stepping-range",
2043 addr="0x000100d4",line="5",file="hello.c"
2044 (@value{GDBP})
2045 @end smallexample
2046
2047
2048 @subheading The @code{-exec-return} Command
2049 @findex -exec-return
2050
2051 @subsubheading Synopsis
2052
2053 @example
2054  -exec-return
2055 @end example
2056
2057 Makes current function return immediately.  Doesn't execute the inferior.
2058 Displays the new current frame.
2059
2060 @subsubheading @value{GDBN} Command
2061
2062 The corresponding @value{GDBN} command is @samp{return}.
2063
2064 @subsubheading Example
2065
2066 @smallexample
2067 (@value{GDBP})
2068 200-break-insert callee4
2069 200^done,bkpt=@{number="1",addr="0x00010734",
2070 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
2071 (@value{GDBP})
2072 000-exec-run
2073 000^running
2074 (@value{GDBP})
2075 000*stopped,reason="breakpoint-hit",bkptno="1",
2076 frame=@{func="callee4",args=[],
2077 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
2078 (@value{GDBP})
2079 205-break-delete
2080 205^done
2081 (@value{GDBP})
2082 111-exec-return
2083 111^done,frame=@{level="0",func="callee3",
2084 args=[@{name="strarg",
2085 value="0x11940 \"A string argument.\""@}],
2086 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
2087 (@value{GDBP})
2088 @end smallexample
2089
2090
2091 @subheading The @code{-exec-run} Command
2092 @findex -exec-run
2093
2094 @subsubheading Synopsis
2095
2096 @example
2097  -exec-run
2098 @end example
2099
2100 Asynchronous command.  Starts execution of the inferior from the
2101 beginning.  The inferior executes until either a breakpoint is
2102 encountered or the program exits.
2103
2104 @subsubheading @value{GDBN} Command
2105
2106 The corresponding @value{GDBN} command is @samp{run}.
2107
2108 @subsubheading Example
2109
2110 @smallexample
2111 (@value{GDBP})
2112 -break-insert main
2113 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
2114 (@value{GDBP})
2115 -exec-run
2116 ^running
2117 (@value{GDBP})
2118 *stopped,reason="breakpoint-hit",bkptno="1",
2119 frame=@{func="main",args=[],file="recursive2.c",line="4"@}
2120 (@value{GDBP})
2121 @end smallexample
2122
2123
2124 @subheading The @code{-exec-show-arguments} Command
2125 @findex -exec-show-arguments
2126
2127 @subsubheading Synopsis
2128
2129 @example
2130  -exec-show-arguments
2131 @end example
2132
2133 Print the arguments of the program.
2134
2135 @subsubheading @value{GDBN} Command
2136
2137 The corresponding @value{GDBN} command is @samp{show args}.
2138
2139 @subsubheading Example
2140 N.A.
2141
2142 @c @subheading -exec-signal
2143
2144 @subheading The @code{-exec-step} Command
2145 @findex -exec-step
2146
2147 @subsubheading Synopsis
2148
2149 @example
2150  -exec-step
2151 @end example
2152
2153 Asynchronous command.  Resumes execution of the inferior program, stopping
2154 when the beginning of the next source line is reached, if the next
2155 source line is not a function call.  If it is, stop at the first
2156 instruction of the called function.
2157
2158 @subsubheading @value{GDBN} Command
2159
2160 The corresponding @value{GDBN} command is @samp{step}.
2161
2162 @subsubheading Example
2163
2164 Stepping into a function:
2165
2166 @smallexample
2167 -exec-step
2168 ^running
2169 (@value{GDBP})
2170 *stopped,reason="end-stepping-range",
2171 frame=@{func="foo",args=[@{name="a",value="10"@},
2172 @{name="b",value="0"@}],file="recursive2.c",line="11"@}
2173 (@value{GDBP})
2174 @end smallexample
2175
2176 Regular stepping:
2177
2178 @smallexample
2179 -exec-step
2180 ^running
2181 (@value{GDBP})
2182 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
2183 (@value{GDBP})
2184 @end smallexample
2185
2186
2187 @subheading The @code{-exec-step-instruction} Command
2188 @findex -exec-step-instruction
2189
2190 @subsubheading Synopsis
2191
2192 @example
2193  -exec-step-instruction
2194 @end example
2195
2196 Asynchronous command.  Resumes the inferior which executes one machine
2197 instruction.  The output, once @value{GDBN} has stopped, will vary depending on
2198 whether we have stopped in the middle of a source line or not.  In the
2199 former case, the address at which the program stopped will be printed as
2200 well.
2201
2202 @subsubheading @value{GDBN} Command
2203
2204 The corresponding @value{GDBN} command is @samp{stepi}.
2205
2206 @subsubheading Example
2207
2208 @smallexample
2209 (@value{GDBP})
2210 -exec-step-instruction
2211 ^running
2212
2213 (@value{GDBP})
2214 *stopped,reason="end-stepping-range",
2215 frame=@{func="foo",args=[],file="try.c",line="10"@}
2216 (@value{GDBP})
2217 -exec-step-instruction
2218 ^running
2219
2220 (@value{GDBP})
2221 *stopped,reason="end-stepping-range",
2222 frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@}
2223 (@value{GDBP})
2224 @end smallexample
2225
2226
2227 @subheading The @code{-exec-until} Command
2228 @findex -exec-until
2229
2230 @subsubheading Synopsis
2231
2232 @example
2233  -exec-until [ @var{location} ]
2234 @end example
2235
2236 Asynchronous command.  Executes the inferior until the @var{location}
2237 specified in the argument is reached.  If there is no argument, the inferior
2238 executes until a source line greater than the current one is reached.
2239 The reason for stopping in this case will be @samp{location-reached}.
2240
2241 @subsubheading @value{GDBN} Command
2242
2243 The corresponding @value{GDBN} command is @samp{until}.
2244
2245 @subsubheading Example
2246
2247 @smallexample
2248 (@value{GDBP})
2249 -exec-until recursive2.c:6
2250 ^running
2251 (@value{GDBP})
2252 x = 55
2253 *stopped,reason="location-reached",frame=@{func="main",args=[],
2254 file="recursive2.c",line="6"@}
2255 (@value{GDBP})
2256 @end smallexample
2257
2258 @ignore
2259 @subheading -file-clear
2260 Is this going away????
2261 @end ignore
2262
2263
2264 @subheading The @code{-file-exec-and-symbols} Command
2265 @findex -file-exec-and-symbols
2266
2267 @subsubheading Synopsis
2268
2269 @example
2270  -file-exec-and-symbols @var{file}
2271 @end example
2272
2273 Specify the executable file to be debugged.  This file is the one from
2274 which the symbol table is also read.  If no file is specified, the
2275 command clears the executable and symbol information.  If breakpoints
2276 are set when using this command with no arguments, @value{GDBN} will produce
2277 error messages.  Otherwise, no output is produced, except a completion
2278 notification.
2279
2280 @subsubheading @value{GDBN} Command
2281
2282 The corresponding @value{GDBN} command is @samp{file}.
2283
2284 @subsubheading Example
2285
2286 @smallexample
2287 (@value{GDBP})
2288 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2289 ^done
2290 (@value{GDBP})
2291 @end smallexample
2292
2293
2294 @subheading The @code{-file-exec-file} Command
2295 @findex -file-exec-file
2296
2297 @subsubheading Synopsis
2298
2299 @example
2300  -file-exec-file @var{file}
2301 @end example
2302
2303 Specify the executable file to be debugged.  Unlike
2304 @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
2305 from this file.  If used without argument, @value{GDBN} clears the information
2306 about the executable file.  No output is produced, except a completion
2307 notification.
2308
2309 @subsubheading @value{GDBN} Command
2310
2311 The corresponding @value{GDBN} command is @samp{exec-file}.
2312
2313 @subsubheading Example
2314
2315 @smallexample
2316 (@value{GDBP})
2317 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2318 ^done
2319 (@value{GDBP})
2320 @end smallexample
2321
2322
2323 @subheading The @code{-file-list-exec-sections} Command
2324 @findex -file-list-exec-sections
2325
2326 @subsubheading Synopsis
2327
2328 @example
2329  -file-list-exec-sections
2330 @end example
2331
2332 List the sections of the current executable file.
2333
2334 @subsubheading @value{GDBN} Command
2335
2336 The @value{GDBN} command @samp{info file} shows, among the rest, the same
2337 information as this command.  @code{gdbtk} has a corresponding command
2338 @samp{gdb_load_info}.
2339
2340 @subsubheading Example
2341 N.A.
2342
2343
2344 @subheading The @code{-file-list-exec-source-files} Command
2345 @findex -file-list-exec-source-files
2346
2347 @subsubheading Synopsis
2348
2349 @example
2350  -file-list-exec-source-files
2351 @end example
2352
2353 List the source files for the current executable.
2354
2355 @subsubheading @value{GDBN} Command
2356
2357 There's no @value{GDBN} command which directly corresponds to this one.
2358 @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
2359
2360 @subsubheading Example
2361 N.A.
2362
2363
2364 @subheading The @code{-file-list-shared-libraries} Command
2365 @findex -file-list-shared-libraries
2366
2367 @subsubheading Synopsis
2368
2369 @example
2370  -file-list-shared-libraries
2371 @end example
2372
2373 List the shared libraries in the program.
2374
2375 @subsubheading @value{GDBN} Command
2376
2377 The corresponding @value{GDBN} command is @samp{info shared}.
2378
2379 @subsubheading Example
2380 N.A.
2381
2382
2383 @subheading The @code{-file-list-symbol-files} Command
2384 @findex -file-list-symbol-files
2385
2386 @subsubheading Synopsis
2387
2388 @example
2389  -file-list-symbol-files
2390 @end example
2391
2392 List symbol files.
2393
2394 @subsubheading @value{GDBN} Command
2395
2396 The corresponding @value{GDBN} command is @samp{info file} (part of it).
2397
2398 @subsubheading Example
2399 N.A.
2400
2401
2402 @subheading The @code{-file-symbol-file} Command
2403 @findex -file-symbol-file
2404
2405 @subsubheading Synopsis
2406
2407 @example
2408  -file-symbol-file @var{file}
2409 @end example
2410
2411 Read symbol table info from the specified @var{file} argument.  When
2412 used without arguments, clears @value{GDBN}'s symbol table info.  No output is
2413 produced, except for a completion notification.
2414
2415 @subsubheading @value{GDBN} Command
2416
2417 The corresponding @value{GDBN} command is @samp{symbol-file}.
2418
2419 @subsubheading Example
2420
2421 @smallexample
2422 (@value{GDBP})
2423 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2424 ^done
2425 (@value{GDBP})
2426 @end smallexample
2427
2428 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2429 @node GDB/MI Miscellaneous Commands
2430 @section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
2431
2432 @c @subheading -gdb-complete
2433
2434 @subheading The @code{-gdb-exit} Command
2435 @findex -gdb-exit
2436
2437 @subsubheading Synopsis
2438
2439 @example
2440  -gdb-exit
2441 @end example
2442
2443 Exit @value{GDBN} immediately.
2444
2445 @subsubheading @value{GDBN} Command
2446
2447 Approximately corresponds to @samp{quit}.
2448
2449 @subsubheading Example
2450
2451 @smallexample
2452 (@value{GDBP})
2453 -gdb-exit
2454 @end smallexample
2455
2456 @subheading The @code{-gdb-set} Command
2457 @findex -gdb-set
2458
2459 @subsubheading Synopsis
2460
2461 @example
2462  -gdb-set
2463 @end example
2464
2465 Set an internal @value{GDBN} variable.
2466 @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
2467
2468 @subsubheading @value{GDBN} Command
2469
2470 The corresponding @value{GDBN} command is @samp{set}.
2471
2472 @subsubheading Example
2473
2474 @smallexample
2475 (@value{GDBP})
2476 -gdb-set $foo=3
2477 ^done
2478 (@value{GDBP})
2479 @end smallexample
2480
2481
2482 @subheading The @code{-gdb-show} Command
2483 @findex -gdb-show
2484
2485 @subsubheading Synopsis
2486
2487 @example
2488  -gdb-show
2489 @end example
2490
2491 Show the current value of a @value{GDBN} variable.
2492
2493 @subsubheading @value{GDBN} command
2494
2495 The corresponding @value{GDBN} command is @samp{show}.
2496
2497 @subsubheading Example
2498
2499 @smallexample
2500 (@value{GDBP})
2501 -gdb-show annotate
2502 ^done,value="0"
2503 (@value{GDBP})
2504 @end smallexample
2505
2506 @c @subheading -gdb-source
2507
2508
2509 @subheading The @code{-gdb-version} Command
2510 @findex -gdb-version
2511
2512 @subsubheading Synopsis
2513
2514 @example
2515  -gdb-version
2516 @end example
2517
2518 Show version information for @value{GDBN}.  Used mostly in testing.
2519
2520 @subsubheading @value{GDBN} Command
2521
2522 There's no equivalent @value{GDBN} command.  @value{GDBN} by default shows this
2523 information when you start an interactive session.
2524
2525 @subsubheading Example
2526
2527 @c This example modifies the actual output from GDB to avoid overfull
2528 @c box in TeX.
2529 @smallexample
2530 (@value{GDBP})
2531 -gdb-version
2532 ~GNU gdb 5.2.1
2533 ~Copyright 2000 Free Software Foundation, Inc.
2534 ~GDB is free software, covered by the GNU General Public License, and
2535 ~you are welcome to change it and/or distribute copies of it under
2536 ~ certain conditions.
2537 ~Type "show copying" to see the conditions.
2538 ~There is absolutely no warranty for GDB.  Type "show warranty" for
2539 ~ details.
2540 ~This GDB was configured as
2541  "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
2542 ^done
2543 (@value{GDBP})
2544 @end smallexample
2545
2546 @ignore
2547 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2548 @node GDB/MI Kod Commands
2549 @section @sc{gdb/mi} Kod Commands
2550
2551 The Kod commands are not implemented.
2552
2553 @c @subheading -kod-info
2554
2555 @c @subheading -kod-list
2556
2557 @c @subheading -kod-list-object-types
2558
2559 @c @subheading -kod-show
2560
2561 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2562 @node GDB/MI Memory Overlay Commands
2563 @section @sc{gdb/mi} Memory Overlay Commands
2564
2565 The memory overlay commands are not implemented.
2566
2567 @c @subheading -overlay-auto
2568
2569 @c @subheading -overlay-list-mapping-state
2570
2571 @c @subheading -overlay-list-overlays
2572
2573 @c @subheading -overlay-map
2574
2575 @c @subheading -overlay-off
2576
2577 @c @subheading -overlay-on
2578
2579 @c @subheading -overlay-unmap
2580
2581 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2582 @node GDB/MI Signal Handling Commands
2583 @section @sc{gdb/mi} Signal Handling Commands
2584
2585 Signal handling commands are not implemented.
2586
2587 @c @subheading -signal-handle
2588
2589 @c @subheading -signal-list-handle-actions
2590
2591 @c @subheading -signal-list-signal-types
2592 @end ignore
2593
2594
2595 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2596 @node GDB/MI Stack Manipulation
2597 @section @sc{gdb/mi} Stack Manipulation Commands
2598
2599
2600 @subheading The @code{-stack-info-frame} Command
2601 @findex -stack-info-frame
2602
2603 @subsubheading Synopsis
2604
2605 @example
2606  -stack-info-frame
2607 @end example
2608
2609 Get info on the current frame.
2610
2611 @subsubheading @value{GDBN} Command
2612
2613 The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
2614 (without arguments).
2615
2616 @subsubheading Example
2617 N.A.
2618
2619 @subheading The @code{-stack-info-depth} Command
2620 @findex -stack-info-depth
2621
2622 @subsubheading Synopsis
2623
2624 @example
2625  -stack-info-depth [ @var{max-depth} ]
2626 @end example
2627
2628 Return the depth of the stack.  If the integer argument @var{max-depth}
2629 is specified, do not count beyond @var{max-depth} frames.
2630
2631 @subsubheading @value{GDBN} Command
2632
2633 There's no equivalent @value{GDBN} command.
2634
2635 @subsubheading Example
2636
2637 For a stack with frame levels 0 through 11:
2638
2639 @smallexample
2640 (@value{GDBP})
2641 -stack-info-depth
2642 ^done,depth="12"
2643 (@value{GDBP})
2644 -stack-info-depth 4
2645 ^done,depth="4"
2646 (@value{GDBP})
2647 -stack-info-depth 12
2648 ^done,depth="12"
2649 (@value{GDBP})
2650 -stack-info-depth 11
2651 ^done,depth="11"
2652 (@value{GDBP})
2653 -stack-info-depth 13
2654 ^done,depth="12"
2655 (@value{GDBP})
2656 @end smallexample
2657
2658 @subheading The @code{-stack-list-arguments} Command
2659 @findex -stack-list-arguments
2660
2661 @subsubheading Synopsis
2662
2663 @example
2664  -stack-list-arguments @var{show-values}
2665     [ @var{low-frame} @var{high-frame} ]
2666 @end example
2667
2668 Display a list of the arguments for the frames between @var{low-frame}
2669 and @var{high-frame} (inclusive).  If @var{low-frame} and
2670 @var{high-frame} are not provided, list the arguments for the whole call
2671 stack.
2672
2673 The @var{show-values} argument must have a value of 0 or 1.  A value of
2674 0 means that only the names of the arguments are listed, a value of 1
2675 means that both names and values of the arguments are printed.
2676
2677 @subsubheading @value{GDBN} Command
2678
2679 @value{GDBN} does not have an equivalent command.  @code{gdbtk} has a
2680 @samp{gdb_get_args} command which partially overlaps with the
2681 functionality of @samp{-stack-list-arguments}.
2682
2683 @subsubheading Example
2684
2685 @smallexample
2686 (@value{GDBP})
2687 -stack-list-frames
2688 ^done,
2689 stack=[
2690 frame=@{level="0",addr="0x00010734",func="callee4",
2691 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
2692 frame=@{level="1",addr="0x0001076c",func="callee3",
2693 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
2694 frame=@{level="2",addr="0x0001078c",func="callee2",
2695 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
2696 frame=@{level="3",addr="0x000107b4",func="callee1",
2697 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
2698 frame=@{level="4",addr="0x000107e0",func="main",
2699 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
2700 (@value{GDBP})
2701 -stack-list-arguments 0
2702 ^done,
2703 stack-args=[
2704 frame=@{level="0",args=[]@},
2705 frame=@{level="1",args=[name="strarg"]@},
2706 frame=@{level="2",args=[name="intarg",name="strarg"]@},
2707 frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@},
2708 frame=@{level="4",args=[]@}]
2709 (@value{GDBP})
2710 -stack-list-arguments 1
2711 ^done,
2712 stack-args=[
2713 frame=@{level="0",args=[]@},
2714 frame=@{level="1",
2715  args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
2716 frame=@{level="2",args=[
2717 @{name="intarg",value="2"@},
2718 @{name="strarg",value="0x11940 \"A string argument.\""@}]@},
2719 @{frame=@{level="3",args=[
2720 @{name="intarg",value="2"@},
2721 @{name="strarg",value="0x11940 \"A string argument.\""@},
2722 @{name="fltarg",value="3.5"@}]@},
2723 frame=@{level="4",args=[]@}]
2724 (@value{GDBP})
2725 -stack-list-arguments 0 2 2
2726 ^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}]
2727 (@value{GDBP})
2728 -stack-list-arguments 1 2 2
2729 ^done,stack-args=[frame=@{level="2",
2730 args=[@{name="intarg",value="2"@},
2731 @{name="strarg",value="0x11940 \"A string argument.\""@}]@}]
2732 (@value{GDBP})
2733 @end smallexample
2734
2735 @c @subheading -stack-list-exception-handlers
2736
2737
2738 @subheading The @code{-stack-list-frames} Command
2739 @findex -stack-list-frames
2740
2741 @subsubheading Synopsis
2742
2743 @example
2744  -stack-list-frames [ @var{low-frame} @var{high-frame} ]
2745 @end example
2746
2747 List the frames currently on the stack.  For each frame it displays the
2748 following info:
2749
2750 @table @samp
2751 @item @var{level}
2752 The frame number, 0 being the topmost frame, i.e. the innermost function.
2753 @item @var{addr}
2754 The @code{$pc} value for that frame.
2755 @item @var{func}
2756 Function name.
2757 @item @var{file}
2758 File name of the source file where the function lives.
2759 @item @var{line}
2760 Line number corresponding to the @code{$pc}.
2761 @end table
2762
2763 If invoked without arguments, this command prints a backtrace for the
2764 whole stack.  If given two integer arguments, it shows the frames whose
2765 levels are between the two arguments (inclusive).  If the two arguments
2766 are equal, it shows the single frame at the corresponding level.
2767
2768 @subsubheading @value{GDBN} Command
2769
2770 The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
2771
2772 @subsubheading Example
2773
2774 Full stack backtrace:
2775
2776 @smallexample
2777 (@value{GDBP})
2778 -stack-list-frames
2779 ^done,stack=
2780 [frame=@{level="0",addr="0x0001076c",func="foo",
2781   file="recursive2.c",line="11"@},
2782 frame=@{level="1",addr="0x000107a4",func="foo",
2783   file="recursive2.c",line="14"@},
2784 frame=@{level="2",addr="0x000107a4",func="foo",
2785   file="recursive2.c",line="14"@},
2786 frame=@{level="3",addr="0x000107a4",func="foo",
2787   file="recursive2.c",line="14"@},
2788 frame=@{level="4",addr="0x000107a4",func="foo",
2789   file="recursive2.c",line="14"@},
2790 frame=@{level="5",addr="0x000107a4",func="foo",
2791   file="recursive2.c",line="14"@},
2792 frame=@{level="6",addr="0x000107a4",func="foo",
2793   file="recursive2.c",line="14"@},
2794 frame=@{level="7",addr="0x000107a4",func="foo",
2795   file="recursive2.c",line="14"@},
2796 frame=@{level="8",addr="0x000107a4",func="foo",
2797   file="recursive2.c",line="14"@},
2798 frame=@{level="9",addr="0x000107a4",func="foo",
2799   file="recursive2.c",line="14"@},
2800 frame=@{level="10",addr="0x000107a4",func="foo",
2801   file="recursive2.c",line="14"@},
2802 frame=@{level="11",addr="0x00010738",func="main",
2803   file="recursive2.c",line="4"@}]
2804 (@value{GDBP})
2805 @end smallexample
2806
2807 Show frames between @var{low_frame} and @var{high_frame}:
2808
2809 @smallexample
2810 (@value{GDBP})
2811 -stack-list-frames 3 5
2812 ^done,stack=
2813 [frame=@{level="3",addr="0x000107a4",func="foo",
2814   file="recursive2.c",line="14"@},
2815 frame=@{level="4",addr="0x000107a4",func="foo",
2816   file="recursive2.c",line="14"@},
2817 frame=@{level="5",addr="0x000107a4",func="foo",
2818   file="recursive2.c",line="14"@}]
2819 (@value{GDBP})
2820 @end smallexample
2821
2822 Show a single frame:
2823
2824 @smallexample
2825 (@value{GDBP})
2826 -stack-list-frames 3 3
2827 ^done,stack=
2828 [frame=@{level="3",addr="0x000107a4",func="foo",
2829   file="recursive2.c",line="14"@}]
2830 (@value{GDBP})
2831 @end smallexample
2832
2833
2834 @subheading The @code{-stack-list-locals} Command
2835 @findex -stack-list-locals
2836
2837 @subsubheading Synopsis
2838
2839 @example
2840  -stack-list-locals @var{print-values}
2841 @end example
2842
2843 Display the local variable names for the current frame.  With an
2844 argument of 0 prints only the names of the variables, with argument of 1
2845 prints also their values.
2846
2847 @subsubheading @value{GDBN} Command
2848
2849 @samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
2850
2851 @subsubheading Example
2852
2853 @smallexample
2854 (@value{GDBP})
2855 -stack-list-locals 0
2856 ^done,locals=[name="A",name="B",name="C"]
2857 (@value{GDBP})
2858 -stack-list-locals 1
2859 ^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
2860   @{name="C",value="3"@}]
2861 (@value{GDBP})
2862 @end smallexample
2863
2864
2865 @subheading The @code{-stack-select-frame} Command
2866 @findex -stack-select-frame
2867
2868 @subsubheading Synopsis
2869
2870 @example
2871  -stack-select-frame @var{framenum}
2872 @end example
2873
2874 Change the current frame.  Select a different frame @var{framenum} on
2875 the stack.
2876
2877 @subsubheading @value{GDBN} Command
2878
2879 The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
2880 @samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
2881
2882 @subsubheading Example
2883
2884 @smallexample
2885 (@value{GDBP})
2886 -stack-select-frame 2
2887 ^done
2888 (@value{GDBP})
2889 @end smallexample
2890
2891 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2892 @node GDB/MI Symbol Query
2893 @section @sc{gdb/mi} Symbol Query Commands
2894
2895
2896 @subheading The @code{-symbol-info-address} Command
2897 @findex -symbol-info-address
2898
2899 @subsubheading Synopsis
2900
2901 @example
2902  -symbol-info-address @var{symbol}
2903 @end example
2904
2905 Describe where @var{symbol} is stored.
2906
2907 @subsubheading @value{GDBN} Command
2908
2909 The corresponding @value{GDBN} command is @samp{info address}.
2910
2911 @subsubheading Example
2912 N.A.
2913
2914
2915 @subheading The @code{-symbol-info-file} Command
2916 @findex -symbol-info-file
2917
2918 @subsubheading Synopsis
2919
2920 @example
2921  -symbol-info-file
2922 @end example
2923
2924 Show the file for the symbol.
2925
2926 @subsubheading @value{GDBN} Command
2927
2928 There's no equivalent @value{GDBN} command.  @code{gdbtk} has
2929 @samp{gdb_find_file}.
2930
2931 @subsubheading Example
2932 N.A.
2933
2934
2935 @subheading The @code{-symbol-info-function} Command
2936 @findex -symbol-info-function
2937
2938 @subsubheading Synopsis
2939
2940 @example
2941  -symbol-info-function
2942 @end example
2943
2944 Show which function the symbol lives in.
2945
2946 @subsubheading @value{GDBN} Command
2947
2948 @samp{gdb_get_function} in @code{gdbtk}.
2949
2950 @subsubheading Example
2951 N.A.
2952
2953
2954 @subheading The @code{-symbol-info-line} Command
2955 @findex -symbol-info-line
2956
2957 @subsubheading Synopsis
2958
2959 @example
2960  -symbol-info-line
2961 @end example
2962
2963 Show the core addresses of the code for a source line.
2964
2965 @subsubheading @value{GDBN} Command
2966
2967 The corresponding @value{GDBN} comamnd is @samp{info line}.
2968 @code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
2969
2970 @subsubheading Example
2971 N.A.
2972
2973
2974 @subheading The @code{-symbol-info-symbol} Command
2975 @findex -symbol-info-symbol
2976
2977 @subsubheading Synopsis
2978
2979 @example
2980  -symbol-info-symbol @var{addr}
2981 @end example
2982
2983 Describe what symbol is at location @var{addr}.
2984
2985 @subsubheading @value{GDBN} Command
2986
2987 The corresponding @value{GDBN} command is @samp{info symbol}.
2988
2989 @subsubheading Example
2990 N.A.
2991
2992
2993 @subheading The @code{-symbol-list-functions} Command
2994 @findex -symbol-list-functions
2995
2996 @subsubheading Synopsis
2997
2998 @example
2999  -symbol-list-functions
3000 @end example
3001
3002 List the functions in the executable.
3003
3004 @subsubheading @value{GDBN} Command
3005
3006 @samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
3007 @samp{gdb_search} in @code{gdbtk}.
3008
3009 @subsubheading Example
3010 N.A.
3011
3012
3013 @subheading The @code{-symbol-list-types} Command
3014 @findex -symbol-list-types
3015
3016 @subsubheading Synopsis
3017
3018 @example
3019  -symbol-list-types
3020 @end example
3021
3022 List all the type names.
3023
3024 @subsubheading @value{GDBN} Command
3025
3026 The corresponding commands are @samp{info types} in @value{GDBN},
3027 @samp{gdb_search} in @code{gdbtk}.
3028
3029 @subsubheading Example
3030 N.A.
3031
3032
3033 @subheading The @code{-symbol-list-variables} Command
3034 @findex -symbol-list-variables
3035
3036 @subsubheading Synopsis
3037
3038 @example
3039  -symbol-list-variables
3040 @end example
3041
3042 List all the global and static variable names.
3043
3044 @subsubheading @value{GDBN} Command
3045
3046 @samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
3047
3048 @subsubheading Example
3049 N.A.
3050
3051
3052 @subheading The @code{-symbol-locate} Command
3053 @findex -symbol-locate
3054
3055 @subsubheading Synopsis
3056
3057 @example
3058  -symbol-locate
3059 @end example
3060
3061 @subsubheading @value{GDBN} Command
3062
3063 @samp{gdb_loc} in @code{gdbtk}.
3064
3065 @subsubheading Example
3066 N.A.
3067
3068
3069 @subheading The @code{-symbol-type} Command
3070 @findex -symbol-type
3071
3072 @subsubheading Synopsis
3073
3074 @example
3075  -symbol-type @var{variable}
3076 @end example
3077
3078 Show type of @var{variable}.
3079
3080 @subsubheading @value{GDBN} Command
3081
3082 The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
3083 @samp{gdb_obj_variable}.
3084
3085 @subsubheading Example
3086 N.A.
3087
3088
3089 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3090 @node GDB/MI Target Manipulation
3091 @section @sc{gdb/mi} Target Manipulation Commands
3092
3093
3094 @subheading The @code{-target-attach} Command
3095 @findex -target-attach
3096
3097 @subsubheading Synopsis
3098
3099 @example
3100  -target-attach @var{pid} | @var{file}
3101 @end example
3102
3103 Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
3104
3105 @subsubheading @value{GDBN} command
3106
3107 The corresponding @value{GDBN} command is @samp{attach}.
3108
3109 @subsubheading Example
3110 N.A.
3111
3112
3113 @subheading The @code{-target-compare-sections} Command
3114 @findex -target-compare-sections
3115
3116 @subsubheading Synopsis
3117
3118 @example
3119  -target-compare-sections [ @var{section} ]
3120 @end example
3121
3122 Compare data of section @var{section} on target to the exec file.
3123 Without the argument, all sections are compared.
3124
3125 @subsubheading @value{GDBN} Command
3126
3127 The @value{GDBN} equivalent is @samp{compare-sections}.
3128
3129 @subsubheading Example
3130 N.A.
3131
3132
3133 @subheading The @code{-target-detach} Command
3134 @findex -target-detach
3135
3136 @subsubheading Synopsis
3137
3138 @example
3139  -target-detach
3140 @end example
3141
3142 Disconnect from the remote target.  There's no output.
3143
3144 @subsubheading @value{GDBN} command
3145
3146 The corresponding @value{GDBN} command is @samp{detach}.
3147
3148 @subsubheading Example
3149
3150 @smallexample
3151 (@value{GDBP})
3152 -target-detach
3153 ^done
3154 (@value{GDBP})
3155 @end smallexample
3156
3157
3158 @subheading The @code{-target-download} Command
3159 @findex -target-download
3160
3161 @subsubheading Synopsis
3162
3163 @example
3164  -target-download
3165 @end example
3166
3167 Loads the executable onto the remote target.
3168 It prints out an update message every half second, which includes the fields:
3169
3170 @table @samp
3171 @item section
3172 The name of the section.
3173 @item section-sent
3174 The size of what has been sent so far for that section.
3175 @item section-size
3176 The size of the section.
3177 @item total-sent
3178 The total size of what was sent so far (the current and the previous sections).
3179 @item total-size
3180 The size of the overall executable to download.
3181 @end table
3182
3183 @noindent
3184 Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
3185 @sc{gdb/mi} Output Syntax}).
3186
3187 In addition, it prints the name and size of the sections, as they are
3188 downloaded.  These messages include the following fields:
3189
3190 @table @samp
3191 @item section
3192 The name of the section.
3193 @item section-size
3194 The size of the section.
3195 @item total-size
3196 The size of the overall executable to download.
3197 @end table
3198
3199 @noindent
3200 At the end, a summary is printed.
3201
3202 @subsubheading @value{GDBN} Command
3203
3204 The corresponding @value{GDBN} command is @samp{load}.
3205
3206 @subsubheading Example
3207
3208 Note: each status message appears on a single line.  Here the messages
3209 have been broken down so that they can fit onto a page.
3210
3211 @smallexample
3212 (@value{GDBP})
3213 -target-download
3214 +download,@{section=".text",section-size="6668",total-size="9880"@}
3215 +download,@{section=".text",section-sent="512",section-size="6668",
3216 total-sent="512",total-size="9880"@}
3217 +download,@{section=".text",section-sent="1024",section-size="6668",
3218 total-sent="1024",total-size="9880"@}
3219 +download,@{section=".text",section-sent="1536",section-size="6668",
3220 total-sent="1536",total-size="9880"@}
3221 +download,@{section=".text",section-sent="2048",section-size="6668",
3222 total-sent="2048",total-size="9880"@}
3223 +download,@{section=".text",section-sent="2560",section-size="6668",
3224 total-sent="2560",total-size="9880"@}
3225 +download,@{section=".text",section-sent="3072",section-size="6668",
3226 total-sent="3072",total-size="9880"@}
3227 +download,@{section=".text",section-sent="3584",section-size="6668",
3228 total-sent="3584",total-size="9880"@}
3229 +download,@{section=".text",section-sent="4096",section-size="6668",
3230 total-sent="4096",total-size="9880"@}
3231 +download,@{section=".text",section-sent="4608",section-size="6668",
3232 total-sent="4608",total-size="9880"@}
3233 +download,@{section=".text",section-sent="5120",section-size="6668",
3234 total-sent="5120",total-size="9880"@}
3235 +download,@{section=".text",section-sent="5632",section-size="6668",
3236 total-sent="5632",total-size="9880"@}
3237 +download,@{section=".text",section-sent="6144",section-size="6668",
3238 total-sent="6144",total-size="9880"@}
3239 +download,@{section=".text",section-sent="6656",section-size="6668",
3240 total-sent="6656",total-size="9880"@}
3241 +download,@{section=".init",section-size="28",total-size="9880"@}
3242 +download,@{section=".fini",section-size="28",total-size="9880"@}
3243 +download,@{section=".data",section-size="3156",total-size="9880"@}
3244 +download,@{section=".data",section-sent="512",section-size="3156",
3245 total-sent="7236",total-size="9880"@}
3246 +download,@{section=".data",section-sent="1024",section-size="3156",
3247 total-sent="7748",total-size="9880"@}
3248 +download,@{section=".data",section-sent="1536",section-size="3156",
3249 total-sent="8260",total-size="9880"@}
3250 +download,@{section=".data",section-sent="2048",section-size="3156",
3251 total-sent="8772",total-size="9880"@}
3252 +download,@{section=".data",section-sent="2560",section-size="3156",
3253 total-sent="9284",total-size="9880"@}
3254 +download,@{section=".data",section-sent="3072",section-size="3156",
3255 total-sent="9796",total-size="9880"@}
3256 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
3257 write-rate="429"
3258 (@value{GDBP})
3259 @end smallexample
3260
3261
3262 @subheading The @code{-target-exec-status} Command
3263 @findex -target-exec-status
3264
3265 @subsubheading Synopsis
3266
3267 @example
3268  -target-exec-status
3269 @end example
3270
3271 Provide information on the state of the target (whether it is running or
3272 not, for instance).
3273
3274 @subsubheading @value{GDBN} Command
3275
3276 There's no equivalent @value{GDBN} command.
3277
3278 @subsubheading Example
3279 N.A.
3280
3281
3282 @subheading The @code{-target-list-available-targets} Command
3283 @findex -target-list-available-targets
3284
3285 @subsubheading Synopsis
3286
3287 @example
3288  -target-list-available-targets
3289 @end example
3290
3291 List the possible targets to connect to.
3292
3293 @subsubheading @value{GDBN} Command
3294
3295 The corresponding @value{GDBN} command is @samp{help target}.
3296
3297 @subsubheading Example
3298 N.A.
3299
3300
3301 @subheading The @code{-target-list-current-targets} Command
3302 @findex -target-list-current-targets
3303
3304 @subsubheading Synopsis
3305
3306 @example
3307  -target-list-current-targets
3308 @end example
3309
3310 Describe the current target.
3311
3312 @subsubheading @value{GDBN} Command
3313
3314 The corresponding information is printed by @samp{info file} (among
3315 other things).
3316
3317 @subsubheading Example
3318 N.A.
3319
3320
3321 @subheading The @code{-target-list-parameters} Command
3322 @findex -target-list-parameters
3323
3324 @subsubheading Synopsis
3325
3326 @example
3327  -target-list-parameters
3328 @end example
3329
3330 @c ????
3331
3332 @subsubheading @value{GDBN} Command
3333
3334 No equivalent.
3335
3336 @subsubheading Example
3337 N.A.
3338
3339
3340 @subheading The @code{-target-select} Command
3341 @findex -target-select
3342
3343 @subsubheading Synopsis
3344
3345 @example
3346  -target-select @var{type} @var{parameters @dots{}}
3347 @end example
3348
3349 Connect @value{GDBN} to the remote target.  This command takes two args:
3350
3351 @table @samp
3352 @item @var{type}
3353 The type of target, for instance @samp{async}, @samp{remote}, etc.
3354 @item @var{parameters}
3355 Device names, host names and the like.  @xref{Target Commands, ,
3356 Commands for managing targets}, for more details.
3357 @end table
3358
3359 The output is a connection notification, followed by the address at
3360 which the target program is, in the following form:
3361
3362 @smallexample
3363 ^connected,addr="@var{address}",func="@var{function name}",
3364   args=[@var{arg list}]
3365 @end smallexample
3366
3367 @subsubheading @value{GDBN} Command
3368
3369 The corresponding @value{GDBN} command is @samp{target}.
3370
3371 @subsubheading Example
3372
3373 @smallexample
3374 (@value{GDBP})
3375 -target-select async /dev/ttya
3376 ^connected,addr="0xfe00a300",func="??",args=[]
3377 (@value{GDBP})
3378 @end smallexample
3379
3380 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3381 @node GDB/MI Thread Commands
3382 @section @sc{gdb/mi} Thread Commands
3383
3384
3385 @subheading The @code{-thread-info} Command
3386 @findex -thread-info
3387
3388 @subsubheading Synopsis
3389
3390 @example
3391  -thread-info
3392 @end example
3393
3394 @subsubheading @value{GDBN} command
3395
3396 No equivalent.
3397
3398 @subsubheading Example
3399 N.A.
3400
3401
3402 @subheading The @code{-thread-list-all-threads} Command
3403 @findex -thread-list-all-threads
3404
3405 @subsubheading Synopsis
3406
3407 @example
3408  -thread-list-all-threads
3409 @end example
3410
3411 @subsubheading @value{GDBN} Command
3412
3413 The equivalent @value{GDBN} command is @samp{info threads}.
3414
3415 @subsubheading Example
3416 N.A.
3417
3418
3419 @subheading The @code{-thread-list-ids} Command
3420 @findex -thread-list-ids
3421
3422 @subsubheading Synopsis
3423
3424 @example
3425  -thread-list-ids
3426 @end example
3427
3428 Produces a list of the currently known @value{GDBN} thread ids.  At the
3429 end of the list it also prints the total number of such threads.
3430
3431 @subsubheading @value{GDBN} Command
3432
3433 Part of @samp{info threads} supplies the same information.
3434
3435 @subsubheading Example
3436
3437 No threads present, besides the main process:
3438
3439 @smallexample
3440 (@value{GDBP})
3441 -thread-list-ids
3442 ^done,thread-ids=@{@},number-of-threads="0"
3443 (@value{GDBP})
3444 @end smallexample
3445
3446
3447 Several threads:
3448
3449 @smallexample
3450 (@value{GDBP})
3451 -thread-list-ids
3452 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3453 number-of-threads="3"
3454 (@value{GDBP})
3455 @end smallexample
3456
3457
3458 @subheading The @code{-thread-select} Command
3459 @findex -thread-select
3460
3461 @subsubheading Synopsis
3462
3463 @example
3464  -thread-select @var{threadnum}
3465 @end example
3466
3467 Make @var{threadnum} the current thread.  It prints the number of the new
3468 current thread, and the topmost frame for that thread.
3469
3470 @subsubheading @value{GDBN} Command
3471
3472 The corresponding @value{GDBN} command is @samp{thread}.
3473
3474 @subsubheading Example
3475
3476 @smallexample
3477 (@value{GDBP})
3478 -exec-next
3479 ^running
3480 (@value{GDBP})
3481 *stopped,reason="end-stepping-range",thread-id="2",line="187",
3482 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
3483 (@value{GDBP})
3484 -thread-list-ids
3485 ^done,
3486 thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3487 number-of-threads="3"
3488 (@value{GDBP})
3489 -thread-select 3
3490 ^done,new-thread-id="3",
3491 frame=@{level="0",func="vprintf",
3492 args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
3493 @{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
3494 (@value{GDBP})
3495 @end smallexample
3496
3497 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3498 @node GDB/MI Tracepoint Commands
3499 @section @sc{gdb/mi} Tracepoint Commands
3500
3501 The tracepoint commands are not yet implemented.
3502
3503 @c @subheading -trace-actions
3504
3505 @c @subheading -trace-delete
3506
3507 @c @subheading -trace-disable
3508
3509 @c @subheading -trace-dump
3510
3511 @c @subheading -trace-enable
3512
3513 @c @subheading -trace-exists
3514
3515 @c @subheading -trace-find
3516
3517 @c @subheading -trace-frame-number
3518
3519 @c @subheading -trace-info
3520
3521 @c @subheading -trace-insert
3522
3523 @c @subheading -trace-list
3524
3525 @c @subheading -trace-pass-count
3526
3527 @c @subheading -trace-save
3528
3529 @c @subheading -trace-start
3530
3531 @c @subheading -trace-stop
3532
3533
3534 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3535 @node GDB/MI Variable Objects
3536 @section @sc{gdb/mi} Variable Objects
3537
3538
3539 @subheading Motivation for Variable Objects in @sc{gdb/mi}
3540
3541 For the implementation of a variable debugger window (locals, watched
3542 expressions, etc.), we are proposing the adaptation of the existing code
3543 used by @code{Insight}.
3544
3545 The two main reasons for that are:
3546
3547 @enumerate 1
3548 @item
3549 It has been proven in practice (it is already on its second generation).
3550
3551 @item
3552 It will shorten development time (needless to say how important it is
3553 now).
3554 @end enumerate
3555
3556 The original interface was designed to be used by Tcl code, so it was
3557 slightly changed so it could be used through @sc{gdb/mi}.  This section
3558 describes the @sc{gdb/mi} operations that will be available and gives some
3559 hints about their use.
3560
3561 @emph{Note}: In addition to the set of operations described here, we
3562 expect the @sc{gui} implementation of a variable window to require, at
3563 least, the following operations:
3564
3565 @itemize @bullet
3566 @item @code{-gdb-show} @code{output-radix}
3567 @item @code{-stack-list-arguments}
3568 @item @code{-stack-list-locals}
3569 @item @code{-stack-select-frame}
3570 @end itemize
3571
3572 @subheading Introduction to Variable Objects in @sc{gdb/mi}
3573
3574 @cindex variable objects in @sc{gdb/mi}
3575 The basic idea behind variable objects is the creation of a named object
3576 to represent a variable, an expression, a memory location or even a CPU
3577 register.  For each object created, a set of operations is available for
3578 examining or changing its properties.
3579
3580 Furthermore, complex data types, such as C structures, are represented
3581 in a tree format.  For instance, the @code{struct} type variable is the
3582 root and the children will represent the struct members.  If a child
3583 is itself of a complex type, it will also have children of its own.
3584 Appropriate language differences are handled for C, C@t{++} and Java.
3585
3586 When returning the actual values of the objects, this facility allows
3587 for the individual selection of the display format used in the result
3588 creation.  It can be chosen among: binary, decimal, hexadecimal, octal
3589 and natural.  Natural refers to a default format automatically
3590 chosen based on the variable type (like decimal for an @code{int}, hex
3591 for pointers, etc.).
3592
3593 The following is the complete set of @sc{gdb/mi} operations defined to
3594 access this functionality:
3595
3596 @multitable @columnfractions .4 .6
3597 @item @strong{Operation}
3598 @tab @strong{Description}
3599
3600 @item @code{-var-create}
3601 @tab create a variable object
3602 @item @code{-var-delete}
3603 @tab delete the variable object and its children
3604 @item @code{-var-set-format}
3605 @tab set the display format of this variable
3606 @item @code{-var-show-format}
3607 @tab show the display format of this variable
3608 @item @code{-var-info-num-children}
3609 @tab tells how many children this object has
3610 @item @code{-var-list-children}
3611 @tab return a list of the object's children
3612 @item @code{-var-info-type}
3613 @tab show the type of this variable object
3614 @item @code{-var-info-expression}
3615 @tab print what this variable object represents
3616 @item @code{-var-show-attributes}
3617 @tab is this variable editable? does it exist here?
3618 @item @code{-var-evaluate-expression}
3619 @tab get the value of this variable
3620 @item @code{-var-assign}
3621 @tab set the value of this variable
3622 @item @code{-var-update}
3623 @tab update the variable and its children
3624 @end multitable
3625
3626 In the next subsection we describe each operation in detail and suggest
3627 how it can be used.
3628
3629 @subheading Description And Use of Operations on Variable Objects
3630
3631 @subheading The @code{-var-create} Command
3632 @findex -var-create
3633
3634 @subsubheading Synopsis
3635
3636 @example
3637  -var-create @{@var{name} | "-"@}
3638     @{@var{frame-addr} | "*"@} @var{expression}
3639 @end example
3640
3641 This operation creates a variable object, which allows the monitoring of
3642 a variable, the result of an expression, a memory cell or a CPU
3643 register.
3644
3645 The @var{name} parameter is the string by which the object can be
3646 referenced.  It must be unique.  If @samp{-} is specified, the varobj
3647 system will generate a string ``varNNNNNN'' automatically.  It will be
3648 unique provided that one does not specify @var{name} on that format.
3649 The command fails if a duplicate name is found.
3650
3651 The frame under which the expression should be evaluated can be
3652 specified by @var{frame-addr}.  A @samp{*} indicates that the current
3653 frame should be used.
3654
3655 @var{expression} is any expression valid on the current language set (must not
3656 begin with a @samp{*}), or one of the following:
3657
3658 @itemize @bullet
3659 @item
3660 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
3661
3662 @item
3663 @samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
3664
3665 @item
3666 @samp{$@var{regname}} --- a CPU register name
3667 @end itemize
3668
3669 @subsubheading Result
3670
3671 This operation returns the name, number of children and the type of the
3672 object created.  Type is returned as a string as the ones generated by
3673 the @value{GDBN} CLI:
3674
3675 @example
3676  name="@var{name}",numchild="N",type="@var{type}"
3677 @end example
3678
3679
3680 @subheading The @code{-var-delete} Command
3681 @findex -var-delete
3682
3683 @subsubheading Synopsis
3684
3685 @example
3686  -var-delete @var{name}
3687 @end example
3688
3689 Deletes a previously created variable object and all of its children.
3690
3691 Returns an error if the object @var{name} is not found.
3692
3693
3694 @subheading The @code{-var-set-format} Command
3695 @findex -var-set-format
3696
3697 @subsubheading Synopsis
3698
3699 @example
3700  -var-set-format @var{name} @var{format-spec}
3701 @end example
3702
3703 Sets the output format for the value of the object @var{name} to be
3704 @var{format-spec}.
3705
3706 The syntax for the @var{format-spec} is as follows:
3707
3708 @example
3709  @var{format-spec} @expansion{}
3710  @{binary | decimal | hexadecimal | octal | natural@}
3711 @end example
3712
3713
3714 @subheading The @code{-var-show-format} Command
3715 @findex -var-show-format
3716
3717 @subsubheading Synopsis
3718
3719 @example
3720  -var-show-format @var{name}
3721 @end example
3722
3723 Returns the format used to display the value of the object @var{name}.
3724
3725 @example
3726  @var{format} @expansion{}
3727  @var{format-spec}
3728 @end example
3729
3730
3731 @subheading The @code{-var-info-num-children} Command
3732 @findex -var-info-num-children
3733
3734 @subsubheading Synopsis
3735
3736 @example
3737  -var-info-num-children @var{name}
3738 @end example
3739
3740 Returns the number of children of a variable object @var{name}:
3741
3742 @example
3743  numchild=@var{n}
3744 @end example
3745
3746
3747 @subheading The @code{-var-list-children} Command
3748 @findex -var-list-children
3749
3750 @subsubheading Synopsis
3751
3752 @example
3753  -var-list-children @var{name}
3754 @end example
3755
3756 Returns a list of the children of the specified variable object:
3757
3758 @example
3759  numchild=@var{n},children=@{@{name=@var{name},
3760  numchild=@var{n},type=@var{type}@},@r{(repeats N times)}@}
3761 @end example
3762
3763
3764 @subheading The @code{-var-info-type} Command
3765 @findex -var-info-type
3766
3767 @subsubheading Synopsis
3768
3769 @example
3770  -var-info-type @var{name}
3771 @end example
3772
3773 Returns the type of the specified variable @var{name}.  The type is
3774 returned as a string in the same format as it is output by the
3775 @value{GDBN} CLI:
3776
3777 @example
3778  type=@var{typename}
3779 @end example
3780
3781
3782 @subheading The @code{-var-info-expression} Command
3783 @findex -var-info-expression
3784
3785 @subsubheading Synopsis
3786
3787 @example
3788  -var-info-expression @var{name}
3789 @end example
3790
3791 Returns what is represented by the variable object @var{name}:
3792
3793 @example
3794  lang=@var{lang-spec},exp=@var{expression}
3795 @end example
3796
3797 @noindent
3798 where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
3799
3800 @subheading The @code{-var-show-attributes} Command
3801 @findex -var-show-attributes
3802
3803 @subsubheading Synopsis
3804
3805 @example
3806  -var-show-attributes @var{name}
3807 @end example
3808
3809 List attributes of the specified variable object @var{name}:
3810
3811 @example
3812  status=@var{attr} [ ( ,@var{attr} )* ]
3813 @end example
3814
3815 @noindent
3816 where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
3817
3818 @subheading The @code{-var-evaluate-expression} Command
3819 @findex -var-evaluate-expression
3820
3821 @subsubheading Synopsis
3822
3823 @example
3824  -var-evaluate-expression @var{name}
3825 @end example
3826
3827 Evaluates the expression that is represented by the specified variable
3828 object and returns its value as a string in the current format specified
3829 for the object:
3830
3831 @example
3832  value=@var{value}
3833 @end example
3834
3835 Note that one must invoke @code{-var-list-children} for a variable
3836 before the value of a child variable can be evaluated.
3837
3838 @subheading The @code{-var-assign} Command
3839 @findex -var-assign
3840
3841 @subsubheading Synopsis
3842
3843 @example
3844  -var-assign @var{name} @var{expression}
3845 @end example
3846
3847 Assigns the value of @var{expression} to the variable object specified
3848 by @var{name}.  The object must be @samp{editable}.  If the variable's
3849 value is altered by the assign, the variable will show up in any
3850 subsequent @code{-var-update} list.
3851
3852 @subsubheading Example
3853
3854 @example
3855 (@value{GDBP})
3856 -var-assign var1 3
3857 ^done,value="3"
3858 (@value{GDBP})
3859 -var-update *
3860 ^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}]
3861 (@value{GDBP})
3862 @end example
3863
3864 @subheading The @code{-var-update} Command
3865 @findex -var-update
3866
3867 @subsubheading Synopsis
3868
3869 @example
3870  -var-update @{@var{name} | "*"@}
3871 @end example
3872
3873 Update the value of the variable object @var{name} by evaluating its
3874 expression after fetching all the new values from memory or registers.
3875 A @samp{*} causes all existing variable objects to be updated.