Subversion Repositories or1k_old

This is gdb.info, produced by makeinfo version 4.1 from ./gdb.texinfo.

INFO-DIR-SECTION Programming & development tools.
START-INFO-DIR-ENTRY
* Gdb: (gdb).                     The GNU debugger.
END-INFO-DIR-ENTRY

   This file documents the GNU debugger GDB.

   This is the Ninth Edition, December 2001, of `Debugging with GDB:
the GNU Source-Level Debugger' for GDB Version 5.3.

   Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1998,
1999, 2000, 2001, 2002 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs Free
Documentation", with the Front-Cover Texts being "A GNU Manual," and
with the Back-Cover Texts as in (a) below.

   (a) The Free Software Foundation's Back-Cover Text is: "You have
freedom to copy and modify this GNU Manual, like GNU software.  Copies
published by the Free Software Foundation raise funds for GNU
development."


File: gdb.info,  Node: GDB/MI Data Manipulation,  Next: GDB/MI Program Control,  Prev: GDB/MI Breakpoint Table Commands,  Up: GDB/MI

GDB/MI Data Manipulation
========================

   This section describes the GDB/MI commands that manipulate data:
examine memory and registers, evaluate expressions, etc.

The `-data-disassemble' Command
-------------------------------

Synopsis
........

      -data-disassemble
         [ -s START-ADDR -e END-ADDR ]
       | [ -f FILENAME -l LINENUM [ -n LINES ] ]
       -- MODE

Where:

`START-ADDR'
     is the beginning address (or `$pc')

`END-ADDR'
     is the end address

`FILENAME'
     is the name of the file to disassemble

`LINENUM'
     is the line number to disassemble around

`LINES'
     is the the number of disassembly lines to be produced.  If it is
     -1, the whole function will be disassembled, in case no END-ADDR is
     specified.  If END-ADDR is specified as a non-zero value, and
     LINES is lower than the number of disassembly lines between
     START-ADDR and END-ADDR, only LINES lines are displayed; if LINES
     is higher than the number of lines between START-ADDR and
     END-ADDR, only the lines up to END-ADDR are displayed.

