gdb/mi/gdbmi.texinfo

   1 \input texinfo   @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename gdbmi.info
   4 @settitle GDB/MI Machine Interface
   5 @setchapternewpage off
   6 @c %**end of header
   7
   8 @ifinfo
   9 This file documents GDB/MI, a Machine Interface to GDB.
  10
  11 Copyright (C) 2000, Free Software Foundation, Inc.
  12 Contributed by Cygnus Solutions.
  13
  14 Permission is granted to make and distribute verbatim copies of this
  15 manual provided the copyright notice and this permission notice are
  16 preserved on all copies.
  17
  18 @ignore
  19 Permission is granted to process this file through TeX and print the
  20 results, provided the printed document carries copying permission notice
  21 identical to this one except for the removal of this paragraph (this
  22 paragraph not being relevant to the printed manual).
  23
  24 @end ignore
  25 Permission is granted to copy and distribute modified versions of this
  26 manual under the conditions for verbatim copying, provided also that the
  27 entire resulting derived work is distributed under the terms of a
  28 permission notice identical to this one.
  29
  30 Permission is granted to copy and distribute translations of this manual
  31 into another language, under the above conditions for modified versions.
  32 @end ifinfo
  33
  34 @c  This title page illustrates only one of the
  35 @c  two methods of forming a title page.
  36
  37 @titlepage
  38 @title GDB/MI
  39 @subtitle Version 0.2
  40 @subtitle Feb 2000
  41 @author Andrew Cagney, Fernando Nasser and Elena Zannoni
  42
  43 @c  The following two commands
  44 @c  start the copyright page.
  45 @page
  46 @vskip 0pt plus 1filll
  47 Permission is granted to make and distribute verbatim copies of this
  48 manual provided the copyright notice and this permission notice are
  49 preserved on all copies.
  50
  51 Copyright @copyright{} 2000, Free Software Foundation, Inc.
  52 @end titlepage
  53
  54 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  55 @chapter Overview
  56
  57 @heading Function and Purpose
  58
  59 GDB/MI is a line based machine oriented text interface to GDB.  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 @heading This Document
  64
  65 This document is a specification of the GDB/MI interface.  It is written
  66 in the form of a reference manual.
  67
  68 @heading Terminology
  69
  70 @heading Dependencies
  71
  72 @heading Acknowledgments
  73
  74 In alphabetic order: Fernando Nasser, Stan Shebs and Elena Zannoni.
  75
  76 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  77 @chapter Command Syntax
  78
  79 @section Input Syntax
  80
  81 @table @code
  82
  83 @item <command> @expansion{}
  84 <cli-command> | <mi-command>
  85
  86 @item <cli-command> @expansion{}
  87 [ <token> ] "any existing GDB CLI command" <nl>
  88
  89 @item <mi-command> @expansion{}
  90 [ <token> ] ``-'' <operation> ( `` '' <option> )* [ `` --'' ] ( `` '' <parameter> )* <nl>
  91
  92 @item <token> @expansion{}
  93 ``any sequence of digits''
  94
  95 @item <option> @expansion{}
  96 ``-'' <parameter> [ `` '' <parameter> ]
  97
  98 @item <parameter> @expansion{}
  99 <non-blank-sequence> | <c-string>
 100
 101 @item <operation> @expansion{}
 102 any of the operations described in this document.
 103
 104 @item <non-blank-sequence> @expansion{}
 105 anything provided it doesn't contain special characters such as ``-''
 106  <nl>, ``"'' and of course `` ''.
 107
 108 @item <c-string> @expansion{}
 109 ``"'' <seven-bit-iso-c-string-content> ``"''
 110
 111 @item <nl> @expansion{}
 112 CR | CR-LF
 113
 114 @end table
 115
 116 Notes:
 117
 118 @itemize @bullet
 119
 120 @item
 121 The CLI commands are still handled by the MI interpreter; their output
 122 is described below
 123
 124 @item
 125 The @code{<token>}, when present, is passed back when the command
 126 finishes.
 127
 128 @item
 129 Some mi commands accept optional arguments as part of the parameter
 130 list. Each option is identified by a leading @code{-} (dash) and may be
 131 followed by an option argument parameter.  Options occure first in the
 132 parameter list and can be delimiated from normal parameters using
 133 @code{--}.
 134
 135 @end itemize
 136
 137 Pragmatics:
 138
 139 @itemize @bullet
 140
 141 @item
 142 We want easy access to the existing CLI syntax (for debugging).
 143
 144 @item
 145 We want it easy to spot a MI operation
 146
 147 @end itemize
 148
 149 @section Output Syntax
 150
 151 The output from GDB/MI consists of zero or more out-of-band records
 152 followed, optionally, by a single result record.  The result record
 153 being for the most recent command.  The sequence of output records is
 154 terminated by ``(gdb)''.
 155
 156 If an input command was prefixed with a @code{<token>} then the
 157 corresponding output for that command will also be prefixed by that same
 158 token.
 159
 160 @table @code
 161 @item <output> @expansion{}
 162 ( <out-of-band-record> )* [ <result-record> ] ``(gdb)'' <nl>
 163
 164 @item <result-record> @expansion{}
 165 [ <token> ] ``^'' <result-class> ( ``,'' <result> )* <nl>
 166
 167 @item <out-of-band-record> @expansion{}
 168 <async-record> | <stream-record>
 169
 170 @item <async-record> @expansion{}
 171 <exec-async-output> | <status-async-output> | <notify-async-output>
 172
 173 @item <exec-async-output> @expansion{}
 174 [ <token> ] ``*'' <async-output>
 175
 176 @item <status-async-output> @expansion{}
 177 [ <token> ] ``+'' <async-output>
 178
 179 @item <notify-async-output> @expansion{}
 180 [ <token> ] ``='' <async-output>
 181
 182 @item <async-output> @expansion{}
 183 <async-class> ( ``,'' <result> )* <nl>
 184
 185 @item <result-class> @expansion{}
 186 ``done'' | ``running'' | ``connected'' | ``error'' | ``exit''
 187
 188 @item <async-class> @expansion{}
 189 ``stopped'' | others (depending on needs, still in development)
 190
 191 @item <result> @expansion{}
 192 [ <string> ``='' ] <value>
 193
 194 @item <value> @expansion{}
 195 <const> | ``@{'' <result> ( ``,'' <result> )* ``@}''
 196
 197 @item <const> @expansion{}
 198 <c-string>
 199
 200 @item <stream-record> @expansion{}
 201 <console-stream-output> | <target-stream-output> | <log-stream-output>
 202
 203 @item <console-stream-output> @expansion{}
 204 ``~'' <c-string>
 205
 206 @item <target-stream-output> @expansion{}
 207 ``@@'' <c-string>
 208
 209 @item <log-stream-output> @expansion{}
 210 ``&'' <c-string>
 211
 212 @item <nl> @expansion{}
 213 CR | CR-LF
 214
 215 @item <token> @expansion{}
 216 ``any sequence of digits''
 217
 218 @end table
 219
 220 In addition, the following are still being developed.
 221
 222 @table @code
 223
 224 @item <query>
 225 This action is currently undefined.
 226
 227 @end table
 228
 229 Notes:
 230
 231 @itemize @bullet
 232
 233 @item
 234 All output sequences end in a single line containing a period.
 235
 236 @item
 237 The @code{<token>} is from the corresponding request.  If an execution
 238 command is interrupted by the -exec-interrupt command, the token
 239 associated with the `*stopped' message is the one of the original
 240 execution command, not the one of the interrupt-command.
 241
 242 @item
 243 <status-async-output> contains on-going status information about the progress
 244 of a slow operation.  It can be discarded. All status output is prefixed by
 245 the prefix `+'.
 246
 247 @item
 248 <exec-async-output> contains asynchronous state change on the target
 249 (stopped, started, disappeared). All async output is prefixed by
 250 the prefix `*'.
 251
 252 @item
 253 <notify-async-output> contains supplementary information that the client should
 254 handle (new breakpoint information). All notify output is prefixed by
 255 the prefix `='.
 256
 257 @item
 258 <console-stream-output> is output that should be displayed as is in the
 259 console.  It is the textual response to a CLI command. All the console
 260 output is prefixed by the prefix ``~''.
 261
 262 @item
 263 <target-stream-output> is the output produced by the target program.
 264 All the target output is prefixed by the prefix ``@@''.
 265
 266 @item
 267 <log-stream-output> is output text coming from GDB's internals, for
 268 instance messages that should be displayed as part of an error log.  All
 269 the log output is prefixed by the prefix ``&''.
 270
 271 @end itemize
 272
 273 @section Simple Examples
 274
 275 @subheading Target stop:
 276
 277 @example
 278 -> -stop
 279 <- (gdb)
 280 @end example
 281
 282 (later)
 283
 284 @example
 285 <- *stop,reason="stop",address="0x123",source="a.c:123"
 286 <- (gdb)
 287 @end example
 288
 289
 290 @subheading Simple CLI command being passed through the MI and on to the CLI.
 291
 292 @example
 293 -> print 1+2
 294 <- ~3\n
 295 <- (gdb)
 296 @end example
 297
 298
 299 @subheading Command with side effects:
 300
 301 @example
 302 -> -symbol-file xyz.exe
 303 <- *breakpoint,nr="3",address="0x123",source="a.c:123"
 304 <- (gdb)
 305 @end example
 306
 307
 308 @subheading A bad command:
 309
 310 @example
 311 -> -rubbish
 312 <- error,"Rubbish not found"
 313 <- (gdb)
 314 @end example
 315
 316 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 317 @chapter CLI compatibility
 318
 319 To help users familiar with the GDB's existing CLI interface, the GDB/MI
 320 will accept existing CLI commands.  As specified by the syntax, such
 321 commands can be directly entered into the MI interface and GDB will
 322 respond.
 323
 324 The mechanism is provided as an aid to developers of MI clients and not
 325 as a reliable interface into the CLI.  Since the command is being
 326 interpreteted in an environment that assumes MI behaviour the exact
 327 output of such commands is likely to end up being an un-supported hybrid
 328 of MI and CLI output.
 329
 330
 331 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 332 @chapter Output Records
 333
 334 @section Result Records
 335
 336 In addition to a number of out-of-band notifications the response to an
 337 MI command includes one of the following result indications.
 338
 339 @table @code
 340
 341 @item ``^done'' [ ``,'' <results> ]
 342 The synchronous operation was successful, @code{<results>} is the return
 343 value.
 344
 345 @item ``^running''
 346 The asynchronous operation was successfully started.  The target is
 347 running.  @emph{Is this one correct should it be an out-of-band
 348 notification?}
 349
 350 @item ``^error'' ``,'' <c-string>
 351 The operation failed.  The @code{<c-string>} contains the corresponding
 352 error message.
 353
 354 @end table
 355
 356 @section Stream Records
 357
 358 GDB internally maintains a number of output streams: the console, the
 359 target, and the log.  The output intended for each of these streams is
 360 tunneled through the MI interface using stream records.
 361
 362 In addition to the prefix each stream record contains a
 363 @code{<string-output>}.  This is either raw text (with an implicit new
 364 line) or a quoted C string (which does not contain an implicit newline).
 365
 366 @table @code
 367
 368 @item ``~'' <string-output>
 369 The console output stream contains text that should be displayed in the
 370 CLI console window.  It contains the textual responses to CLI commands.
 371
 372 @item ``@@'' <string-output>
 373 The target output stream contains any textual output from the running
 374 target.
 375
 376 @item ``&'' <string-output>
 377 The LOG stream contains debugging messages being produced by GDB's
 378 internals.
 379
 380 @end table
 381
 382 @section Out-of-band Records.
 383
 384 Out-of-band records are used to notify the MI client of additional
 385 changes that have occurred.  Those changes can either be a consequence of
 386 an MI (breakpoint modified) or as a result of target activity (target
 387 stopped).
 388
 389 The following is a preliminary list of possible out-of-band records.
 390
 391 @table @code
 392
 393 @item ``*'' ``stop''
 394
 395 @end table
 396
 397
 398 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 399 @chapter Command Description Format
 400
 401 The remaining chapters describe blocks of commands.  Each block of
 402 commands is laid out in a fashion similar to this chapter.
 403
 404 Note the the line breaks shown in the examples are here only for
 405 readability. They don't appear in the real output.
 406 Note that the commands with a non available example (N.A.) are not yet
 407 implemented.
 408
 409 @section Motivation
 410
 411 What motivates the collection of commands
 412
 413 @section Introduction
 414
 415 Brief introduction to the commands as a whole.
 416
 417 @section Operations
 418
 419 @subsection -command <args>...
 420
 421 @subsubsection Result
 422
 423 @subsubsection Out-of-band
 424
 425 @subsubsection Notes
 426
 427 @subsubsection Example
 428
 429
 430 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 431 @chapter Breakpoint table commands
 432
 433 @section -break-after <number> <count>
 434 The breakpoint number <number> is not in effect until it has been hit <count> times.
 435 Note how this is reflected in the output of the -break-list command.
 436
 437 @subsection GDB command
 438 ignore
 439
 440 @subsection Example
 441 @example
 442 (gdb)
 443 -break-insert main
 444 ^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@}
 445 (gdb)
 446 -break-after 1 3
 447 ~
 448 ^done
 449 (gdb)
 450 -break-list
 451 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
 452 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
 453 addr="0x000100d0",func="main",file="hello.c",line="5",times="0",ignore="3"@}@}
 454 (gdb)
 455 @end example
 456
 457 @c @section -break-catch
 458
 459 @c @section -break-commands
 460
 461 @section -break-condition <number> <expr>
 462 Breakpoint <number> will stop the program only if the condition in <expr> is true.
 463 The condition becomes part of the -break-list output.
 464 @subsection GDB command
 465 condition
 466 @subsection Example
 467 @example
 468 (gdb)
 469 -break-condition 1 1
 470 ^done
 471 (gdb)
 472 -break-list
 473 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
 474 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
 475 addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",times="0",ignore="3"@}@}
 476 (gdb)
 477 @end example
 478
 479 @section -break-delete @{ <breakpoint> @}+
 480 Delete the breakpoint(s) specified in the argument list. This is
 481 obviously reflected in the breakpoint list.
 482 @subsection GDB command
 483 delete
 484 @subsection Example
 485 @example
 486 (gdb)
 487 -break-delete 1
 488 ^done
 489 (gdb)
 490 -break-list
 491 ^done,BreakpointTable=@{@}
 492 (gdb)
 493 @end example
 494
 495 @section -break-disable @{ <breakpoint> @}+
 496 Disable the breakpoint(s). Note how the field 'enabled' in the break
 497 list is now set to 'n'.
 498 @subsection GDB command
 499 disable
 500 @subsection Example
 501 @example
 502 (gdb)
 503 -break-disable 2
 504 ^done
 505 (gdb)
 506 -break-list
 507 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
 508 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
 509 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
 510 (gdb)
 511 @end example
 512
 513 @section -break-enable @{ <breakpoint> @}+
 514 Enable a previously disabled breakpoint(s).
 515 @subsection GDB command
 516 enable
 517 @subsection Example
 518 @example
 519 (gdb)
 520 enable 2
 521 ^done
 522 (gdb)
 523 -break-list
 524 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
 525 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
 526 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
 527 (gdb)
 528 @end example
 529
 530 @section -break-info <breakpoint>
 531 REDUNDANT??? Get information about a single breakpoint.
 532 @subsection GDB command
 533 @subsection Example
 534 N.A.
 535
 536 @section -break-insert [ "-t" ] [ "-h" ] [ "-r" ] [ "-c" <condition> ] [ "-i" <ignore-count> ] [ "-p" <thread> ] [ <line> | <addr> ]
 537
 538 <line>, if specified, accordingly to the gdb manual can be one of:
 539 @itemize @bullet
 540 @item function
 541 @c @item +offset
 542 @c @item -offset
 543 @c @item linenum
 544 @item filename:linenum
 545 @item filename:function
 546 @item *address
 547 @end itemize
 548
 549 The possible forms of this command are:
 550
 551 @table @samp
 552 @item -t
 553 Insert a tempoary breakpoint.
 554 @item -h
 555 Insert a hardware breakpoint.
 556 @item -c <condition>
 557 Make the breakpoint conditional on <condition>
 558 @item -i <ignore-count>
 559 Initialize the <ignore-count>
 560 @item -r
 561 Insert a regular breakpoint in all the functions whose names match the
 562 given regular expression.  Other flags are not applicable to regular
 563 expresson.
 564 @end table
 565
 566
 567 The result is in the form:
 568
 569 ^done,bkptno="<gdb number for this breakpoint>",func="<name of the
 570 function where the breakpoint was inserted>",file="<source file which
 571 contains this function>",line="<source line number within the file>"
 572
 573 Note: this is open to change.  An out-of-band breakpoint instead of part
 574 of the result?
 575 @subsection GDB command
 576 break, tbreak, hbreak, thbreak, rbreak.
 577 @subsection Example
 578 @example
 579 (gdb)
 580 -break-insert main
 581 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
 582 (gdb)
 583 -break-insert -t foo
 584 ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
 585 (gdb)
 586 -break-list
 587 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
 588 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",addr="0x0001072c",
 589 func="main",file="recursive2.c",line="4",times="0"@},
 590 bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",addr="0x00010774",
 591 func="foo",file="recursive2.c",line="11",times="0"@}@}
 592 (gdb)
 593 -break-insert -r foo.*
 594 ~int foo(int, int);
 595 ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
 596 (gdb)
 597 @end example
 598
 599 @section -break-list
 600 Displays the list of inserted breakpoints, showing the following fields:
 601 @table @samp
 602 @item Number
 603 Number of the breakpoint
 604 @item Type
 605 Type of the breakpoint: breakpoint or watchpoint
 606 @item Disposition
 607 Should the breakpoint be deleted or disabled when it is hit: keep or nokeep
 608 @item Enabled
 609 Is the breakpoint enabled or no: y or n
 610 @item Address
 611 Memory location at which the breakpoint is set.
 612 @item What
 613 Logical location of the breakpoint, expressed by function name, file name, line number.
 614 @item times
 615 Number of times the breakpoint has been hit.
 616 @end table
 617
 618 If there are no breakpoints or watchpoints, the BreakpointTable field is
 619 an empty list.
 620 @subsection GDB command
 621 info break
 622
 623 @subsection Example 1
 624 @example
 625 (gdb)
 626 -break-list
 627 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
 628 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
 629 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
 630 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
 631 addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}@}
 632 (gdb)
 633 @end example
 634 @subsection Example 2
 635 @example
 636 (gdb)
 637 -break-list
 638 ^done,BreakpointTable=@{@}
 639 (gdb)
 640 @end example
 641
 642 @section -break-watch [ "-a" | "-r" ]
 643 Create a watchpoint.  With the ``-a'' option it will create an access
 644 watchpoint, i.e. a watchpoints that triggers either on a read or on a
 645 write on the memory location.  With the ``-r'' option, the watchoint
 646 created is a read watchpoint, i.e. it will trigger only when the memory
 647 location os accessed for reading.  Without either of the options, the
 648 watchpoint created is a regular watchpoint, i.e. it will trigger whe the
 649 memory location is accessed for writing.
 650
 651 Note that ``-break-list'' will report a single list of watchpoints and
 652 breakpoints inserted.
 653
 654 @subsection GDB command
 655 watch, awatch, rwatch
 656
 657 @subsection Example 1
 658 Watchpoint on a variable in main().
 659 @example
 660 (gdb)
 661 -break-watch x
 662 ^done,wpt=@{number="2",exp="x"@}
 663 (gdb)
 664 -exec-continue
 665 ^running
 666 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
 667 value=@{old="-268439212",new="55"@},
 668 frame=@{func="main",args=@{@},file="recursive2.c",line="5"@}
 669 (gdb)
 670 @end example
 671 @subsection Example 2
 672 Watchpoint on a variable local to a function. Gdb will stop the program execution
 673 twice: first for the variable changing value, then for the watchpoint going out of scope.
 674 @example
 675 (gdb)
 676 -break-watch C
 677 ^done,wpt=@{number="5",exp="C"@}
 678 (gdb)
 679 -exec-continue
 680 ^running
 681 ^done,reason="watchpoint-trigger",
 682 wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
 683 frame=@{func="callee4",args=@{@},file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
 684 line="13"@}
 685 (gdb)
 686 -exec-continue
 687 ^running
 688 ^done,reason="watchpoint-scope",wpnum="5",
 689 frame=@{func="callee3",args=@{@{name="strarg",value="0x11940 \"A string argument.\""@}@},
 690 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
 691 (gdb)
 692 @end example
 693
 694 @subsection Example 3
 695 Listing breakpoints and watchpoints, at different points in the program execution.
 696 Note that once the watchpoint goes out of scope, it is deleted.
 697 @example
 698 (gdb)
 699 -break-watch C
 700 ^done,wpt=@{number="2",exp="C"@}
 701 (gdb)
 702 -break-list
 703 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
 704 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",addr="0x00010734",
 705 func="callee4",
 706 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
 707 bkpt=@{number="2",type="watchpoint",disp="keep",
 708 enabled="y",addr="",what="C",times="0"@}@}
 709 (gdb)
 710 -exec-continue
 711 ^running
 712 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
 713 value=@{old="-276895068",new="3"@},
 714 frame=@{func="callee4",args=@{@},
 715 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
 716 (gdb)
 717 -break-list
 718 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
 719 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",addr="0x00010734",
 720 func="callee4",
 721 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
 722 bkpt=@{number="2",type="watchpoint",disp="keep",
 723 enabled="y",addr="",what="C",times="-5"@}@}
 724 (gdb)
 725 -exec-continue
 726 ^running
 727 ^done,reason="watchpoint-scope",wpnum="2",
 728 frame=@{func="callee3",args=@{@{name="strarg",value="0x11940 \"A string argument.\""@}@},
 729 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
 730 (gdb)
 731 -break-list
 732 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
 733 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",addr="0x00010734",
 734 func="callee4",
 735 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}@}
 736 (gdb)
 737 @end example
 738 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 739 @chapter Data manipulation
 740
 741 @c REMOVED FROM THE ITNERFACE.
 742 @c @section -data-assign
 743 @c Change the value of a program variable. Plenty of side effects.
 744 @c @subsection GDB command
 745 @c set variable
 746 @c @subsection Example
 747 @c N.A.
 748
 749 @section -data-disassemble ( -s <start-addr> -e <end-addr> ) | (-f <filename> -l <linenum> [-n <lines> ]] -- <mode>
 750 Where
 751 @table @samp
 752 @item <start-addr>
 753 Is the beginning address (or $pc).
 754 @item <end-addr>
 755 End address.
 756 @item <filename>
 757 Name of the file to disassemble.
 758 @item <linenum>
 759 Line number to disassemble around.
 760 @item <number-of-lines>
 761 specifies the number of disassembly lines to be produced. If it is -1
 762 the whole function will be disassembled, in case no <end> address is
 763 specified.  If <end> is specified as a non-zero value, and
 764 <number-of-lines> is lower that the number of disassembly lines between
 765 <begin> and <end>, we'll display only <number-of-lines> lines, vice
 766 versa if <number-of-lines> is higher than the number of lines between
 767 <begin> and <end>, we'll display only the lines up to <end>.
 768 @item <mode>
 769 can be 0 (only disassembly) or 1 (mixed source and disassembly).
 770 @end table
 771
 772 The output for each instruction is composed of two fields:
 773 @itemize @bullet
 774 @item Address
 775 @item Func-name
 776 @item Offset
 777 @item Instruction
 778 @end itemize
 779 Note that whatever included in the instruction field, is not manipulated
 780 directely by Flathead, i.e. it is not possible to adjust its format.
 781 @subsection GDB command
 782 N.A. No direct mapping.
 783
 784 @subsection Example 1
 785 Disassemble from the current PC value to PC + 20.
 786
 787 @example
 788 (gdb)
 789 -data-disassemble -s $pc -e "$pc + 20" -- 0
 790 ^done,
 791 asm_insns={
 792 {address="0x000107c0",func-name="main",offset="4",
 793 inst="mov  2, %o0"},
 794 {address="0x000107c4",func-name="main",offset="8",
 795 inst="sethi  %hi(0x11800), %o2"},
 796 {address="0x000107c8",func-name="main",offset="12",
 797 inst="or  %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},
 798 {address="0x000107cc",func-name="main",offset="16",
 799 inst="sethi  %hi(0x11800), %o2"},
 800 {address="0x000107d0",func-name="main",offset="20",
 801 inst="or  %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}}
 802 (gdb)
 803 @end example
 804
 805 @subsection Example 2
 806 Disassemble the whole function main. Line 32 is part of main.
 807 @example
 808 -data-disassemble -f basics.c -l 32 -- 0
 809 ^done,asm_insns={
 810 {address="0x000107bc",func-name="main",offset="0",inst="save  %sp, -112, %sp"},
 811 {address="0x000107c0",func-name="main",offset="4",inst="mov  2, %o0"},
 812 {address="0x000107c4",func-name="main",offset="8",inst="sethi  %hi(0x11800), %o2"},
 813 [...]
 814 {address="0x0001081c",func-name="main",offset="96",inst="ret "},
 815 {address="0x00010820",func-name="main",offset="100",inst="restore "}}
 816 (gdb)
 817 @end example
 818
 819 @subsection Example 3
 820 Disassemble 3 instruction from the start of main.
 821 @example
 822 (gdb)
 823 -data-disassemble -f basics.c -l 32 -n 3 -- 0
 824 ^done,asm_insns={
 825 {address="0x000107bc",func-name="main",offset="0",inst="save  %sp, -112, %sp"},
 826 {address="0x000107c0",func-name="main",offset="4",inst="mov  2, %o0"},
 827 {address="0x000107c4",func-name="main",offset="8",inst="sethi  %hi(0x11800), %o2"}}
 828 (gdb)
 829 @end example
 830
 831 @subsection Example 4
 832 Disassemble 3 instruction from the start of main in mixed mode.
 833 @example
 834 (gdb)
 835 -data-disassemble -f basics.c -l 32 -n 3 -- 1
 836 ^done,asm_insns={
 837 src_and_asm_line={line="31",
 838 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/testsuite/gdb.mi/basics.c",
 839 line_asm_insn={
 840 {address="0x000107bc",func-name="main",offset="0",inst="save  %sp, -112, %sp"}}},
 841
 842 src_and_asm_line={line="32",
 843 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/testsuite/gdb.mi/basics.c",
 844 line_asm_insn={
 845 {address="0x000107c0",func-name="main",offset="4",inst="mov  2, %o0"},
 846 {address="0x000107c4",func-name="main",offset="8",inst="sethi  %hi(0x11800), %o2"}}}}
 847 (gdb)
 848 @end example
 849
 850 @section -data-evaluate-expression
 851 Evaluate an expression. The expression could contain an inferior
 852 function call. The function call will execute synchronously.
 853 If the expression contains spaces, it must be enclosed in double quotes.
 854 @subsection GDB command
 855 print, output, gdb_eval
 856 @subsection Example
 857 @example
 858 211-data-evaluate-expression A
 859 211^done,value="1"
 860 (gdb)
 861 311-data-evaluate-expression &A
 862 311^done,value="0xefffeb7c"
 863 (gdb)
 864 411-data-evaluate-expression A+3
 865 411^done,value="4"
 866 (gdb)
 867 511-data-evaluate-expression "A + 3"
 868 511^done,value="4"
 869 (gdb)
 870 @end example
 871
 872 @section -data-list-changed-registers
 873 Display a list of the registers that have changed.
 874 @subsection GDB command
 875 gdb_changed_register_list. This is in gdbtk only.
 876 @subsection Example
 877 On a PPC MBX board.
 878 @example
 879 (gdb)
 880 -exec-continue
 881 ^running
 882
 883 (gdb)
 884 *stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
 885 args=@{@},file="try.c",line="5"@}
 886 (gdb)
 887 -data-list-changed-registers
 888 ^done,changed-registers=@{"0","1","2","4","5","6","7","8","9",
 889 "10","11","13","14","15","16","17","18","19","20","21","22","23",
 890 "24","25","26","27","28","30","31","64","65","66","67","69"@}
 891 (gdb)
 892 @end example
 893
 894 @section -data-list-register-names
 895 Show a list of register names for the current target.  If no arguments
 896 are given, it shows a list of the names of all the registers.  If
 897 integer numbers are given as arguments, it will print a list of the
 898 names corresponding to the arguments.
 899 @subsection GDB command
 900 gdb_regnames
 901 @subsection Example
 902 For the PPC MBX board:
 903 @example
 904 (gdb)
 905 -data-list-register-names
 906 ^done,register-names=@{"r0","r1","r2","r3","r4","r5","r6","r7",
 907 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
 908 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
 909 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
 910 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
 911 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
 912 "pc","ps","cr","lr","ctr","xer"@}
 913 (gdb)
 914 -data-list-register-names 1 2 3
 915 ^done,register-names=@{"r1","r2","r3"@}
 916 (gdb)
 917 @end example
 918
 919 @section -data-list-register-values
 920 Display the registers contents.  Arguments are the format according to
 921 which the registers contents are to be returned, and a list of numbers
 922 specifying the registers to display. A missing list of number indicates
 923 that the contents of all the registers must be returned.
 924 Allowed formats are:
 925 @itemize @bullet
 926 @item 'x': Hexadecimal
 927 @item 'o': Octal
 928 @item 't': Binary
 929 @item 'd': Decimal
 930 @item 'r': Raw
 931 @item 'N': Natural
 932 @end itemize
 933
 934 @subsection GDB command
 935 info reg, info all-reg  AND/OR gdb_fetch_registers
 936 @subsection Example
 937 For a PPC MBX board. Note, line breaks are for readability only, they
 938 don't appear in the actual output.
 939 @example
 940 (gdb)
 941 -data-list-register-values r 64 65
 942 ^done,register-values=@{@{number="64",value="0xfe00a300"@},
 943 @{number="65",value="0x00029002"@}@}
 944 (gdb)
 945 -data-list-register-values x
 946 ^done,register-values=@{@{number="0",value="0xfe0043c8"@},
 947 @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
 948 @{number="3",value="0x0"@},@{number="4",value="0xa"@},
 949 @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
 950 @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
 951 @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
 952 @{number="11",value="0x1"@},@{number="12",value="0x0"@},
 953 @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
 954 @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
 955 @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
 956 @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
 957 @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
 958 @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
 959 @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
 960 @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
 961 @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
 962 @{number="31",value="0x0"@},@{number="32",value="0x0"@},
 963 @{number="33",value="0x0"@},@{number="34",value="0x0"@},
 964 @{number="35",value="0x0"@},@{number="36",value="0x0"@},
 965 @{number="37",value="0x0"@},@{number="38",value="0x0"@},
 966 @{number="39",value="0x0"@},@{number="40",value="0x0"@},
 967 @{number="41",value="0x0"@},@{number="42",value="0x0"@},
 968 @{number="43",value="0x0"@},@{number="44",value="0x0"@},
 969 @{number="45",value="0x0"@},@{number="46",value="0x0"@},
 970 @{number="47",value="0x0"@},@{number="48",value="0x0"@},
 971 @{number="49",value="0x0"@},@{number="50",value="0x0"@},
 972 @{number="51",value="0x0"@},@{number="52",value="0x0"@},
 973 @{number="53",value="0x0"@},@{number="54",value="0x0"@},
 974 @{number="55",value="0x0"@},@{number="56",value="0x0"@},
 975 @{number="57",value="0x0"@},@{number="58",value="0x0"@},
 976 @{number="59",value="0x0"@},@{number="60",value="0x0"@},
 977 @{number="61",value="0x0"@},@{number="62",value="0x0"@},
 978 @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
 979 @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
 980 @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
 981 @{number="69",value="0x20002b03"@}@}
 982 (gdb)
 983 @end example
 984
 985 @section -data-read-memory [ -o <byte-offset> ] [ -- ] <address> <word-format> <word-size> <nr-rows> <nr-cols> [ <aschar> ]
 986 Where
 987 @table @samp
 988 @item <address>
 989 An expression specifying the address of the first memory word to be
 990 read.  Complex expressions containing embedded white space should be
 991 quoted using the C convention.
 992 @item <word-format>
 993 The format to be used to print the memory words.  The notation is the
 994 same as for GDB's @code{print} command.
 995 @item <word-size>
 996 The size of each memory word in bytes.
 997 @item <nr-rows>
 998 The number of rows in the output table.
 999 @item <nr-cols>
1000 The number of columns in the output table.
1001 @item <aschar>
1002 If present, indicates that each row should include an ascii dump.  The
1003 value of <aschar> is used as a padding character when a byte is not a
1004 member of the printable ascii character set (@code{<32} or @code{>126}).
1005 @item <byte-offset>
1006 An offset to add to the <address> before fetching memory.
1007 @end table
1008 Display memory contents as a table of <nr-rows> by <nr-cols> words.
1009 Each word being <word-size> bytes.  In total @code{<nr-rows> * <nr-cols>
1010 * <word-size>} bytes are read (returned as @code{total-bytes}.  Should
1011 less then the requested number of bytes be returned by the target, the
1012 missing words are identified using @code{N/A}.  The number of bytes read
1013 from the target is returned in @code{nr-bytes} and the starting address
1014 used to read memory by @code{addr}.
1015
1016 The address of the next/previous page or row is available in
1017 @code{next-row} and @code{prev-row}, @code{next-page} and
1018 @code{prev-page}.
1019 @subsection GDB command
1020 x AND/OR gdb_get_mem AND/OR GDBtk's memory read.
1021 @subsection Example 1
1022 Read six bytes of memory starting at @code{bytes+6} but then offset by
1023 @code{-6} bytes.  Format as three rows of two columns. One byte per
1024 word.  Display each word in hex.
1025 @example
1026 (gdb)
1027 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
1028 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
1029 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
1030 prev-page="0x0000138a",memory=@{
1031 @{addr="0x00001390",data=@{"0x00","0x01"@}@},
1032 @{addr="0x00001392",data=@{"0x02","0x03"@}@},
1033 @{addr="0x00001394",data=@{"0x04","0x05"@}@}@}
1034 (gdb)
1035 @end example
1036 @subsection Example 2
1037 Read two bytes of memory starting at address @code{shorts + 64} and
1038 display as a single word formatted in decimal.
1039 @example
1040 (gdb)
1041 5-data-read-memory shorts+64 d 2 1 1
1042 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
1043 next-row="0x00001512",prev-row="0x0000150e",
1044 next-page="0x00001512",prev-page="0x0000150e",memory=@{
1045 @{addr="0x00001510",data=@{"128"@}@}@}
1046 (gdb)
1047 @end example
1048 @subsection Example 3
1049 Read thirty two bytes of memory starting at @code{bytes+16} and format
1050 as eight rows of four columns.  Include a string encoding with @code{x}
1051 used as the non-printable character.
1052 @example
1053 (gdb)
1054 4-data-read-memory bytes+16 x 1 8 4 x
1055 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
1056 next-row="0x000013c0",prev-row="0x0000139c",
1057 next-page="0x000013c0",prev-page="0x00001380",memory=@{
1058 @{addr="0x000013a0",data=@{"0x10","0x11","0x12","0x13"@},ascii="xxxx"@},
1059 @{addr="0x000013a4",data=@{"0x14","0x15","0x16","0x17"@},ascii="xxxx"@},
1060 @{addr="0x000013a8",data=@{"0x18","0x19","0x1a","0x1b"@},ascii="xxxx"@},
1061 @{addr="0x000013ac",data=@{"0x1c","0x1d","0x1e","0x1f"@},ascii="xxxx"@},
1062 @{addr="0x000013b0",data=@{"0x20","0x21","0x22","0x23"@},ascii=" !\"#"@},
1063 @{addr="0x000013b4",data=@{"0x24","0x25","0x26","0x27"@},ascii="$%&'"@},
1064 @{addr="0x000013b8",data=@{"0x28","0x29","0x2a","0x2b"@},ascii="()*+"@},
1065 @{addr="0x000013bc",data=@{"0x2c","0x2d","0x2e","0x2f"@},ascii=",-./"@}@}
1066 (gdb)
1067 @end example
1068
1069 @section -display-delete <number>
1070 Delete the display <number>.
1071 @subsection GDB command
1072 delete display
1073 @subsection Example
1074 N.A.
1075
1076 @section -display-disable <number>
1077 Disable display <number>
1078 @subsection GDB command
1079 disable display
1080 @subsection Example
1081 N.A.
1082
1083 @section -display-enable <number>
1084 Enable display <number>
1085 @subsection GDB command
1086 enable display
1087 @subsection Example
1088 N.A.
1089
1090 @section -display-insert <expression>
1091 Display <expression> every time the program stops.
1092 @subsection GDB command
1093 display
1094 @subsection Example
1095 N.A.
1096
1097 @section -display-list
1098 List the displays. Do not show the current values.
1099 @subsection GDB command
1100 info display
1101 @subsection Example
1102 N.A.
1103
1104 @section -environment-cd <pathdir>
1105 Set GDB's working directory.
1106 @subsection GDB command
1107 cd
1108 @subsection Example
1109 @example
1110 (gdb)
1111 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1112 ^done
1113 (gdb)
1114 @end example
1115
1116 @section -environment-directory <pathdir>
1117 Add directory <pathdir> to beginning of search path for source files.
1118 @subsection GDB command
1119 dir
1120 @subsection Example
1121 @example
1122 (gdb)
1123 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1124 ^done
1125 (gdb)
1126 @end example
1127
1128 @section -environment-path @{ <pathdir> @}+
1129 Add directories to beginning of search path for object files.
1130 @subsection GDB command
1131 path
1132 @subsection Example
1133 @example
1134 (gdb)
1135 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
1136 ^done
1137 (gdb)
1138 @end example
1139
1140 @section -environment-pwd
1141 Show the current working directory
1142 @subsection GDB command
1143 pwd
1144 @subsection Example
1145 @example
1146 (gdb)
1147 -environment-pwd
1148 ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
1149 ^done
1150 (gdb)
1151 @end example
1152
1153 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1154 @chapter Program control
1155
1156 @section Program termination
1157 As a result of execution, the inferior program can run to completion, if
1158 it doesn't encouter any breakpoints.  In this case the ouput will
1159 include an exit code, if the program has exited exceptionally.
1160 @subsection Example 1
1161 Program exited normally:
1162 @example
1163 (gdb)
1164 -exec-run
1165 ^running
1166 (gdb)
1167 x = 55
1168 *stopped,reason="exited-normally"
1169 (gdb)
1170 @end example
1171
1172 @subsection Example 2
1173 Program exited exceptionally:
1174 @example
1175 (gdb)
1176 -exec-run
1177 ^running
1178 (gdb)
1179 x = 55
1180 *stopped,reason="exited",exit-code="01"
1181 (gdb)
1182 @end example
1183
1184 Another way the program can terminate is if it receives a signal like SIGINT.
1185 @subsection Example
1186 Program exited with signal (for a more complete example, see the exec-interrupt command).
1187 @example
1188 (gdb)
1189 *stopped,reason="exited-signalled",signal-name="SIGINT",signal-meaning="Interrupt"
1190 @end example
1191
1192
1193 @section -exec-abort
1194 Kill the inferior running program.
1195
1196 @subsection GDB command
1197 kill
1198
1199 @subsection Example
1200 N.A.
1201
1202 @section -exec-arguments
1203 Set the inferior program arguments, to be used in the next -exec-run.
1204
1205 @subsection GDB command
1206 set args
1207
1208 @subsection Example
1209 Don't have it around.
1210
1211 @section -exec-continue
1212 Asynchronous command. Resumes the execution of the inferior program until
1213 a breakpoint is encountered, or the inferior exits.
1214
1215 @subsection GDB command
1216 continue
1217
1218 @subsection Example
1219 @example
1220 -exec-continue
1221 ^running
1222 (gdb)
1223 @@Hello world
1224 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=@{@},
1225 file="hello.c",line="13"@}
1226 (gdb)
1227 @end example
1228
1229 @section -exec-finish
1230 Asynchronous command. Resumes the execution of the inferior program until the
1231 current function is exited. Displays the results returned by the function (???).
1232
1233 @subsection GDB command
1234 finish
1235
1236 @subsection Example 1
1237 Function returning 'void'.
1238 @example
1239 -exec-finish
1240 ^running
1241 (gdb)
1242 @@hello from foo
1243 *stopped,reason="function-finished",frame=@{func="main",args=@{@},
1244 file="hello.c",line="7"@}
1245 (gdb)
1246 @end example
1247 @subsection Example 2
1248 Function returning other than 'void'. The name of the internal gdb variable storing the
1249 result is printed, and the value itself.
1250 @example
1251 -exec-finish
1252 ^running
1253 (gdb)
1254 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
1255 args=@{@{name="a",value="1"@},@{name="b",value="9"@}@},file="recursive2.c",line="14"@},
1256 gdb-result-var="$1",return-value="0"
1257 (gdb)
1258
1259 @end example
1260 @section -exec-interrupt
1261 Asynchronous command. Interrupts the background execution of the target.
1262 Note how the token associated with the stop message is the one for the
1263 execution command that has been interrupted. The token for the interrupt
1264 itself only appears in the '^done' output.  If the user is trying to
1265 interrupt a non running program, an error message will be printed.
1266 @subsection GDB command
1267 interrupt
1268
1269 @subsection Example
1270 @example
1271 (gdb)
1272 111-exec-continue
1273 111^running
1274
1275 (gdb)
1276 222-exec-interrupt
1277 222^done
1278 (gdb)
1279 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1280 frame=@{addr="0x00010140",func="foo",args=@{@},file="try.c",line="13"@}
1281 (gdb)
1282
1283 (gdb)
1284 -exec-interrupt
1285 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1286 (gdb)
1287
1288 @end example
1289
1290 @section -exec-next
1291 Asynchronous command. Resumes execution of the inferior program, stopping
1292 when the beginning of the next source line is reached.
1293
1294 @subsection GDB command
1295 next
1296
1297 @subsection Example
1298 @example
1299 -exec-next
1300 ^running
1301 (gdb)
1302 *stopped,reason="end-stepping-range",line="8",file="hello.c"
1303 (gdb)
1304 @end example
1305
1306 @section -exec-next-instruction
1307 Asynchronous command. Executes one machine instruction. If the
1308 instruction is a function call continues until the function returns.  If
1309 the program stops at an instruction in the middle of a source line, the
1310 address will be printed as well.
1311 @subsection GDB command
1312 nexti
1313
1314 @subsection Example
1315 @example
1316 (gdb)
1317 -exec-next-instruction
1318 ^running
1319
1320 (gdb)
1321 *stopped,reason="end-stepping-range",
1322 addr="0x000100d4",line="5",file="hello.c"
1323 (gdb)
1324 @end example
1325
1326 @section -exec-return
1327 Makes current function return immediately. Doesn't execute the inferior.
1328 It displays the new current frame.
1329
1330 @subsection GDB command
1331 return
1332
1333 @subsection Example
1334 @example
1335 (gdb)
1336 200-break-insert callee4
1337 200^done,bkpt=@{number="1",addr="0x00010734",
1338 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1339 (gdb)
1340 000-exec-run
1341 000^running
1342 (gdb)
1343 000*stopped,reason="breakpoint-hit",bkptno="1",
1344 frame=@{func="callee4",args=@{@},
1345 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1346 (gdb)
1347 205-break-delete
1348 205^done
1349 (gdb)
1350 111-exec-return
1351 111^done,frame=@{level="0 ",func="callee3",
1352 args=@{@{name="strarg",value="0x11940 \"A string argument.\""@}@},
1353 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1354 (gdb)
1355 @end example
1356
1357 @section -exec-run
1358 Asynchronous command. Starts execution of the inferior from the
1359 beginning. The inferior executes until either a breakpoint is
1360 encountered or the program exits.
1361
1362 @subsection GDB command
1363 run
1364
1365 @subsection Example
1366 @example
1367 (gdb)
1368 -break-insert main
1369 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
1370 (gdb)
1371 -exec-run
1372 ^running
1373 (gdb)
1374 *stopped,reason="breakpoint-hit",bkptno="1",
1375 frame=@{func="main",args=@{@},file="recursive2.c",line="4"@}
1376 (gdb)
1377 @end example
1378
1379
1380 @section -exec-show-arguments
1381 Print the arguments of the program.
1382 @subsection GDB command
1383 show args
1384 @subsection Example
1385 N.A.
1386
1387 @c @section -exec-signal
1388
1389 @section -exec-step
1390 Asynchronous command. Resumes execution of the inferior program, stopping
1391 when the beginning of the next source line is reached, if the next
1392 source line is not a function call. If it is, stop at the first
1393 instruction of the called function.
1394
1395 @subsection GDB command
1396 step
1397
1398 @subsection Example 1
1399 Stepping into a function:
1400 @example
1401 -exec-step
1402 ^running
1403 (gdb)
1404 *stopped,reason="end-stepping-range",frame=@{func="foo",args=@{@{name="a",value="10"@},
1405 @{name="b",value="0"@}@},file="recursive2.c",line="11"@}
1406 (gdb)
1407 @end example
1408 @subsection Example 2
1409 Regular stepping
1410 @example
1411 -exec-step
1412 ^running
1413 (gdb)
1414 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
1415 (gdb)
1416 @end example
1417
1418 @section -exec-step-instruction
1419 Asynchronous command. Resumes the inferior which executes one machine
1420 instruction. The output, once stop, will vary depend on whether we have
1421 stopped in the middle of a source line or not.  In the former case, the
1422 address at which the program stopped will be printed as well.
1423
1424 @subsection GDB command
1425 stepi
1426
1427 @subsection Example
1428 @example
1429 (gdb)
1430 -exec-step-instruction
1431 ^running
1432
1433 (gdb)
1434 *stopped,reason="end-stepping-range",
1435 frame=@{func="foo",args=@{@},file="try.c",line="10"@}
1436 (gdb)
1437 -exec-step-instruction
1438 ^running
1439
1440 (gdb)
1441 *stopped,reason="end-stepping-range",
1442 frame=@{addr="0x000100f4",func="foo",args=@{@},file="try.c",line="10"@}
1443 (gdb)
1444 @end example
1445
1446 @section -exec-until
1447 Asynchronous command. Executes the inferior until the location specified
1448 in the argument is reached. If there is no argument, the inferior
1449 executes until a source line greater than the current one is reached.
1450 The reason for stopping in this case will be ``location-reached''.
1451 @subsection GDB command
1452 until
1453
1454 @subsection Example
1455 @example
1456 (gdb)
1457 -exec-until recursive2.c:6
1458 ^running
1459 (gdb)
1460 x = 55
1461 *stopped,reason="location-reached",frame=@{func="main",args=@{@},
1462 file="recursive2.c",line="6"@}
1463 (gdb)
1464 @end example
1465
1466 @section -file-clear
1467 Is this going away????
1468
1469 @section -file-exec-and-symbols <file>
1470 Specify the executable file to be debugged. This file is the one from
1471 which the symbol table is also read.  If no file is specified, it clears
1472 the executable and symbol information.  If breakpoints are set when
1473 using this command with no arguments, gdb will produce errors. No output
1474 is produced, except a completion notification.
1475 @subsection GDB command
1476 file <file>
1477
1478 @subsection Example
1479 @example
1480 (gdb)
1481 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
1482 ^done
1483 (gdb)
1484 @end example
1485
1486 @section -file-exec-file <file>
1487 Specify the executable file to be debugged. The symbol table is not read
1488 from this file. If used without argument gdb clears the information
1489 about the executable file.  No output is produced, except a completion
1490 notification.
1491 @subsection GDB command
1492 exec-file <file>
1493
1494 @subsection Example
1495 @example
1496 (gdb)
1497 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
1498 ^done
1499 (gdb)
1500 @end example
1501
1502 @section -file-list-exec-sections
1503 List the sections of the current executable file.
1504 @subsection GDB command
1505 info file (only part of it), gdb_load_info
1506 @subsection Example
1507 N.A.
1508
1509 @section -file-list-exec-source-files
1510 List the source files for the current executable.
1511 @subsection GDB command
1512 gdb_listfiles (gdbtk).
1513 @subsection Example
1514 N.A.
1515
1516 @section -file-list-shared-libraries
1517 List the shared libraries in the program.
1518 @subsection GDB command
1519 info shared
1520 @subsection Example
1521 N.A.
1522
1523 @section -file-list-symbol-files
1524 List symbol files.
1525 @subsection GDB command
1526 info file (part of it).
1527 @subsection Example
1528 N.A.
1529
1530 @section -file-symbol-file <file>
1531 Read symbol table info from the file specified as argument.  Used
1532 without arguments clears gdb's symbol table info.  No output is
1533 produced, except a completion notification.
1534 @subsection GDB command
1535 symbol-file <file>
1536
1537 @subsection Example
1538 @example
1539 (gdb)
1540 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
1541 ^done
1542 (gdb)
1543 @end example
1544
1545 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1546 @chapter Misc GDB commands
1547
1548 @c @section -gdb-complete
1549
1550 @section -gdb-exit
1551
1552 Exit GDB immediately.
1553 @subsection GDB command
1554 Approximately corresponds to 'quit'.
1555
1556 @subsection Example
1557 @example
1558 (gdb)
1559 -gdb-exit
1560 @end example
1561
1562 @section -gdb-set
1563 Set an internal GDB variable.
1564 IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
1565
1566 @subsection GDB command
1567 set
1568
1569 @subsection Example
1570 @example
1571 (gdb)
1572 -gdb-set $foo=3
1573 ^done
1574 (gdb)
1575 @end example
1576
1577 @section -gdb-show
1578 Show the current value of a GDB variable.
1579
1580 @subsection GDB command
1581 show
1582
1583 @subsection Example
1584 @example
1585 (gdb)
1586 -gdb-show annotate
1587 ^done,value="0"
1588 (gdb)
1589 @end example
1590
1591 @c @section -gdb-source
1592
1593 @section -gdb-version
1594 Show version information for gdb. Used in testing mostly.
1595
1596 @subsection GDB command
1597 No equivalent.
1598
1599 @subsection Example
1600 @example
1601 (gdb)
1602 -gdb-version
1603 ~GNU gdb 4.18.1 HEADLESS
1604 ~Copyright 1998 Free Software Foundation, Inc.
1605 ~GDB is free software, covered by the GNU General Public License, and you are
1606 ~welcome to change it and/or distribute copies of it under certain conditions.
1607 ~Type "show copying" to see the conditions.
1608 ~There is absolutely no warranty for GDB.  Type "show warranty" for details.
1609 ~This GDB was configured as "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
1610 ^done
1611 (gdb)
1612 @end example
1613
1614 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1615 @chapter Kod Commands
1616
1617 The Kod commands are not implemented.
1618
1619 @c @section -kod-info
1620
1621 @c @section -kod-list
1622
1623 @c @section -kod-list-object-types
1624
1625 @c @section -kod-show
1626
1627 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1628 @chapter Memory Overlay Commands
1629
1630 the memory overlay commands not implemented.
1631
1632 @c @section -overlay-auto
1633
1634 @c @section -overlay-list-mapping-state
1635
1636 @c @section -overlay-list-overlays
1637
1638 @c @section -overlay-map
1639
1640 @c @section -overlay-off
1641
1642 @c @section -overlay-on
1643
1644 @c @section -overlay-unmap
1645
1646 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1647 @chapter Signal Handling Commands
1648
1649 Signal handling commands are not implemented.
1650
1651 @c @section -signal-handle
1652
1653 @c @section -signal-list-handle-actions
1654
1655 @c @section -signal-list-signal-types
1656
1657 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1658 @chapter Stack manipulation commands
1659
1660 @section -stack-info-frame
1661 Get info on the current frame.
1662 @subsection GDB command
1663 info frame or frame (w/o args).
1664 @subsection Example
1665 N.A.
1666
1667 @section -stack-info-depth [max-depth]
1668 Return the depth of the stack. If the integer argument <max-depth> is specified, do not
1669 count beyond max-depth frames.
1670 @subsection GDB command
1671 No equivalent.
1672 @subsection Example
1673 For a stack with frame levels 0 through 11:
1674 @example
1675 (gdb)
1676 -stack-info-depth
1677 ^done,depth="12"
1678 (gdb)
1679 -stack-info-depth 4
1680 ^done,depth="4"
1681 (gdb)
1682 -stack-info-depth 12
1683 ^done,depth="12"
1684 (gdb)
1685 -stack-info-depth 11
1686 ^done,depth="11"
1687 (gdb)
1688 -stack-info-depth 13
1689 ^done,depth="12"
1690 (gdb)
1691 @end example
1692
1693 @section -stack-list-arguments <show-values> [ <low-frame> <high-frame> ]
1694 Display a list of the arguments for the frames between low-frame and
1695 high-frame (inclusive). If low-frame and high-frame are not provided, it
1696 will list the arguments for the whole stack. The show-values argument
1697 must have a value of 0 or 1. A value of 0 means that only the names of
1698 the arguments are listed, a value of 1 means that both names and values
1699 of the argumetns are printed.
1700 @subsection GDB command
1701 gdb_get_args (partially).
1702 @subsection Example
1703 @example
1704 (gdb)
1705 -stack-list-frames
1706 ^done,
1707 stack=@{
1708 frame=@{level="0 ",addr="0x00010734",func="callee4",
1709 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
1710 frame=@{level="1 ",addr="0x0001076c",func="callee3",
1711 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
1712 frame=@{level="2 ",addr="0x0001078c",func="callee2",
1713 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
1714 frame=@{level="3 ",addr="0x000107b4",func="callee1",
1715 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
1716 frame=@{level="4 ",addr="0x000107e0",func="main",
1717 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}@}
1718 (gdb)
1719 -stack-list-arguments 0
1720 ^done,
1721 stack-args=@{
1722 frame=@{level="0",args=@{@}@},
1723 frame=@{level="1",args=@{name="strarg"@}@},
1724 frame=@{level="2",args=@{name="intarg",name="strarg"@}@},
1725 frame=@{level="3",args=@{name="intarg",name="strarg",name="fltarg"@}@},
1726 frame=@{level="4",args=@{@}@}@}
1727 (gdb)
1728 -stack-list-arguments 1
1729 ^done,
1730 stack-args=@{
1731 frame=@{level="0",args=@{@}@},
1732 frame=@{level="1",args=@{@{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
1733 frame=@{level="2",args=@{
1734 @{name="intarg",value="2"@},
1735 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
1736 @{frame=@{level="3",args=@{
1737 @{name="intarg",value="2"@},
1738 @{name="strarg",value="0x11940 \"A string argument.\""@},
1739 @{name="fltarg",value="3.5"@}@}@},
1740 frame=@{level="4",args=@{@}@}@}
1741 (gdb)
1742 -stack-list-arguments 0 2 2
1743 ^done,stack-args=@{frame=@{level="2",args=@{name="intarg",name="strarg"@}@}@}
1744 (gdb)
1745 -stack-list-arguments 1 2 2
1746 ^done,stack-args=@{frame=@{level="2",
1747 args=@{@{name="intarg",value="2"@},
1748 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@}@}
1749 (gdb)
1750 @end example
1751
1752 @c @section -stack-list-exception-handlers
1753
1754 @section -stack-list-frames [ <low-frame> <high-frame> ]
1755 List the frames currently on the stack. For each frame it displays the following info:
1756 @table @samp
1757 @item <level>
1758 The frame number, 0 being the topmost frame, i.e. the innermost function.
1759 @item <addr>
1760 Pc value for that frame.
1761 @item <func>
1762 Function name
1763 @item <file>
1764 File name of the source fle where the function lives.
1765 @item <line>
1766 Line number corresponding to the pc.
1767 @end table
1768
1769 If invoked without arguments, it prints a backtrace for the whole stack.
1770 If given two integer arguments it shows the frames whose levels are
1771 between the two arguments (inclusive). If the two arguments are equal,
1772 it shows the single frame at the corresponding level.
1773
1774 @subsection GDB command
1775 backtrace or where
1776
1777 @subsection Example 1
1778 Whole stack backtrace.
1779
1780 @example
1781 (gdb)
1782 -stack-list-frames
1783 ^done,stack=
1784 @{frame=@{level="0 ",addr="0x0001076c",func="foo",file="recursive2.c",line="11"@},
1785 frame=@{level="1 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
1786 frame=@{level="2 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
1787 frame=@{level="3 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
1788 frame=@{level="4 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
1789 frame=@{level="5 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
1790 frame=@{level="6 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
1791 frame=@{level="7 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
1792 frame=@{level="8 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
1793 frame=@{level="9 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
1794 frame=@{level="10",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
1795 frame=@{level="11",addr="0x00010738",func="main",file="recursive2.c",line="4"@}@}
1796
1797 (gdb)
1798 @end example
1799
1800 @subsection Example 2
1801 Show frames between low_frame and high_frame.
1802 @example
1803 (gdb)
1804 -stack-list-frames 3 5
1805 ^done,stack=
1806 @{frame=@{level="3 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
1807 frame=@{level="4 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@},
1808 frame=@{level="5 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@}@}
1809 (gdb)
1810 @end example
1811 @subsection Example 3
1812 Show one single frame.
1813 @example
1814 (gdb)
1815 -stack-list-frames 3 3
1816 ^done,stack=
1817 @{frame=@{level="3 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@}@}
1818 (gdb)
1819 @end example
1820
1821 @section -stack-list-locals <print-values>
1822 Display the local variables names for the current frame.  With an
1823 argument of 0 prints only the names of the variables, with argument of 1
1824 prints also the values.
1825 @subsection GDB command
1826 gdb_get_locals
1827
1828 @subsection Example
1829 @example
1830 (gdb)
1831 -stack-list-locals 0
1832 ^done,locals=@{name="A",name="B",name="C"@}
1833 (gdb)
1834 -stack-list-locals 1
1835 ^done,locals=@{@{name="A",value="1"@},@{name="B",value="2"@},@{name="C",value="3"@}@}
1836 (gdb)
1837 @end example
1838
1839 @section -stack-select-frame <framenum>
1840 Change the current frame. Select a different frame on the stack.
1841 @subsection GDB command
1842 frame (part), up, down
1843 AND/OR select-frame,
1844 up-silent, down-silent
1845 @subsection Example
1846 @example
1847 (gdb)
1848 -stack-select-frame 2
1849 ^done
1850 (gdb)
1851 @end example
1852
1853 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1854 @chapter Symbol query commands
1855
1856 @section -symbol-info-address <symbol>
1857 Describe where <symbol> is stored.
1858 @subsection GDB command
1859 Info address
1860 @subsection Example
1861 N.A.
1862
1863 @section -symbol-info-file
1864 Show the file for the symbol [NOT SURE]
1865 @subsection GDB command
1866 gdb_filnd_file (gdbtk).
1867 @subsection Example
1868 N.A.
1869
1870 @section -symbol-info-function
1871 Show which function the symbol lives in. [NOT SURE]
1872 @subsection GDB command
1873 gdb_get_function (gdbtk)
1874 @subsection Example
1875 N.A.
1876
1877 @section -symbol-info-line
1878 Core addresses of the code for a source line.
1879 @subsection GDB command
1880 info line , gdb_get_line, gdb_get_file
1881 @subsection Example
1882 N.A.
1883
1884 @section -symbol-info-symbol
1885 Describe what symbol is at location ADDR [NOT SURE]
1886 @subsection GDB command
1887 info symbol
1888 @subsection Example
1889 N.A.
1890
1891 @section -symbol-list-functions
1892 List the functions in the executable.
1893 @subsection GDB command
1894 info functions, gdb_listfunc, gdb_search
1895 @subsection Example
1896 N.A.
1897
1898 @section -symbol-list-types
1899 List all the type names.
1900 @subsection GDB command
1901 info types, gdb_search
1902 @subsection Example
1903 N.A.
1904
1905 @section -symbol-list-variables
1906 List all global and static variable names.
1907 @subsection GDB command
1908 Info variables, gdb_search
1909 @subsection Example
1910 N.A.
1911
1912 @section -symbol-locate
1913 @subsection GDB command
1914 gdb_loc (gdbtk)
1915 @subsection Example
1916 N.A.
1917
1918 @section -symbol-type
1919 Show type of a variable.
1920 @subsection GDB command
1921 ptype, gdb_obj_variable
1922 @subsection Example
1923 N.A.
1924
1925 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1926 @chapter Target manipulation commands
1927
1928 @section -target-attach
1929 Attach to a process or file outside of GDB.
1930 @subsection GDB command
1931 attach
1932 @subsection Example
1933 N.A.
1934
1935 @section -target-compare-sections
1936 Compare section data on target to the exec file.
1937 @subsection GDB command
1938 compare-sections
1939 @subsection Example
1940 N.A.
1941
1942 @section -target-detach
1943 Disconnect from the remote target.
1944 No output.
1945
1946 @subsection GDB command
1947 detach
1948
1949 @subsection Example
1950 @example
1951 (gdb)
1952 -target-detach
1953 ^done
1954 (gdb)
1955 @end example
1956
1957 @section -target-download
1958 Loads the executable onto the remote target.
1959 It prints out an update message every half second, which includes the fields:
1960 @itemize @bullet
1961 @item section: The name of the section.
1962 @item section-sent: The size of what has been sent so far for that section.
1963 @item section-size: The size of the section.
1964 @item total-sent: The total size of what was sent so far (the current and the previous sections).
1965 @item total-size: The size of the overall executable to download.
1966 @end itemize
1967 Each message is sent as status record.
1968
1969 In addition it prints the name and size of the sections, as they are
1970 downloaded. These messages include the fields:
1971 @itemize @bullet
1972 @item section: The name of the section.
1973 @item section-size: The size of the section.
1974 @item total-size: The size of the overall executable to download.
1975 @end itemize
1976 At the end a summary is printed.
1977 @subsection GDB command
1978 load
1979
1980 @subsection Example
1981 Note: Each status message appears on a single line. Here the messages
1982 have been broken down, so they can fit into a page.
1983 @example
1984 (gdb)
1985 -target-download
1986 +download,@{section=".text",section-size="6668",total-size="9880"@}
1987 +download,@{section=".text",section-sent="512",section-size="6668",
1988 total-sent="512",total-size="9880"@}
1989 +download,@{section=".text",section-sent="1024",section-size="6668",
1990 total-sent="1024",total-size="9880"@}
1991 +download,@{section=".text",section-sent="1536",section-size="6668",
1992 total-sent="1536",total-size="9880"@}
1993 +download,@{section=".text",section-sent="2048",section-size="6668",
1994 total-sent="2048",total-size="9880"@}
1995 +download,@{section=".text",section-sent="2560",section-size="6668",
1996 total-sent="2560",total-size="9880"@}
1997 +download,@{section=".text",section-sent="3072",section-size="6668",
1998 total-sent="3072",total-size="9880"@}
1999 +download,@{section=".text",section-sent="3584",section-size="6668",
2000 total-sent="3584",total-size="9880"@}
2001 +download,@{section=".text",section-sent="4096",section-size="6668",
2002 total-sent="4096",total-size="9880"@}
2003 +download,@{section=".text",section-sent="4608",section-size="6668",
2004 total-sent="4608",total-size="9880"@}
2005 +download,@{section=".text",section-sent="5120",section-size="6668",
2006 total-sent="5120",total-size="9880"@}
2007 +download,@{section=".text",section-sent="5632",section-size="6668",
2008 total-sent="5632",total-size="9880"@}
2009 +download,@{section=".text",section-sent="6144",section-size="6668",
2010 total-sent="6144",total-size="9880"@}
2011 +download,@{section=".text",section-sent="6656",section-size="6668",
2012 total-sent="6656",total-size="9880"@}
2013 +download,@{section=".init",section-size="28",total-size="9880"@}
2014 +download,@{section=".fini",section-size="28",total-size="9880"@}
2015 +download,@{section=".data",section-size="3156",total-size="9880"@}
2016 +download,@{section=".data",section-sent="512",section-size="3156",
2017 total-sent="7236",total-size="9880"@}
2018 +download,@{section=".data",section-sent="1024",section-size="3156",
2019 total-sent="7748",total-size="9880"@}
2020 +download,@{section=".data",section-sent="1536",section-size="3156",
2021 total-sent="8260",total-size="9880"@}
2022 +download,@{section=".data",section-sent="2048",section-size="3156",
2023 total-sent="8772",total-size="9880"@}
2024 +download,@{section=".data",section-sent="2560",section-size="3156",
2025 total-sent="9284",total-size="9880"@}
2026 +download,@{section=".data",section-sent="3072",section-size="3156",
2027 total-sent="9796",total-size="9880"@}
2028 ^done,address="0x10004",load-size="9880",transfer-rate="6586",write-rate="429"
2029 (gdb)
2030 @end example
2031
2032 @section -target-exec-status
2033 Provide information on the state of the target. Whether it is running or not, for instance.
2034 @subsection GDB command
2035 No equivalent
2036 @subsection Example
2037 N.A.
2038
2039 @section -target-list-available-targets
2040 List the possible targets to connect to.
2041 @subsection GDB command
2042 help target
2043 @subsection Example
2044 N.A.
2045
2046 @section -target-list-current-targets
2047 What the current target is.
2048 @subsection GDB command
2049 info file (part of it).
2050 @subsection Example
2051 N.A.
2052
2053 @section -target-list-parameters
2054 ????
2055 @subsection GDB command
2056 No equivalent
2057 @subsection Example
2058 N.A.
2059
2060 @section -target-select
2061 Connect GDB to the remote target.
2062 It takes two args:
2063
2064 -target-select <type> <parameters>.
2065
2066 Where:
2067
2068 @table @samp
2069 @item <type>
2070 The type of target, for instance async, remote, etc.
2071 @item <parameters>
2072 Device names, host names and the like.
2073 @end table
2074 The output is a connection notification, followed by the address at
2075 which the target program is, in the following form:
2076 ^connected,addr="<address>",func="<function name>",args=@{<arg list>@}
2077
2078 @subsection GDB command
2079 target
2080
2081 @subsection Example
2082 @example
2083 (gdb)
2084 -target-select async /dev/ttya
2085 ^connected,addr="0xfe00a300",func="??",args=@{@}
2086 (gdb)
2087 @end example
2088
2089 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2090 @chapter Thread commands
2091
2092 @section -thread-info
2093 @subsection GDB command
2094 @subsection Example
2095
2096 @section -thread-list-all-threads
2097 @subsection GDB command
2098 @subsection Example
2099
2100 @section -thread-list-ids
2101 Produces a list of the currently known gdb thread ids. At the end of the
2102 list it also prints the toal number of such threads.
2103 @subsection GDB command
2104 None equivalent. (Maybe part of info threads).
2105 @subsection Example 1
2106 No threads present, besides the main process.
2107 @example
2108 (gdb)
2109 -thread-list-ids
2110 ^done,thread-ids=@{@},number-of-threads="0"
2111 (gdb)
2112 @end example
2113 @subsection Example 2
2114 Several threads.
2115 @example
2116 (gdb)
2117 -thread-list-ids
2118 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
2119 number-of-threads="3"
2120 (gdb)
2121 @end example
2122
2123 @section -thread-select <threadnum>
2124 Make <threadnum> the current thread. It prints the number of the new
2125 current thread, and the topmost frame for that thread.
2126 @subsection GDB command
2127 thread
2128 @subsection Example
2129 @example
2130 (gdb)
2131 -exec-next
2132 ^running
2133 (gdb)
2134 *stopped,reason="end-stepping-range",thread-id="2",line="187",
2135 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
2136 (gdb)
2137 -thread-list-ids
2138 ^done,
2139 thread-ids={thread-id="3",thread-id="2",thread-id="1"},
2140 number-of-threads="3"
2141 (gdb)
2142 -thread-select 3
2143 ^done,new-thread-id="3",
2144 frame=@{level="0 ",func="vprintf",
2145 args=@{@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
2146 @{name="arg",value="0x2"@}@},file="vprintf.c",line="31"@}
2147 (gdb)
2148 @end example
2149
2150 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2151 @chapter Tracepoint Commands
2152
2153 The tracepoint commands are not implemented.
2154
2155 @c @section -trace-actions
2156
2157 @c @section -trace-delete
2158
2159 @c @section -trace-disable
2160
2161 @c @section -trace-dump
2162
2163 @c @section -trace-enable
2164
2165 @c @section -trace-exists
2166
2167 @c @section -trace-find
2168
2169 @c @section -trace-frame-number
2170
2171 @c @section -trace-info
2172
2173 @c @section -trace-insert
2174
2175 @c @section -trace-list
2176
2177 @c @section -trace-pass-count
2178
2179 @c @section -trace-save
2180
2181 @c @section -trace-start
2182
2183 @c @section -trace-stop
2184
2185
2186 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2187 @chapter Variable Objects
2188
2189 @section Motivation
2190
2191 For the implementation of a variable debugger window (locals, watched
2192 expressions, etc.), we are proposing the adaptation of the existent code
2193 used by Insight.
2194
2195 The two main reason for that are:
2196
2197 @enumerate 1
2198 @item
2199 It has been proven in practice (it is already on it's second generation)
2200 @item
2201 It will shorten development time (needless to say how important it is
2202 now)
2203 @end enumerate
2204
2205 The original interface was designed to be used by Tcl code, so it was
2206 slightly changed so it can be used through flathead.  This document
2207 describes the flathead operations that will be available and gives some
2208 hints about its use.
2209
2210 @emph{Note}: In addition to the set of operations described here, we
2211 expect the GUI implementation of a variable window to require, at least,
2212 the following operations:
2213 @itemize bullet
2214 @item -gdb-show output-radix
2215 @item -stack-list-arguments
2216 @item -stack-list-locals
2217 @item -stack-select-frame
2218 @end itemize
2219
2220 @section Introduction
2221
2222 The basic idea behind variable objects is the creation of a named object
2223 to represent a variable, an expression, a memory location or even a CPU
2224 register.  For each object created, a set of operations is available for
2225 examining or changing its properties.
2226
2227 Furthermore, complex data types, such as C structures, are represented
2228 in a tree format.  For instance, the struct type variable is the root
2229 and the children will represent the struct members.  If a children is
2230 itself of a complex type, it will also have children of its own.
2231 Appropriate language differences are handled for C, C++ and Java.
2232
2233 When returning the actual values of the objects, this facility allows
2234 for the individual selection of the display format used in the result
2235 creation.  It can be chosen among: binary, decimal, hexadecimal, octal
2236 and natural. Natural refers to the a default format automatically chosen
2237 based on the variable type (like decimal for int, hex for pointers,
2238 etc.).
2239
2240 The following is the complete set of flathead operations defined to
2241 access this functionality:
2242
2243 @multitable @columnfractions .3 .6
2244 @item @strong{Operation}
2245 @tab @strong{Description}
2246
2247 @item -var-create
2248 @tab create a variable object
2249 @item -var-delete
2250 @tab delete the variable object and its children
2251 @item -var-set-format
2252 @tab set the display format of this variable
2253 @item -var-show-format
2254 @tab show the display format of this variable
2255 @item -var-info-num-children
2256 @tab tells how many children this object has
2257 @item -var-list-children
2258 @tab return a list of the object's children
2259 @item -var-info-type
2260 @tab show the type of this variable object
2261 @item -var-info-expression
2262 @tab print what this variable object represents
2263 @item -var-show-attributes
2264 @tab is this variable editable? does it exist here?
2265 @item -var-evaluate-expression
2266 @tab get the value of this variable
2267 @item -var-assign
2268 @tab set the value of this variable
2269 @item -var-update
2270 @tab update the variable and its children
2271 @end multitable
2272
2273 In the next section we describe each operation in detail and suggest how
2274 it can be used.
2275
2276
2277 @section Operations Description And Use
2278
2279 @subsection -var-create @{<name> | '-'@} @{<frame-addr> | '*'@} <expression>
2280
2281 This operation creates a variable object, which allows the monitoring of
2282 a variable, the result of an expression, a memory cell or a CPU
2283 register.
2284
2285 The <name> parameter is the string by which the object can be
2286 referenced.  It must be unique.  If '-' is specified, the varobj system
2287 will generate a string "varNNNNNN" automatically.  It will be unique
2288 provided that one does not specify <name> on that format.  The command
2289 fails if a duplicate name is found.
2290
2291 The frame under which the expression should be evaluated can be
2292 specified.  A '*' indicates that the current frame should be used.
2293
2294 Expression is any expression valid on the current language set (must not
2295 begin with '*') or: *<addr> - The address of a memory cell
2296 *<addr>-<addr> - An memory address range (TBD) $<regname> - A CPU
2297 register
2298
2299 This operation returns the name, number of children and the type of the
2300 object created.  Type is returned as a string as the ones generated by
2301 gdb CLI.
2302
2303 name="<name>",numchild="N",type="<type>"
2304
2305 @subsection -var-delete <name>
2306
2307 Deletes a previously created variable object and all of it's children.
2308
2309 Returns an error if the object <name> is not found.
2310
2311 @subsection -var-set-format <name> <format-spec>
2312
2313 Sets the output format for the value of the object.
2314
2315 <format-spec> = @{binary | decimal | hexadecimal | octal | natural@}
2316
2317 @subsection -var-show-format <name>
2318
2319 Returns the format used to display the value of the object.
2320
2321 format="<format-spec>"
2322
2323 @subsection -var-info-num-children <name>
2324
2325 Returns the number of children of a variable object.
2326
2327 numchild="N"
2328
2329 @subsection -var-list-children <name>
2330
2331 Returns a list of the children of the specified variable object.
2332
2333 numchild="N",children=@{@{name="<name>",numchild="N",type="<type>"@},(repeats N times)@}
2334
2335 @subsection -var-info-type <name>
2336
2337 Returns the type of the specified variable.  The type is returned as a
2338 string in the same format as it is output by gdb's CLI.
2339
2340 type="<type>"
2341
2342 @subsection -var-info-expression <name>
2343
2344 Returns what is represented by the specified variable object.
2345
2346 lang="<lang-spec>",exp="<expression>"
2347
2348 where <lang-spec> = @{"C" | "C++" | "Java"@}
2349
2350 @subsection -var-show-attributes <name>
2351
2352 List attributes of the specified variable object.
2353
2354 status="<attr>[,<attr>]*"
2355
2356 where <attr> = @{ @{ editable | noneditable @} | TBD @}
2357
2358 @subsection -var-evaluate-expression <name>
2359
2360 Evaluates the expression that is represented by the specified variable
2361 object and returns its value as a string in the current format specified
2362 for the object.
2363
2364 value="<value>"
2365
2366 @subsection -var-assign <name> <expression>
2367
2368 Assigns a new value for the variable object specified.  The object must
2369 be "editable".
2370
2371 @subsection -var-update @{<name> | '*'@}
2372
2373 Update the value of the variable object by evaluating its expression
2374 after fetching all the new values from memory or registers.  A '*'
2375 causes all existing variable objects to be updated.
2376
2377
2378 @c%%%%%%%%%%%%%%%%%%%%%%%%%%%% APPENDIX %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2379 @appendix Proposed v2.0 Output Syntax
2380
2381 This appendix is not part of the MI specification.  It is provided as a
2382 discussion point.
2383
2384 The output from GDB/MI consists of zero or more out-of-band records
2385 optionally followed by a single result record.  The result record being
2386 for the most recent command input.  The sequence being terminated by
2387 ``(gdb)''.
2388
2389 Asynchronous GDB/MI output is similar.
2390
2391 Each output record directly associated with an input command is prefixed
2392 by the input commands @code{<token>}.
2393
2394 @table @code
2395 @item <output> @expansion{}
2396 @{ <out-of-band-record> @} [ <result-record> ] ``(gdb)'' <nl>
2397
2398 @item <result-record> @expansion{}
2399 [ <token> ] ``^'' <result-class> @{ ``,'' <result> @} <nl>
2400
2401 @item <out-of-band-record> @expansion{}
2402 <async-record> | <stream-record>
2403
2404 @item <async-record> @expansion{}
2405 <exec-async-output> | <status-async-output> | <notify-async-output>
2406
2407 @item <exec-async-output> @expansion{}
2408 [ <token> ] ``*'' <async-output>
2409
2410 @item <status-async-output> @expansion{}
2411 [ <token> ] ``+'' <async-output>
2412
2413 @item <notify-async-output> @expansion{}
2414 [ <token> ] ``='' <async-output>
2415
2416 @item <async-output> @expansion{}
2417 <async-class> @{ ``,'' <result> @} <nl>
2418
2419 @item <result-class> @expansion{}
2420 ``done'' | ``running'' | ``connected'' | ``error'' | ``exit''
2421
2422 @item <async-class> @expansion{}
2423 ``stopped'' | @emph{others depending on need as still in development}
2424
2425 @item <result> @expansion{}
2426 <string> ``='' <value>
2427
2428 @item <value> @expansion{}
2429 <c-string> | <tupple> | <list>
2430
2431 @item <tupple> @expansion{}
2432 ``@{@}'' | ``@{'' <result> @{ ``,'' <result> @} ``@}''
2433
2434 @item <list> @expansion{}
2435 ``[]'' | ``['' <value> @{ ``,'' <value> @} ``]''
2436
2437 @item <string> @expansion{}
2438 @emph{[-A-Za-z\.0-9_]*}
2439
2440 @item <c-string> @expansion{}
2441 @emph{See the input specification}
2442
2443 @item <stream-record> @expansion{}
2444 <console-stream-output> | <target-stream-output> | <log-stream-output>
2445
2446 @item <console-stream-output> @expansion{}
2447 ``~'' <c-string>
2448
2449 @item <target-stream-output> @expansion{}
2450 ``@@'' <c-string>
2451
2452 @item <log-stream-output> @expansion{}
2453 ``&'' <c-string>
2454
2455 @item <nl> @expansion{}
2456 CR | CR-LF
2457
2458 @item <token> @expansion{}
2459 ``any sequence of digits''
2460
2461 @end table
2462
2463 In addition, the following are still being developed.
2464
2465 @table @code
2466
2467 @item <query>
2468 This action is currently undefined.
2469
2470 @end table
2471
2472 Notes:
2473
2474 @itemize @bullet
2475
2476 @item
2477 All output sequences end in a single line containing a period.
2478
2479 @item
2480 The @code{<token>} is from the corresponding request.  If an execution
2481 command is interrupted by the -exec-interrupt command, the token
2482 associated with the `*stopped' message is the one of the original
2483 execution command, not the one of the interrupt-command.
2484
2485 @item
2486 <status-async-output> contains on-going status information about the progress
2487 of a slow operation.  It can be discarded. All status output is prefixed by
2488 the prefix `+'.
2489
2490 @item
2491 <exec-async-output> contains asynchronous state change on the target
2492 (stopped, started, disappeared). All async output is prefixed by
2493 the prefix `*'.
2494
2495 @item
2496 <notify-async-output> contains supplementary information that the client should
2497 handle (new breakpoint information). All notify output is prefixed by
2498 the prefix `='.
2499
2500 @item
2501 <console-stream-output> is output that should be displayed as is in the
2502 console.  It is the textual response to a CLI command. All the console
2503 output is prefixed by the prefix ``~''.
2504
2505 @item
2506 <target-stream-output> is the output produced by the target program.
2507 All the target output is prefixed by the prefix ``@@''.
2508
2509 @item
2510 <log-stream-output> is output text coming from GDB's internals, for
2511 instance messages that should be displayed as part of an error log.  All
2512 the log output is prefixed by the prefix ``&''.
2513
2514 @end itemize
2515
2516
2517 @c Local variables:
2518 @c change-log-default-name: "ChangeLog-mi"
2519 @c End:
2520 @bye