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