`MODE'
     is either 0 (meaning only disassembly) or 1 (meaning mixed source
     and disassembly).

Result
......

   The output for each instruction is composed of four fields:

   * Address

   * Func-name

   * Offset

   * Instruction

   Note that whatever included in the instruction field, is not
manipulated directely by GDB/MI, i.e. it is not possible to adjust its
format.

GDB Command
...........

   There's no direct mapping from this command to the CLI.

Example
.......

   Disassemble from the current value of `$pc' to `$pc + 20':

     (gdb)
     -data-disassemble -s $pc -e "$pc + 20" -- 0
     ^done,
     asm_insns=[
     {address="0x000107c0",func-name="main",offset="4",
     inst="mov  2, %o0"},
     {address="0x000107c4",func-name="main",offset="8",
     inst="sethi  %hi(0x11800), %o2"},
     {address="0x000107c8",func-name="main",offset="12",
     inst="or  %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},
     {address="0x000107cc",func-name="main",offset="16",
     inst="sethi  %hi(0x11800), %o2"},
     {address="0x000107d0",func-name="main",offset="20",
     inst="or  %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}]
     (gdb)

   Disassemble the whole `main' function.  Line 32 is part of `main'.

     -data-disassemble -f basics.c -l 32 -- 0
     ^done,asm_insns=[
     {address="0x000107bc",func-name="main",offset="0",
     inst="save  %sp, -112, %sp"},
     {address="0x000107c0",func-name="main",offset="4",
     inst="mov   2, %o0"},
     {address="0x000107c4",func-name="main",offset="8",
     inst="sethi %hi(0x11800), %o2"},
     [...]
     {address="0x0001081c",func-name="main",offset="96",inst="ret "},
     {address="0x00010820",func-name="main",offset="100",inst="restore "}]
     (gdb)

   Disassemble 3 instructions from the start of `main':

     (gdb)
     -data-disassemble -f basics.c -l 32 -n 3 -- 0
     ^done,asm_insns=[
     {address="0x000107bc",func-name="main",offset="0",
     inst="save  %sp, -112, %sp"},
     {address="0x000107c0",func-name="main",offset="4",
     inst="mov  2, %o0"},
     {address="0x000107c4",func-name="main",offset="8",
     inst="sethi  %hi(0x11800), %o2"}]
     (gdb)

   Disassemble 3 instructions from the start of `main' in mixed mode:

     (gdb)
     -data-disassemble -f basics.c -l 32 -n 3 -- 1
     ^done,asm_insns=[
     src_and_asm_line={line="31",
     file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
       testsuite/gdb.mi/basics.c",line_asm_insn=[
     {address="0x000107bc",func-name="main",offset="0",
     inst="save  %sp, -112, %sp"}]},
     src_and_asm_line={line="32",
     file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
       testsuite/gdb.mi/basics.c",line_asm_insn=[
     {address="0x000107c0",func-name="main",offset="4",
     inst="mov  2, %o0"},
     {address="0x000107c4",func-name="main",offset="8",
     inst="sethi  %hi(0x11800), %o2"}]}]
     (gdb)

The `-data-evaluate-expression' Command
---------------------------------------

Synopsis
........

      -data-evaluate-expression EXPR

   Evaluate EXPR as an expression.  The expression could contain an
inferior function call.  The function call will execute synchronously.
If the expression contains spaces, it must be enclosed in double quotes.

GDB Command
...........

   The corresponding GDB commands are `print', `output', and `call'.
In `gdbtk' only, there's a corresponding `gdb_eval' command.

Example
.......

   In the following example, the numbers that precede the commands are
the "tokens" described in *Note GDB/MI Command Syntax: GDB/MI Command
Syntax.  Notice how GDB/MI returns the same tokens in its output.

     211-data-evaluate-expression A
     211^done,value="1"
     (gdb)
     311-data-evaluate-expression &A
     311^done,value="0xefffeb7c"
     (gdb)
     411-data-evaluate-expression A+3
     411^done,value="4"
     (gdb)
     511-data-evaluate-expression "A + 3"
     511^done,value="4"
     (gdb)

The `-data-list-changed-registers' Command
------------------------------------------

Synopsis
........

      -data-list-changed-registers

   Display a list of the registers that have changed.

GDB Command
...........

   GDB doesn't have a direct analog for this command; `gdbtk' has the
corresponding command `gdb_changed_register_list'.

Example
.......

   On a PPC MBX board:

     (gdb)
     -exec-continue
     ^running
     
     (gdb)
     *stopped,reason="breakpoint-hit",bkptno="1",frame={func="main",
     args=[],file="try.c",line="5"}
     (gdb)
     -data-list-changed-registers
     ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
     "10","11","13","14","15","16","17","18","19","20","21","22","23",
     "24","25","26","27","28","30","31","64","65","66","67","69"]
     (gdb)

The `-data-list-register-names' Command
---------------------------------------

Synopsis
........

      -data-list-register-names [ ( REGNO )+ ]

   Show a list of register names for the current target.  If no
arguments are given, it shows a list of the names of all the registers.
If integer numbers are given as arguments, it will print a list of the
names of the registers corresponding to the arguments.  To ensure
consistency between a register name and its number, the output list may
include empty register names.

GDB Command
...........

   GDB does not have a command which corresponds to
`-data-list-register-names'.  In `gdbtk' there is a corresponding
command `gdb_regnames'.

Example
.......

   For the PPC MBX board:
     (gdb)
     -data-list-register-names
     ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
     "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
     "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
     "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
     "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
     "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
     "", "pc","ps","cr","lr","ctr","xer"]
     (gdb)
     -data-list-register-names 1 2 3
     ^done,register-names=["r1","r2","r3"]
     (gdb)

The `-data-list-register-values' Command
----------------------------------------

Synopsis
........

      -data-list-register-values FMT [ ( REGNO )*]

   Display the registers' contents.  FMT is the format according to
which the registers' contents are to be returned, followed by an
optional list of numbers specifying the registers to display.  A
missing list of numbers indicates that the contents of all the
registers must be returned.

   Allowed formats for FMT are:

`x'
     Hexadecimal

`o'
     Octal

`t'
     Binary

`d'
     Decimal

`r'
     Raw

`N'
     Natural

GDB Command
...........

   The corresponding GDB commands are `info reg', `info all-reg', and
(in `gdbtk') `gdb_fetch_registers'.

Example
.......

   For a PPC MBX board (note: line breaks are for readability only, they
don't appear in the actual output):

     (gdb)
     -data-list-register-values r 64 65
     ^done,register-values=[{number="64",value="0xfe00a300"},
     {number="65",value="0x00029002"}]
     (gdb)
     -data-list-register-values x
     ^done,register-values=[{number="0",value="0xfe0043c8"},
     {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"},
     {number="3",value="0x0"},{number="4",value="0xa"},
     {number="5",value="0x3fff68"},{number="6",value="0x3fff58"},
     {number="7",value="0xfe011e98"},{number="8",value="0x2"},
     {number="9",value="0xfa202820"},{number="10",value="0xfa202808"},
     {number="11",value="0x1"},{number="12",value="0x0"},
     {number="13",value="0x4544"},{number="14",value="0xffdfffff"},
     {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"},
     {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"},
     {number="19",value="0xffffffff"},{number="20",value="0xffffffff"},
     {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"},
     {number="23",value="0xffffffff"},{number="24",value="0xffffffff"},
     {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"},
     {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"},
     {number="29",value="0x0"},{number="30",value="0xfe010000"},
     {number="31",value="0x0"},{number="32",value="0x0"},
     {number="33",value="0x0"},{number="34",value="0x0"},
     {number="35",value="0x0"},{number="36",value="0x0"},
     {number="37",value="0x0"},{number="38",value="0x0"},
     {number="39",value="0x0"},{number="40",value="0x0"},
     {number="41",value="0x0"},{number="42",value="0x0"},
     {number="43",value="0x0"},{number="44",value="0x0"},
     {number="45",value="0x0"},{number="46",value="0x0"},
     {number="47",value="0x0"},{number="48",value="0x0"},
     {number="49",value="0x0"},{number="50",value="0x0"},
     {number="51",value="0x0"},{number="52",value="0x0"},
     {number="53",value="0x0"},{number="54",value="0x0"},
     {number="55",value="0x0"},{number="56",value="0x0"},
     {number="57",value="0x0"},{number="58",value="0x0"},
     {number="59",value="0x0"},{number="60",value="0x0"},
     {number="61",value="0x0"},{number="62",value="0x0"},
     {number="63",value="0x0"},{number="64",value="0xfe00a300"},
     {number="65",value="0x29002"},{number="66",value="0x202f04b5"},
     {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"},
     {number="69",value="0x20002b03"}]
     (gdb)

The `-data-read-memory' Command
-------------------------------

Synopsis
........

      -data-read-memory [ -o BYTE-OFFSET ]
        ADDRESS WORD-FORMAT WORD-SIZE
        NR-ROWS NR-COLS [ ASCHAR ]

where:

`ADDRESS'
     An expression specifying the address of the first memory word to be
     read.  Complex expressions containing embedded white space should
     be quoted using the C convention.

`WORD-FORMAT'
     The format to be used to print the memory words.  The notation is
     the same as for GDB's `print' command (*note Output formats:
     Output Formats.).

`WORD-SIZE'
     The size of each memory word in bytes.

`NR-ROWS'
     The number of rows in the output table.

`NR-COLS'
     The number of columns in the output table.

`ASCHAR'
     If present, indicates that each row should include an ASCII dump.
     The value of ASCHAR is used as a padding character when a byte is
     not a member of the printable ASCII character set (printable ASCII
     characters are those whose code is between 32 and 126,
     inclusively).

`BYTE-OFFSET'
     An offset to add to the ADDRESS before fetching memory.

   This command displays memory contents as a table of NR-ROWS by
NR-COLS words, each word being WORD-SIZE bytes.  In total, `NR-ROWS *
NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes').
Should less than the requested number of bytes be returned by the
target, the missing words are identified using `N/A'.  The number of
bytes read from the target is returned in `nr-bytes' and the starting
address used to read memory in `addr'.

   The address of the next/previous row or page is available in
`next-row' and `prev-row', `next-page' and `prev-page'.

GDB Command
...........

   The corresponding GDB command is `x'.  `gdbtk' has `gdb_get_mem'
memory read command.

Example
.......

   Read six bytes of memory starting at `bytes+6' but then offset by
`-6' bytes.  Format as three rows of two columns.  One byte per word.
Display each word in hex.

     (gdb)
     9-data-read-memory -o -6 -- bytes+6 x 1 3 2
     9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
     next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
     prev-page="0x0000138a",memory=[
     {addr="0x00001390",data=["0x00","0x01"]},
     {addr="0x00001392",data=["0x02","0x03"]},
     {addr="0x00001394",data=["0x04","0x05"]}]
     (gdb)

   Read two bytes of memory starting at address `shorts + 64' and
display as a single word formatted in decimal.

     (gdb)
     5-data-read-memory shorts+64 d 2 1 1
     5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
     next-row="0x00001512",prev-row="0x0000150e",
     next-page="0x00001512",prev-page="0x0000150e",memory=[
     {addr="0x00001510",data=["128"]}]
     (gdb)

   Read thirty two bytes of memory starting at `bytes+16' and format as
eight rows of four columns.  Include a string encoding with `x' used as
the non-printable character.

     (gdb)
     4-data-read-memory bytes+16 x 1 8 4 x
     4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
     next-row="0x000013c0",prev-row="0x0000139c",
     next-page="0x000013c0",prev-page="0x00001380",memory=[
     {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"},
     {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"},
     {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"},
     {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"},
     {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"},
     {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"},
     {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"},
     {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}]
     (gdb)

The `-display-delete' Command
-----------------------------

Synopsis
........

      -display-delete NUMBER

   Delete the display NUMBER.

GDB Command
...........

   The corresponding GDB command is `delete display'.

Example
.......

   N.A.

The `-display-disable' Command
------------------------------

Synopsis
........

      -display-disable NUMBER

   Disable display NUMBER.

GDB Command
...........

   The corresponding GDB command is `disable display'.

Example
.......

   N.A.

The `-display-enable' Command
-----------------------------

Synopsis
........

      -display-enable NUMBER

   Enable display NUMBER.

GDB Command
...........

   The corresponding GDB command is `enable display'.

Example
.......

   N.A.

The `-display-insert' Command
-----------------------------

Synopsis
........

      -display-insert EXPRESSION

   Display EXPRESSION every time the program stops.

GDB Command
...........

   The corresponding GDB command is `display'.

Example
.......

   N.A.

The `-display-list' Command
---------------------------

Synopsis
........

      -display-list

   List the displays.  Do not show the current values.

GDB Command
...........

   The corresponding GDB command is `info display'.

Example
.......

   N.A.

The `-environment-cd' Command
-----------------------------

Synopsis
........

      -environment-cd PATHDIR

   Set GDB's working directory.

GDB Command
...........

   The corresponding GDB command is `cd'.

Example
.......

     (gdb)
     -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
     ^done
     (gdb)

The `-environment-directory' Command
------------------------------------

Synopsis
........

      -environment-directory PATHDIR

   Add directory PATHDIR to beginning of search path for source files.

GDB Command
...........

   The corresponding GDB command is `dir'.

Example
.......

     (gdb)
     -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
     ^done
     (gdb)

The `-environment-path' Command
-------------------------------

Synopsis
........

      -environment-path ( PATHDIR )+

   Add directories PATHDIR to beginning of search path for object files.

GDB Command
...........

   The corresponding GDB command is `path'.

Example
.......

     (gdb)
     -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
     ^done
     (gdb)

The `-environment-pwd' Command
------------------------------

Synopsis
........

      -environment-pwd

   Show the current working directory.

GDB command
...........

   The corresponding GDB command is `pwd'.

Example
.......

     (gdb)
     -environment-pwd
     ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
     ^done
     (gdb)


File: gdb.info,  Node: GDB/MI Program Control,  Next: GDB/MI Miscellaneous Commands,  Prev: GDB/MI Data Manipulation,  Up: GDB/MI

GDB/MI Program control
======================

Program termination
...................

   As a result of execution, the inferior program can run to
completion, if it doesn't encounter any breakpoints.  In this case the
output will include an exit code, if the program has exited
exceptionally.

Examples
........

Program exited normally:

     (gdb)
     -exec-run
     ^running
     (gdb)
     x = 55
     *stopped,reason="exited-normally"
     (gdb)

Program exited exceptionally:

     (gdb)
     -exec-run
     ^running
     (gdb)
     x = 55
     *stopped,reason="exited",exit-code="01"
     (gdb)

   Another way the program can terminate is if it receives a signal
such as `SIGINT'.  In this case, GDB/MI displays this:

     (gdb)
     *stopped,reason="exited-signalled",signal-name="SIGINT",
     signal-meaning="Interrupt"

The `-exec-abort' Command
-------------------------

Synopsis
........

      -exec-abort

   Kill the inferior running program.

GDB Command
...........

   The corresponding GDB command is `kill'.

Example
.......

   N.A.

The `-exec-arguments' Command
-----------------------------

Synopsis
........

      -exec-arguments ARGS

   Set the inferior program arguments, to be used in the next
`-exec-run'.

GDB Command
...........

   The corresponding GDB command is `set args'.

Example
.......

   Don't have one around.

The `-exec-continue' Command
----------------------------

Synopsis
........

      -exec-continue

   Asynchronous command.  Resumes the execution of the inferior program
until a breakpoint is encountered, or until the inferior exits.

GDB Command
...........

   The corresponding GDB corresponding is `continue'.

Example
.......

     -exec-continue
     ^running
     (gdb)
     @Hello world
     *stopped,reason="breakpoint-hit",bkptno="2",frame={func="foo",args=[],
     file="hello.c",line="13"}
     (gdb)

The `-exec-finish' Command
--------------------------

Synopsis
........

      -exec-finish

   Asynchronous command.  Resumes the execution of the inferior program
until the current function is exited.  Displays the results returned by
the function.

GDB Command
...........

   The corresponding GDB command is `finish'.

Example
.......

   Function returning `void'.

     -exec-finish
     ^running
     (gdb)
     @hello from foo
     *stopped,reason="function-finished",frame={func="main",args=[],
     file="hello.c",line="7"}
     (gdb)

   Function returning other than `void'.  The name of the internal GDB
variable storing the result is printed, together with the value itself.

     -exec-finish
     ^running
     (gdb)
     *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo",
     args=[{name="a",value="1"],{name="b",value="9"}},
     file="recursive2.c",line="14"},
     gdb-result-var="$1",return-value="0"
     (gdb)

The `-exec-interrupt' Command
-----------------------------

Synopsis
........

      -exec-interrupt

   Asynchronous command.  Interrupts the background execution of the
target.  Note how the token associated with the stop message is the one
for the execution command that has been interrupted.  The token for the
interrupt itself only appears in the `^done' output.  If the user is
trying to interrupt a non-running program, an error message will be
printed.

GDB Command
...........

   The corresponding GDB command is `interrupt'.

Example
.......

     (gdb)
     111-exec-continue
     111^running
     
     (gdb)
     222-exec-interrupt
     222^done
     (gdb)
     111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
     frame={addr="0x00010140",func="foo",args=[],file="try.c",line="13"}
     (gdb)
     
     (gdb)
     -exec-interrupt
     ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
     (gdb)

The `-exec-next' Command
------------------------

Synopsis
........

      -exec-next

   Asynchronous command.  Resumes execution of the inferior program,
stopping when the beginning of the next source line is reached.

GDB Command
...........

   The corresponding GDB command is `next'.

Example
.......

     -exec-next
     ^running
     (gdb)
     *stopped,reason="end-stepping-range",line="8",file="hello.c"
     (gdb)

The `-exec-next-instruction' Command
------------------------------------

Synopsis
........

      -exec-next-instruction

   Asynchronous command.  Executes one machine instruction.  If the
instruction is a function call continues until the function returns.  If
the program stops at an instruction in the middle of a source line, the
address will be printed as well.

GDB Command
...........

   The corresponding GDB command is `nexti'.

Example
.......

     (gdb)
     -exec-next-instruction
     ^running
     
     (gdb)
     *stopped,reason="end-stepping-range",
     addr="0x000100d4",line="5",file="hello.c"
     (gdb)

The `-exec-return' Command
--------------------------

Synopsis
........

      -exec-return

   Makes current function return immediately.  Doesn't execute the
inferior.  Displays the new current frame.

GDB Command
...........

   The corresponding GDB command is `return'.

Example
.......

     (gdb)
     200-break-insert callee4
     200^done,bkpt={number="1",addr="0x00010734",
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
     (gdb)
     000-exec-run
     000^running
     (gdb)
     000*stopped,reason="breakpoint-hit",bkptno="1",
     frame={func="callee4",args=[],
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
     (gdb)
     205-break-delete
     205^done
     (gdb)
     111-exec-return
     111^done,frame={level="0 ",func="callee3",
     args=[{name="strarg",
     value="0x11940 \"A string argument.\""}],
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
     (gdb)

The `-exec-run' Command
-----------------------

Synopsis
........

      -exec-run

   Asynchronous command.  Starts execution of the inferior from the
beginning.  The inferior executes until either a breakpoint is
encountered or the program exits.

GDB Command
...........

   The corresponding GDB command is `run'.

Example
.......

     (gdb)
     -break-insert main
     ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
     (gdb)
     -exec-run
     ^running
     (gdb)
     *stopped,reason="breakpoint-hit",bkptno="1",
     frame={func="main",args=[],file="recursive2.c",line="4"}
     (gdb)

The `-exec-show-arguments' Command
----------------------------------

Synopsis
........

      -exec-show-arguments

   Print the arguments of the program.

GDB Command
...........

   The corresponding GDB command is `show args'.

Example
.......

   N.A.

The `-exec-step' Command
------------------------

Synopsis
........

      -exec-step

   Asynchronous command.  Resumes execution of the inferior program,
stopping when the beginning of the next source line is reached, if the
next source line is not a function call.  If it is, stop at the first
instruction of the called function.

GDB Command
...........

   The corresponding GDB command is `step'.

Example
.......

   Stepping into a function:

     -exec-step
     ^running
     (gdb)
     *stopped,reason="end-stepping-range",
     frame={func="foo",args=[{name="a",value="10"},
     {name="b",value="0"}],file="recursive2.c",line="11"}
     (gdb)

   Regular stepping:

     -exec-step
     ^running
     (gdb)
     *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
     (gdb)

The `-exec-step-instruction' Command
------------------------------------

Synopsis
........

      -exec-step-instruction

   Asynchronous command.  Resumes the inferior which executes one
machine instruction.  The output, once GDB has stopped, will vary
depending on whether we have stopped in the middle of a source line or
not.  In the former case, the address at which the program stopped will
be printed as well.

GDB Command
...........

   The corresponding GDB command is `stepi'.

Example
.......

     (gdb)
     -exec-step-instruction
     ^running
     
     (gdb)
     *stopped,reason="end-stepping-range",
     frame={func="foo",args=[],file="try.c",line="10"}
     (gdb)
     -exec-step-instruction
     ^running
     
     (gdb)
     *stopped,reason="end-stepping-range",
     frame={addr="0x000100f4",func="foo",args=[],file="try.c",line="10"}
     (gdb)

The `-exec-until' Command
-------------------------

Synopsis
........

      -exec-until [ LOCATION ]

   Asynchronous command.  Executes the inferior until the LOCATION
specified in the argument is reached.  If there is no argument, the
inferior executes until a source line greater than the current one is
reached.  The reason for stopping in this case will be
`location-reached'.

GDB Command
...........

   The corresponding GDB command is `until'.

Example
.......

     (gdb)
     -exec-until recursive2.c:6
     ^running
     (gdb)
     x = 55
     *stopped,reason="location-reached",frame={func="main",args=[],
     file="recursive2.c",line="6"}
     (gdb)

The `-file-exec-and-symbols' Command
------------------------------------

Synopsis
........

      -file-exec-and-symbols FILE

   Specify the executable file to be debugged.  This file is the one
from which the symbol table is also read.  If no file is specified, the
command clears the executable and symbol information.  If breakpoints
are set when using this command with no arguments, GDB will produce
error messages.  Otherwise, no output is produced, except a completion
notification.

GDB Command
...........

   The corresponding GDB command is `file'.

Example
.......

     (gdb)
     -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
     ^done
     (gdb)

The `-file-exec-file' Command
-----------------------------

Synopsis
........

      -file-exec-file FILE

   Specify the executable file to be debugged.  Unlike
`-file-exec-and-symbols', the symbol table is _not_ read from this
file.  If used without argument, GDB clears the information about the
executable file.  No output is produced, except a completion
notification.

GDB Command
...........

   The corresponding GDB command is `exec-file'.

Example
.......

     (gdb)
     -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
     ^done
     (gdb)

The `-file-list-exec-sections' Command
--------------------------------------

Synopsis
........

      -file-list-exec-sections

   List the sections of the current executable file.

GDB Command
...........

   The GDB command `info file' shows, among the rest, the same
information as this command.  `gdbtk' has a corresponding command
`gdb_load_info'.

Example
.......

   N.A.

The `-file-list-exec-source-files' Command
------------------------------------------

Synopsis
........

      -file-list-exec-source-files

   List the source files for the current executable.

GDB Command
...........

   There's no GDB command which directly corresponds to this one.
`gdbtk' has an analogous command `gdb_listfiles'.

Example
.......

   N.A.

The `-file-list-shared-libraries' Command
-----------------------------------------

Synopsis
........

      -file-list-shared-libraries

   List the shared libraries in the program.

GDB Command
...........

   The corresponding GDB command is `info shared'.

Example
.......

   N.A.

The `-file-list-symbol-files' Command
-------------------------------------

Synopsis
........

      -file-list-symbol-files

   List symbol files.

GDB Command
...........

   The corresponding GDB command is `info file' (part of it).

Example
.......

   N.A.

The `-file-symbol-file' Command
-------------------------------

Synopsis
........

      -file-symbol-file FILE

   Read symbol table info from the specified FILE argument.  When used
without arguments, clears GDB's symbol table info.  No output is
produced, except for a completion notification.

GDB Command
...........

   The corresponding GDB command is `symbol-file'.

Example
.......

     (gdb)
     -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
     ^done
     (gdb)


File: gdb.info,  Node: GDB/MI Miscellaneous Commands,  Next: GDB/MI Stack Manipulation,  Prev: GDB/MI Program Control,  Up: GDB/MI

Miscellaneous GDB commands in GDB/MI
====================================

The `-gdb-exit' Command
-----------------------

Synopsis
........

      -gdb-exit

   Exit GDB immediately.

GDB Command
...........

   Approximately corresponds to `quit'.

Example
.......

     (gdb)
     -gdb-exit

The `-gdb-set' Command
----------------------

Synopsis
........

      -gdb-set

   Set an internal GDB variable.

GDB Command
...........

   The corresponding GDB command is `set'.

Example
.......

     (gdb)
     -gdb-set $foo=3
     ^done
     (gdb)

The `-gdb-show' Command
-----------------------

Synopsis
........

      -gdb-show

   Show the current value of a GDB variable.

GDB command
...........

   The corresponding GDB command is `show'.

Example
.......

     (gdb)
     -gdb-show annotate
     ^done,value="0"
     (gdb)

The `-gdb-version' Command
--------------------------

Synopsis
........

      -gdb-version

   Show version information for GDB.  Used mostly in testing.

GDB Command
...........

   There's no equivalent GDB command.  GDB by default shows this
information when you start an interactive session.

Example
.......

     (gdb)
     -gdb-version
     ~GNU gdb 5.2.1
     ~Copyright 2000 Free Software Foundation, Inc.
     ~GDB is free software, covered by the GNU General Public License, and
     ~you are welcome to change it and/or distribute copies of it under
     ~ certain conditions.
     ~Type "show copying" to see the conditions.
     ~There is absolutely no warranty for GDB.  Type "show warranty" for
     ~ details.
     ~This GDB was configured as
      "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
     ^done
     (gdb)


File: gdb.info,  Node: GDB/MI Stack Manipulation,  Next: GDB/MI Symbol Query,  Prev: GDB/MI Miscellaneous Commands,  Up: GDB/MI

GDB/MI Stack Manipulation Commands
==================================

The `-stack-info-frame' Command
-------------------------------

Synopsis
........

      -stack-info-frame

   Get info on the current frame.

GDB Command
...........

   The corresponding GDB command is `info frame' or `frame' (without
arguments).

Example
.......

   N.A.

The `-stack-info-depth' Command
-------------------------------

Synopsis
........

      -stack-info-depth [ MAX-DEPTH ]

   Return the depth of the stack.  If the integer argument MAX-DEPTH is
specified, do not count beyond MAX-DEPTH frames.

GDB Command
...........

   There's no equivalent GDB command.

Example
.......

   For a stack with frame levels 0 through 11:

     (gdb)
     -stack-info-depth
     ^done,depth="12"
     (gdb)
     -stack-info-depth 4
     ^done,depth="4"
     (gdb)
     -stack-info-depth 12
     ^done,depth="12"
     (gdb)
     -stack-info-depth 11
     ^done,depth="11"
     (gdb)
     -stack-info-depth 13
     ^done,depth="12"
     (gdb)

The `-stack-list-arguments' Command
-----------------------------------

Synopsis
........

      -stack-list-arguments SHOW-VALUES
         [ LOW-FRAME HIGH-FRAME ]

   Display a list of the arguments for the frames between LOW-FRAME and
HIGH-FRAME (inclusive).  If LOW-FRAME and HIGH-FRAME are not provided,
list the arguments for the whole call stack.

   The SHOW-VALUES argument must have a value of 0 or 1.  A value of 0
means that only the names of the arguments are listed, a value of 1
means that both names and values of the arguments are printed.

GDB Command
...........

   GDB does not have an equivalent command.  `gdbtk' has a
`gdb_get_args' command which partially overlaps with the functionality
of `-stack-list-arguments'.

Example
.......

     (gdb)
     -stack-list-frames
     ^done,
     stack=[
     frame={level="0 ",addr="0x00010734",func="callee4",
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"},
     frame={level="1 ",addr="0x0001076c",func="callee3",
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"},
     frame={level="2 ",addr="0x0001078c",func="callee2",
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"},
     frame={level="3 ",addr="0x000107b4",func="callee1",
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"},
     frame={level="4 ",addr="0x000107e0",func="main",
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"}]
     (gdb)
     -stack-list-arguments 0
     ^done,
     stack-args=[
     frame={level="0",args=[]},
     frame={level="1",args=[name="strarg"]},
     frame={level="2",args=[name="intarg",name="strarg"]},
     frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]},
     frame={level="4",args=[]}]
     (gdb)
     -stack-list-arguments 1
     ^done,
     stack-args=[
     frame={level="0",args=[]},
     frame={level="1",
      args=[{name="strarg",value="0x11940 \"A string argument.\""}]},
     frame={level="2",args=[
     {name="intarg",value="2"},
     {name="strarg",value="0x11940 \"A string argument.\""}]},
     {frame={level="3",args=[
     {name="intarg",value="2"},
     {name="strarg",value="0x11940 \"A string argument.\""},
     {name="fltarg",value="3.5"}]},
     frame={level="4",args=[]}]
     (gdb)
     -stack-list-arguments 0 2 2
     ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}]
     (gdb)
     -stack-list-arguments 1 2 2
     ^done,stack-args=[frame={level="2",
     args=[{name="intarg",value="2"},
     {name="strarg",value="0x11940 \"A string argument.\""}]}]
     (gdb)

The `-stack-list-frames' Command
--------------------------------

Synopsis
........

      -stack-list-frames [ LOW-FRAME HIGH-FRAME ]

   List the frames currently on the stack.  For each frame it displays
the following info:

`LEVEL'
     The frame number, 0 being the topmost frame, i.e. the innermost
     function.

`ADDR'
     The `$pc' value for that frame.

`FUNC'
     Function name.

`FILE'
     File name of the source file where the function lives.

`LINE'
     Line number corresponding to the `$pc'.

   If invoked without arguments, this command prints a backtrace for the
whole stack.  If given two integer arguments, it shows the frames whose
levels are between the two arguments (inclusive).  If the two arguments
are equal, it shows the single frame at the corresponding level.

GDB Command
...........

   The corresponding GDB commands are `backtrace' and `where'.

Example
.......

   Full stack backtrace:

     (gdb)
     -stack-list-frames
     ^done,stack=
     [frame={level="0 ",addr="0x0001076c",func="foo",
       file="recursive2.c",line="11"},
     frame={level="1 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"},
     frame={level="2 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"},
     frame={level="3 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"},
     frame={level="4 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"},
     frame={level="5 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"},
     frame={level="6 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"},
     frame={level="7 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"},
     frame={level="8 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"},
     frame={level="9 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"},
     frame={level="10",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"},
     frame={level="11",addr="0x00010738",func="main",
       file="recursive2.c",line="4"}]
     (gdb)

   Show frames between LOW_FRAME and HIGH_FRAME:

     (gdb)
     -stack-list-frames 3 5
     ^done,stack=
     [frame={level="3 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"},
     frame={level="4 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"},
     frame={level="5 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"}]
     (gdb)

   Show a single frame:

     (gdb)
     -stack-list-frames 3 3
     ^done,stack=
     [frame={level="3 ",addr="0x000107a4",func="foo",
       file="recursive2.c",line="14"}]
     (gdb)

The `-stack-list-locals' Command
--------------------------------

Synopsis
........

      -stack-list-locals PRINT-VALUES

   Display the local variable names for the current frame.  With an
argument of 0 prints only the names of the variables, with argument of 1
prints also their values.

GDB Command
...........

   `info locals' in GDB, `gdb_get_locals' in `gdbtk'.

Example
.......

     (gdb)
     -stack-list-locals 0
     ^done,locals=[name="A",name="B",name="C"]
     (gdb)
     -stack-list-locals 1
     ^done,locals=[{name="A",value="1"},{name="B",value="2"},
       {name="C",value="3"}]
     (gdb)

The `-stack-select-frame' Command
---------------------------------

Synopsis
........

      -stack-select-frame FRAMENUM

   Change the current frame.  Select a different frame FRAMENUM on the
stack.

GDB Command
...........

   The corresponding GDB commands are `frame', `up', `down',
`select-frame', `up-silent', and `down-silent'.

Example
.......

     (gdb)
     -stack-select-frame 2
     ^done
     (gdb)


File: gdb.info,  Node: GDB/MI Symbol Query,  Next: GDB/MI Target Manipulation,  Prev: GDB/MI Stack Manipulation,  Up: GDB/MI

GDB/MI Symbol Query Commands
============================

The `-symbol-info-address' Command
----------------------------------

Synopsis
........

      -symbol-info-address SYMBOL

   Describe where SYMBOL is stored.

GDB Command
...........

   The corresponding GDB command is `info address'.

Example
.......

   N.A.

The `-symbol-info-file' Command
-------------------------------

Synopsis
........

      -symbol-info-file

   Show the file for the symbol.

GDB Command
...........

   There's no equivalent GDB command.  `gdbtk' has `gdb_find_file'.

Example
.......

   N.A.

The `-symbol-info-function' Command
-----------------------------------

Synopsis
........

      -symbol-info-function

   Show which function the symbol lives in.

GDB Command
...........

   `gdb_get_function' in `gdbtk'.

Example
.......

   N.A.

The `-symbol-info-line' Command
-------------------------------

Synopsis
........

      -symbol-info-line

   Show the core addresses of the code for a source line.

GDB Command
...........

   The corresponding GDB comamnd is `info line'.  `gdbtk' has the
`gdb_get_line' and `gdb_get_file' commands.

Example
.......

   N.A.

The `-symbol-info-symbol' Command
---------------------------------

Synopsis
........

      -symbol-info-symbol ADDR

   Describe what symbol is at location ADDR.

GDB Command
...........

   The corresponding GDB command is `info symbol'.

Example
.......

   N.A.

The `-symbol-list-functions' Command
------------------------------------

Synopsis
........

      -symbol-list-functions

   List the functions in the executable.

GDB Command
...........

   `info functions' in GDB, `gdb_listfunc' and `gdb_search' in `gdbtk'.

Example
.......

   N.A.

The `-symbol-list-types' Command
--------------------------------

Synopsis
........

      -symbol-list-types

   List all the type names.

GDB Command
...........

   The corresponding commands are `info types' in GDB, `gdb_search' in
`gdbtk'.

Example
.......

   N.A.

The `-symbol-list-variables' Command
------------------------------------

Synopsis
........

      -symbol-list-variables

   List all the global and static variable names.

GDB Command
...........

   `info variables' in GDB, `gdb_search' in `gdbtk'.

Example
.......

   N.A.

The `-symbol-locate' Command
----------------------------

Synopsis
........

      -symbol-locate

GDB Command
...........

   `gdb_loc' in `gdbtk'.

Example
.......

   N.A.

The `-symbol-type' Command
--------------------------

Synopsis
........

      -symbol-type VARIABLE

   Show type of VARIABLE.

GDB Command
...........

   The corresponding GDB command is `ptype', `gdbtk' has
`gdb_obj_variable'.

Example
.......

   N.A.


File: gdb.info,  Node: GDB/MI Target Manipulation,  Next: GDB/MI Thread Commands,  Prev: GDB/MI Symbol Query,  Up: GDB/MI

GDB/MI Target Manipulation Commands
===================================

The `-target-attach' Command
----------------------------

Synopsis
........

      -target-attach PID | FILE

   Attach to a process PID or a file FILE outside of GDB.

GDB command
...........

   The corresponding GDB command is `attach'.

Example
.......

   N.A.

The `-target-compare-sections' Command
--------------------------------------

Synopsis
........

      -target-compare-sections [ SECTION ]

   Compare data of section SECTION on target to the exec file.  Without
the argument, all sections are compared.

GDB Command
...........

   The GDB equivalent is `compare-sections'.

Example
.......

   N.A.

The `-target-detach' Command
----------------------------

Synopsis
........

      -target-detach

   Disconnect from the remote target.  There's no output.

GDB command
...........

   The corresponding GDB command is `detach'.

Example
.......

     (gdb)
     -target-detach
     ^done
     (gdb)

The `-target-download' Command
------------------------------

Synopsis
........

      -target-download

   Loads the executable onto the remote target.  It prints out an
update message every half second, which includes the fields:

`section'
     The name of the section.

`section-sent'
     The size of what has been sent so far for that section.

`section-size'
     The size of the section.

`total-sent'
     The total size of what was sent so far (the current and the
     previous sections).

`total-size'
     The size of the overall executable to download.

Each message is sent as status record (*note GDB/MI Output Syntax:
GDB/MI Output Syntax.).

   In addition, it prints the name and size of the sections, as they are
downloaded.  These messages include the following fields:

`section'
     The name of the section.

`section-size'
     The size of the section.

`total-size'
     The size of the overall executable to download.

At the end, a summary is printed.

GDB Command
...........

   The corresponding GDB command is `load'.

Example
.......

   Note: each status message appears on a single line.  Here the
messages have been broken down so that they can fit onto a page.

     (gdb)
     -target-download
     +download,{section=".text",section-size="6668",total-size="9880"}
     +download,{section=".text",section-sent="512",section-size="6668",
     total-sent="512",total-size="9880"}
     +download,{section=".text",section-sent="1024",section-size="6668",
     total-sent="1024",total-size="9880"}
     +download,{section=".text",section-sent="1536",section-size="6668",
     total-sent="1536",total-size="9880"}
     +download,{section=".text",section-sent="2048",section-size="6668",
     total-sent="2048",total-size="9880"}
     +download,{section=".text",section-sent="2560",section-size="6668",
     total-sent="2560",total-size="9880"}
     +download,{section=".text",section-sent="3072",section-size="6668",
     total-sent="3072",total-size="9880"}
     +download,{section=".text",section-sent="3584",section-size="6668",
     total-sent="3584",total-size="9880"}
     +download,{section=".text",section-sent="4096",section-size="6668",
     total-sent="4096",total-size="9880"}
     +download,{section=".text",section-sent="4608",section-size="6668",
     total-sent="4608",total-size="9880"}
     +download,{section=".text",section-sent="5120",section-size="6668",
     total-sent="5120",total-size="9880"}
     +download,{section=".text",section-sent="5632",section-size="6668",
     total-sent="5632",total-size="9880"}
     +download,{section=".text",section-sent="6144",section-size="6668",
     total-sent="6144",total-size="9880"}
     +download,{section=".text",section-sent="6656",section-size="6668",
     total-sent="6656",total-size="9880"}
     +download,{section=".init",section-size="28",total-size="9880"}
     +download,{section=".fini",section-size="28",total-size="9880"}
     +download,{section=".data",section-size="3156",total-size="9880"}
     +download,{section=".data",section-sent="512",section-size="3156",
     total-sent="7236",total-size="9880"}
     +download,{section=".data",section-sent="1024",section-size="3156",
     total-sent="7748",total-size="9880"}
     +download,{section=".data",section-sent="1536",section-size="3156",
     total-sent="8260",total-size="9880"}
     +download,{section=".data",section-sent="2048",section-size="3156",
     total-sent="8772",total-size="9880"}
     +download,{section=".data",section-sent="2560",section-size="3156",
     total-sent="9284",total-size="9880"}
     +download,{section=".data",section-sent="3072",section-size="3156",
     total-sent="9796",total-size="9880"}
     ^done,address="0x10004",load-size="9880",transfer-rate="6586",
     write-rate="429"
     (gdb)

The `-target-exec-status' Command
---------------------------------

Synopsis
........

      -target-exec-status

   Provide information on the state of the target (whether it is
running or not, for instance).

GDB Command
...........

   There's no equivalent GDB command.

Example
.......

   N.A.

The `-target-list-available-targets' Command
--------------------------------------------

Synopsis
........

      -target-list-available-targets

   List the possible targets to connect to.

GDB Command
...........

   The corresponding GDB command is `help target'.

Example
.......

   N.A.

The `-target-list-current-targets' Command
------------------------------------------

Synopsis
........

      -target-list-current-targets

   Describe the current target.

GDB Command
...........

   The corresponding information is printed by `info file' (among other
things).

Example
.......

   N.A.

The `-target-list-parameters' Command
-------------------------------------

Synopsis
........

      -target-list-parameters

GDB Command
...........

   No equivalent.

Example
.......

   N.A.

The `-target-select' Command
----------------------------

Synopsis
........

      -target-select TYPE PARAMETERS ...

   Connect GDB to the remote target.  This command takes two args:

`TYPE'
     The type of target, for instance `async', `remote', etc.

`PARAMETERS'
     Device names, host names and the like.  *Note Commands for
     managing targets: Target Commands, for more details.

   The output is a connection notification, followed by the address at
which the target program is, in the following form:

     ^connected,addr="ADDRESS",func="FUNCTION NAME",
       args=[ARG LIST]

GDB Command
...........

   The corresponding GDB command is `target'.

Example
.......

     (gdb)
     -target-select async /dev/ttya
     ^connected,addr="0xfe00a300",func="??",args=[]
     (gdb)