gdb/mi/gdbmi.texinfo

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