This file documents GDB/MI, a Machine Interface to GDB.

Copyright (C) 2000, Free Software Foundation, Inc. Contributed by Cygnus Solutions.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

Overview
********

Function and Purpose
====================

GDB/MI is a line based machine oriented text interface to GDB.  It is specifically intended to support the development of systems which use the debugger as just one small component of a larger system.

This Document
=============

This document is a specification of the GDB/MI interface.  It is written in the form of a reference manual.

Terminology
===========

Dependencies
============

Acknowledgments
===============

In alphabetic order: Fernando Nasser, Stan Shebs and Elena Zannoni.

Command Syntax
**************

Input Syntax
============

<command> ==>
     <cli-command> | <mi-command>

<cli-command> ==>
     [ <token> ] "any existing GDB CLI command" <nl>

<mi-command> ==>
     [ <token> ] ``-'' <operation> ( `` '' <option> )* [ `` --'' ] ( `` '' <parameter> )* <nl>

<token> ==>
     ``any sequence of digits''

<option> ==>
     ``-'' <parameter> [ `` '' <parameter> ]

<parameter> ==>
     <non-blank-sequence> | <c-string>

<operation> ==>
     any of the operations described in this document.

<non-blank-sequence> ==>
     anything provided it doesn't contain special characters such as ``-'' <nl>, ``"'' and of course `` ''.

<c-string> ==>
     ``"'' <seven-bit-iso-c-string-content> ``"''

<nl> ==>
     CR | CR-LF

Notes:

  * The CLI commands are still handled by the MI interpreter; their output is described below

  * The <token>, when present, is passed back when the command finishes.

  * Some mi commands accept optional arguments as part of the parameter list. Each option is identified by a leading - (dash) and may be followed by an option argument parameter.  Options occure first in the parameter list and can be delimiated from normal parameters using --.

Pragmatics:

  * We want easy access to the existing CLI syntax (for debugging).

  * We want it easy to spot a MI operation

Output Syntax
=============

The output from GDB/MI consists of zero or more out-of-band records followed, optionally, by a single result record.  The result record being for the most recent command.  The sequence of output records is terminated by ``(gdb)''.

If an input command was prefixed with a <token> then the corresponding output for that command will also be prefixed by that same token.

<output> ==>
     ( <out-of-band-record> )* [ <result-record> ] ``(gdb)'' <nl>

<result-record> ==>
     [ <token> ] ``^'' <result-class> ( ``,'' <result> )* <nl>

<out-of-band-record> ==>
     <async-record> | <stream-record>

<async-record> ==>
     <exec-async-output> | <status-async-output> | <notify-async-output>

<exec-async-output> ==>
     [ <token> ] ``*'' <async-output>

<status-async-output> ==>
     [ <token> ] ``+'' <async-output>

<notify-async-output> ==>
     [ <token> ] ``='' <async-output>

<async-output> ==>
     <async-class> ( ``,'' <result> )* <nl>

<result-class> ==>
     ``done'' | ``running'' | ``connected'' | ``error'' | ``exit''

<async-class> ==>
     ``stopped'' | others (depending on needs, still in development)

<result> ==>
     [ <string> ``='' ] <value>

<value> ==>
     <const> | ``{'' <result> ( ``,'' <result> )* ``}''

<const> ==>
     <c-string>

<stream-record> ==>
     <console-stream-output> | <target-stream-output> | <log-stream-output>

<console-stream-output> ==>
     ``~'' <c-string>

<target-stream-output> ==>
     ``@'' <c-string>

<log-stream-output> ==>
     ``&'' <c-string>

<nl> ==>
     CR | CR-LF

<token> ==>
     ``any sequence of digits''

In addition, the following are still being developed.

<query>
     This action is currently undefined.

Notes:

  * All output sequences end in a single line containing a period.

  * The <token> is from the corresponding request.  If an execution command is interrupted by the -exec-interrupt command, the token associated with the `*stopped' message is the one of the original execution command, not the one of the interrupt-command.

  * <status-async-output> contains on-going status information about the progress of a slow operation.  It can be discarded. All status output is prefixed by the prefix `+'.

  * <exec-async-output> contains asynchronous state change on the target (stopped, started, disappeared). All async output is prefixed by the prefix `*'.

  * <notify-async-output> contains supplementary information that the client should handle (new breakpoint information). All notify output is prefixed by the prefix `='.

  * <console-stream-output> is output that should be displayed as is in the console.  It is the textual response to a CLI command. All the console output is prefixed by the prefix ``~''.

  * <target-stream-output> is the output produced by the target program. All the target output is prefixed by the prefix ``@''.

  * <log-stream-output> is output text coming from GDB's internals, for instance messages that should be displayed as part of an error log.  All the log output is prefixed by the prefix ``&''.

Simple Examples
===============

Target stop:
------------

     -> -stop
     <- (gdb)

(later)

     <- *stop,reason="stop",address="0x123",source="a.c:123"
     <- (gdb)

Simple CLI command being passed through the MI and on to the CLI.
-----------------------------------------------------------------

     -> print 1+2
     <- ~3\n
     <- (gdb)

Command with side effects:
--------------------------

     -> -symbol-file xyz.exe
     <- *breakpoint,nr="3",address="0x123",source="a.c:123"
     <- (gdb)

A bad command:
--------------

     -> -rubbish
     <- error,"Rubbish not found"
     <- (gdb)

CLI compatibility
*****************

To help users familiar with the GDB's existing CLI interface, the GDB/MI will accept existing CLI commands.  As specified by the syntax, such commands can be directly entered into the MI interface and GDB will respond.

The mechanism is provided as an aid to developers of MI clients and not as a reliable interface into the CLI.  Since the command is being interpreteted in an environment that assumes MI behaviour the exact output of such commands is likely to end up being an un-supported hybrid of MI and CLI output.

Output Records
**************

Result Records
==============

In addition to a number of out-of-band notifications the response to an MI command includes one of the following result indications.

``^done'' [ ``,'' <results> ]
     The synchronous operation was successful, <results> is the return value.

``^running''
     The asynchronous operation was successfully started.  The target is running.  Is this one correct should it be an out-of-band notification?

``^error'' ``,'' <c-string>
     The operation failed.  The <c-string> contains the corresponding error message.

Stream Records
==============

GDB internally maintains a number of output streams: the console, the target, and the log.  The output intended for each of these streams is tunneled through the MI interface using stream records.

In addition to the prefix each stream record contains a <string-output>.  This is either raw text (with an implicit new line) or a quoted C string (which does not contain an implicit newline).

``~'' <string-output>
     The console output stream contains text that should be displayed in the CLI console window.  It contains the textual responses to CLI commands.

``@'' <string-output>
     The target output stream contains any textual output from the running target.

``&'' <string-output>
     The LOG stream contains debugging messages being produced by GDB's internals.

Out-of-band Records.
====================

Out-of-band records are used to notify the MI client of additional changes that have occurred.  Those changes can either be a consequence of an MI (breakpoint modified) or as a result of target activity (target stopped).

The following is a preliminary list of possible out-of-band records.

``*'' ``stop''

Command Description Format
**************************

The remaining chapters describe blocks of commands.  Each block of commands is laid out in a fashion similar to this chapter.

Note the the line breaks shown in the examples are here only for readability. They don't appear in the real output. Note that the commands with a non available example (N.A.) are not yet implemented.

Motivation
==========

What motivates the collection of commands

Introduction
============

Brief introduction to the commands as a whole.

Operations
==========

-command <args>...
------------------

Result
......

Out-of-band
...........

Notes
.....

Example
.......

Breakpoint table commands
*************************

-break-after <number> <count>
=============================

The breakpoint number <number> is not in effect until it has been hit <count> times. Note how this is reflected in the output of the -break-list command.

GDB command
-----------

ignore

Example
-------

     (gdb)
     -break-insert main
     ^done,bkpt={number="1",addr="0x000100d0",file="hello.c",line="5"}
     (gdb)
     -break-after 1 3
     ~
     ^done
     (gdb)
     -break-list
     ^done,BreakpointTable={hdr={"Num","Type","Disp","Enb","Address","What"},
     bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
     addr="0x000100d0",func="main",file="hello.c",line="5",times="0",ignore="3"}}
     (gdb)

-break-condition <number> <expr>
================================

Breakpoint <number> will stop the program only if the condition in <expr> is true. The condition becomes part of the -break-list output.

GDB command
-----------

condition

Example
-------

     (gdb)
     -break-condition 1 1
     ^done
     (gdb)
     -break-list
     ^done,BreakpointTable={hdr={"Num","Type","Disp","Enb","Address","What"},
     bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
     addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",times="0",ignore="3"}}
     (gdb)

-break-delete { <breakpoint> }+
===============================

Delete the breakpoint(s) specified in the argument list. This is obviously reflected in the breakpoint list.

GDB command
-----------

delete

Example
-------

     (gdb)
     -break-delete 1
     ^done
     (gdb)
     -break-list
     ^done,BreakpointTable={}
     (gdb)

-break-disable { <breakpoint> }+
================================

Disable the breakpoint(s). Note how the field 'enabled' in the break list is now set to 'n'.

GDB command
-----------

disable

Example
-------

     (gdb)
     -break-disable 2
     ^done
     (gdb)
     -break-list
     ^done,BreakpointTable={hdr={"Num","Type","Disp","Enb","Address","What"},
     bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
     addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}}
     (gdb)

-break-enable { <breakpoint> }+
===============================

Enable a previously disabled breakpoint(s).

GDB command
-----------

enable

Example
-------

     (gdb)
     enable 2
     ^done
     (gdb)
     -break-list
     ^done,BreakpointTable={hdr={"Num","Type","Disp","Enb","Address","What"},
     bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
     addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}}
     (gdb)

-break-info <breakpoint>
========================

REDUNDANT??? Get information about a single breakpoint.

GDB command
-----------

Example
-------

N.A.

-break-insert [ "-t" ] [ "-h" ] [ "-r" ] [ "-c" <condition> ] [ "-i" <ignore-count> ] [ "-p" <thread> ] [ <line> | <addr> ]
===========================================================================================================================

<line>, if specified, accordingly to the gdb manual can be one of:

  * function

  * filename:linenum

  * filename:function

  * *address

The possible forms of this command are:

-t
     Insert a tempoary breakpoint.

-h
     Insert a hardware breakpoint.

-c <condition>
     Make the breakpoint conditional on <condition>

-i <ignore-count>
     Initialize the <ignore-count>

-r
     Insert a regular breakpoint in all the functions whose names match the given regular expression.  Other flags are not applicable to regular expresson.

The result is in the form:

^done,bkptno="<gdb number for this breakpoint>",func="<name of the function where the breakpoint was inserted>",file="<source file which contains this function>",line="<source line number within the file>"

Note: this is open to change.  An out-of-band breakpoint instead of part of the result?

GDB command
-----------

break, tbreak, hbreak, thbreak, rbreak.

Example
-------

     (gdb)
     -break-insert main
     ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
     (gdb)
     -break-insert -t foo
     ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",line="11"}
     (gdb)
     -break-list
     ^done,BreakpointTable={hdr={"Num","Type","Disp","Enb","Address","What"},
     bkpt={number="1",type="breakpoint",disp="keep",enabled="y",addr="0x0001072c",
     func="main",file="recursive2.c",line="4",times="0"},
     bkpt={number="2",type="breakpoint",disp="del",enabled="y",addr="0x00010774",
     func="foo",file="recursive2.c",line="11",times="0"}}
     (gdb)
     -break-insert -r foo.*
     ~int foo(int, int);
     ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c",line="11"}
     (gdb)

-break-list
===========

Displays the list of inserted breakpoints, showing the following fields:

Number
     Number of the breakpoint

Type
     Type of the breakpoint: breakpoint or watchpoint

Disposition
     Should the breakpoint be deleted or disabled when it is hit: keep or nokeep

Enabled
     Is the breakpoint enabled or no: y or n

Address
     Memory location at which the breakpoint is set.

What
     Logical location of the breakpoint, expressed by function name, file name, line number.

times
     Number of times the breakpoint has been hit.

If there are no breakpoints or watchpoints, the BreakpointTable field is an empty list.

GDB command
-----------

info break

Example 1
---------

     (gdb)
     -break-list
     ^done,BreakpointTable={hdr={"Num","Type","Disp","Enb","Address","What"},
     bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
     addr="0x000100d0",func="main",file="hello.c",line="5",times="0"},
     bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
     addr="0x00010114",func="foo",file="hello.c",line="13",times="0"}}
     (gdb)

Example 2
---------

     (gdb)
     -break-list
     ^done,BreakpointTable={}
     (gdb)

-break-watch [ "-a" | "-r" ]
============================

Create a watchpoint.  With the ``-a'' option it will create an access watchpoint, i.e. a watchpoints that triggers either on a read or on a write on the memory location.  With the ``-r'' option, the watchoint created is a read watchpoint, i.e. it will trigger only when the memory location os accessed for reading.  Without either of the options, the watchpoint created is a regular watchpoint, i.e. it will trigger whe the memory location is accessed for writing.

Note that ``-break-list'' will report a single list of watchpoints and breakpoints inserted.

GDB command
-----------

watch, awatch, rwatch

Example 1
---------

Watchpoint on a variable in main().

     (gdb)
     -break-watch x
     ^done,wpt={number="2",exp="x"}
     (gdb)
     -exec-continue
     ^running
     ^done,reason="watchpoint-trigger",wpt={number="2",exp="x"},
     value={old="-268439212",new="55"},
     frame={func="main",args={},file="recursive2.c",line="5"}
     (gdb)

Example 2
---------

Watchpoint on a variable local to a function. Gdb will stop the program execution twice: first for the variable changing value, then for the watchpoint going out of scope.

     (gdb)
     -break-watch C
     ^done,wpt={number="5",exp="C"}
     (gdb)
     -exec-continue
     ^running
     ^done,reason="watchpoint-trigger",
     wpt={number="5",exp="C"},value={old="-276895068",new="3"},
     frame={func="callee4",args={},file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
     line="13"}
     (gdb)
     -exec-continue
     ^running
     ^done,reason="watchpoint-scope",wpnum="5",
     frame={func="callee3",args={{name="strarg",value="0x11940 \"A string argument.\""}},
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
     (gdb)

Example 3
---------

Listing breakpoints and watchpoints, at different points in the program execution. Note that once the watchpoint goes out of scope, it is deleted.

     (gdb)
     -break-watch C
     ^done,wpt={number="2",exp="C"}
     (gdb)
     -break-list
     ^done,BreakpointTable={hdr={"Num","Type","Disp","Enb","Address","What"},
     bkpt={number="1",type="breakpoint",disp="keep",enabled="y",addr="0x00010734",
     func="callee4",
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
     bkpt={number="2",type="watchpoint",disp="keep",
     enabled="y",addr="",what="C",times="0"}}
     (gdb)
     -exec-continue
     ^running
     ^done,reason="watchpoint-trigger",wpt={number="2",exp="C"},
     value={old="-276895068",new="3"},
     frame={func="callee4",args={},
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
     (gdb)
     -break-list
     ^done,BreakpointTable={hdr={"Num","Type","Disp","Enb","Address","What"},
     bkpt={number="1",type="breakpoint",disp="keep",enabled="y",addr="0x00010734",
     func="callee4",
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
     bkpt={number="2",type="watchpoint",disp="keep",
     enabled="y",addr="",what="C",times="-5"}}
     (gdb)
     -exec-continue
     ^running
     ^done,reason="watchpoint-scope",wpnum="2",
     frame={func="callee3",args={{name="strarg",value="0x11940 \"A string argument.\""}},
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
     (gdb)
     -break-list
     ^done,BreakpointTable={hdr={"Num","Type","Disp","Enb","Address","What"},
     bkpt={number="1",type="breakpoint",disp="keep",enabled="y",addr="0x00010734",
     func="callee4",
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}}
     (gdb)

Data manipulation
*****************

-data-disassemble <begin> <end> <mode> <number-of-lines>
========================================================

Where

<begin>
     Is a function name or an address (or $pc)

<end>
     can be 0 (in which case the enclosing function will be disassembled), or an address.

<mode>
     can be 0 (only disassembly) or 1 (mixed source and disassembly).

<number-of-lines>
     specifies the number of disassembly lines to be produced. If it is -1 the whole function will be disassembled, in case no <end> address is specified.  If <end> is specified as a non-zero value, and <number-of-lines> is lower that the number of disassembly lines between <begin> and <end>, we'll display only <number-of-lines> lines, vice versa if <number-of-lines> is higher than the number of lines between <begin> and <end>, we'll display only the lines up to <end>.

The output for each instruction is composed of two fields:

  * Address

  * Instruction

Note that whatever included in those fields, is not manipulated directely by Flathead, i.e. it is not possible to adjust their format.

GDB command
-----------

N.A. No direct mapping.

Example 1
---------

     (gdb)
     -data-disassemble main 0 0 -1
     ^done,asm_insns={
     {address="0x100b8 <main>",inst=" stwu r1,-16(r1)"},
     {address="0x100bc <main+4>",inst="mflr r0"},
     {address="0x100c0 <main+8>",inst=" stw r31,12(r1)"},
     {address="0x100c4 <main+12>",inst=" stw r0,20(r1)"},
     {address="0x100c8 <main+16>",inst=" mr r31,r1"},
     {address="0x100cc <main+20>",inst=" bl0x1013c <__eabi>"},
     {address="0x100d0 <main+24>",inst=" lis r9,2"},
     {address="0x100d4 <main+28>",inst=" addi r3,r9,-25680"},
     {address="0x100d8 <main+32>",inst=" bl 0x10fc8 <printf>"},
     {address="0x100dc <main+36>",inst=" bl 0x10100 <foo>"},
     {address="0x100e0 <main+40>",inst=" li r3,0"},
     {address="0x100e4 <main+44>",inst=" b 0x100e8 <main+48>"},
     {address="0x100e8 <main+48>",inst=" lwz r11,0(r1)"},
     {address="0x100ec <main+52>",inst=" lwz r0,4(r11)"},
     {address="0x100f0 <main+56>",inst=" mtlr r0"},
     {address="0x100f4 <main+60>",inst=" lwz r31,-4(r11)"},
     {address="0x100f8 <main+64>",inst=" mr r1,r11"},
     {address="0x100fc <main+68>",inst=" blr"}
     (gdb)

Example 2
---------

     (gdb)
     -data-disassemble main 0 0 3
     ^done,asm_insns={
     {address=" 0x100b8 <main>",inst=" stwu r1,-16(r1)"},
     {address=" 0x100bc <main+4>",inst="mflr r0"},
     {address=" 0x100c0 <main+8>",inst=" stw r31,12(r1)"}
     (gdb)

Example 3
---------

     (gdb)
     -data-disassemble foo 0 1 -1
     ^done,asm_insns={src_and_asm_line={line="11",file="hello.c",
     line_asm_insn={
     {address="    0x10100 <foo>",inst="      stwu        r1,-16(r1)"},
     {address="    0x10104 <foo+4>",inst="           mflrr0"},
     {address="    0x10108 <foo+8>",inst="           stw r31,12(r1)"},
     {address="    0x1010c <foo+12>",inst="         stw  r0,20(r1)"},
     {address="    0x10110 <foo+16>",inst="           mr  r31,r1"}}},
     src_and_asm_line={line="12",file="hello.c",
     line_asm_insn={
     {address="    0x10114 <foo+20>",inst="          lisr9,2"},
     {address="    0x10118 <foo+24>",inst="         addi        r3,r9,-25664"},
     {address="    0x1011c <foo+28>",inst="        bl  0x10fc8 <printf>"}}},
     src_and_asm_line={line="14",file="hello.c",
     line_asm_insn={
     {address="    0x10120 <foo+32>",inst="        lwz r11,0(r1)"},
     {address="    0x10124 <foo+36>",inst="           lwz r0,4(r11)"},
     {address="    0x10128 <foo+40>",inst="           mtlr        r0"},
     {address="    0x1012c <foo+44>",inst="          lwz r31,-4(r11)"},
     {address="    0x10130 <foo+48>",inst="         mr r1,r11"},
     {address="    0x10134 <foo+52>",inst="       blr"}}}}
     (gdb)

-data-evaluate-expression
=========================

Evaluate 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
-----------

print, output, gdb_eval

Example
-------

     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)

-data-list-changed-registers
============================

Display a list of the registers that have changed.

GDB command
-----------

gdb_changed_register_list. This is in gdbtk only.

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)

-data-list-register-names
=========================

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 corresponding to the arguments.

GDB 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)

-data-list-register-values
==========================

Display the registers contents.  Arguments are the format according to which the registers contents are to be returned, and a list of numbers specifying the registers to display. A missing list of number indicates that the contents of all the registers must be returned. Allowed formats are:

  * 'x': Hexadecimal

  * 'o': Octal

  * 't': Binary

  * 'd': Decimal

  * 'r': Raw

  * 'N': Natural

GDB command
-----------

info reg, info all-reg  AND/OR 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)

-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.

<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 (<32 or >126).

<byte-offset>
     An offset to add to the <address> before fetching memory.

Display 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 then 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 by addr.

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

GDB command
-----------

x AND/OR gdb_get_mem AND/OR GDBtk's memory read.

Example 1
---------

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)

Example 2
---------

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)

Example 3
---------

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)

-display-delete <number>
========================

Delete the display <number>.

GDB command
-----------

delete display

Example
-------

N.A.

-display-disable <number>
=========================

Disable display <number>

GDB command
-----------

disable display

Example
-------

N.A.

-display-enable <number>
========================

Enable display <number>

GDB command
-----------

enable display

Example
-------

N.A.

-display-insert <expression>
============================

Display <expression> every time the program stops.

GDB command
-----------

display

Example
-------

N.A.

-display-list
=============

List the displays. Do not show the current values.

GDB command
-----------

info display

Example
-------

N.A.

-environment-cd <pathdir>
=========================

Set GDB's working directory.

GDB command
-----------

cd

Example
-------

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

-environment-directory <pathdir>
================================

Add directory <pathdir> to beginning of search path for source files.

GDB command
-----------

dir

Example
-------

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

-environment-path { <pathdir> }+
================================

Add directories to beginning of search path for object files.

GDB command
-----------

path

Example
-------

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

-environment-pwd
================

Show the current working directory

GDB command
-----------

pwd

Example
-------

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

Program control
***************

Program termination
===================

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

Example 1
---------

Program exited normally:

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

Example 2
---------

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 like SIGINT.

Example
-------

Program exited with signal (for a more complete example, see the exec-interrupt command).

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

-exec-abort
===========

Kill the inferior running program.

GDB command
-----------

kill

Example
-------

N.A.

-exec-arguments
===============

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

GDB command
-----------

set args

Example
-------

Don't have it around.

-exec-continue
==============

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

GDB command
-----------

continue

Example
-------

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

-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
-----------

finish

Example 1
---------

Function returning 'void'.

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

Example 2
---------

Function returning other than 'void'. The name of the internal gdb variable storing the result is printed, and 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)

-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
-----------

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)

-exec-next
==========

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

GDB command
-----------

next

Example
-------

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

-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
-----------

nexti

Example
-------

     (gdb)
     -exec-next-instruction
     ^running

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

-exec-return
============

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

GDB command
-----------

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)

-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
-----------

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)

-exec-show-arguments
====================

Print the arguments of the program.

GDB command
-----------

show args

Example
-------

N.A.

-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
-----------

step

Example 1
---------

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)

Example 2
---------

Regular stepping

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

-exec-step-instruction
======================

Asynchronous command. Resumes the inferior which executes one machine instruction. The output, once stop, will vary depend 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
-----------

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)

-exec-until
===========

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
-----------

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)

-file-clear
===========

Is this going away????

-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, it clears the executable and symbol information.  If breakpoints are set when using this command with no arguments, gdb will produce errors. No output is produced, except a completion notification.

GDB command
-----------

file <file>

Example
-------

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

-file-exec-file <file>
======================

Specify the executable file to be debugged. 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
-----------

exec-file <file>

Example
-------

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

-file-list-exec-sections
========================

List the sections of the current executable file.

GDB command
-----------

info file (only part of it), gdb_load_info

Example
-------

N.A.

-file-list-exec-source-files
============================

List the source files for the current executable.

GDB command
-----------

gdb_listfiles (gdbtk).

Example
-------

N.A.

-file-list-shared-libraries
===========================

List the shared libraries in the program.

GDB command
-----------

info shared

Example
-------

N.A.

-file-list-symbol-files
=======================

List symbol files.

GDB command
-----------

info file (part of it).

Example
-------

N.A.

-file-symbol-file <file>
========================

Read symbol table info from the file specified as argument.  Used without arguments clears gdb's symbol table info.  No output is produced, except a completion notification.

GDB command
-----------

symbol-file <file>

Example
-------

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

Misc GDB commands
*****************

-gdb-exit
=========

Exit GDB immediately.

GDB command
-----------

Approximately corresponds to 'quit'.

Example
-------

     (gdb)
     -gdb-exit

-gdb-set
========

Set an internal GDB variable. IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????

GDB command
-----------

set

Example
-------

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

-gdb-show
=========

Show the current value of a GDB variable.

GDB command
-----------

show

Example
-------

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

-gdb-version
============

Show version information for gdb. Used in testing mostly.

GDB command
-----------

No equivalent.

Example
-------

     (gdb)
     -gdb-version
     ~GNU gdb 4.18.1 HEADLESS
     ~Copyright 1998 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)

Kod Commands
************

The Kod commands are not implemented.

Memory Overlay Commands
***********************

the memory overlay commands not implemented.

Signal Handling Commands
************************

Signal handling commands are not implemented.

Stack manipulation commands
***************************

-stack-info-frame
=================

Get info on the current frame.

GDB command
-----------

info frame or frame (w/o args).

Example
-------

N.A.

-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
-----------

No equivalent.

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)

-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, it will list the arguments for the whole 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 argumetns are printed.

GDB command
-----------

gdb_get_args (partially).

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)

-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>
     Pc value for that frame.

<func>
     Function name

<file>
     File name of the source fle where the function lives.

<line>
     Line number corresponding to the pc.

If invoked without arguments, it 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
-----------

backtrace or where

Example 1
---------

Whole 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)

Example 2
---------

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)

Example 3
---------

Show one single frame.

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

-stack-list-locals <print-values>
=================================

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

GDB command
-----------

gdb_get_locals

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)

-stack-select-frame <framenum>
==============================

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

GDB command
-----------

frame (part), up, down AND/OR select-frame, up-silent, down-silent

Example
-------

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

Symbol query commands
*********************

-symbol-info-address <symbol>
=============================

Describe where <symbol> is stored.

GDB command
-----------

Info address

Example
-------

N.A.

-symbol-info-file
=================

Show the file for the symbol [NOT SURE]

GDB command
-----------

gdb_filnd_file (gdbtk).

Example
-------

N.A.

-symbol-info-function
=====================

Show which function the symbol lives in. [NOT SURE]

GDB command
-----------

gdb_get_function (gdbtk)

Example
-------

N.A.

-symbol-info-line
=================

Core addresses of the code for a source line.

GDB command
-----------

info line , gdb_get_line, gdb_get_file

Example
-------

N.A.

-symbol-info-symbol
===================

Describe what symbol is at location ADDR [NOT SURE]

GDB command
-----------

info symbol

Example
-------

N.A.

-symbol-list-functions
======================

List the functions in the executable.

GDB command
-----------

info functions, gdb_listfunc, gdb_search

Example
-------

N.A.

-symbol-list-types
==================

List all the type names.

GDB command
-----------

info types, gdb_search

Example
-------

N.A.

-symbol-list-variables
======================

List all global and static variable names.

GDB command
-----------

Info variables, gdb_search

Example
-------

N.A.

-symbol-locate
==============

GDB command
-----------

gdb_loc (gdbtk)

Example
-------

N.A.

-symbol-type
============

Show type of a variable.

GDB command
-----------

ptype, gdb_obj_variable

Example
-------

N.A.

Target manipulation commands
****************************

-target-attach
==============

Attach to a process or file outside of GDB.

GDB command
-----------

attach

Example
-------

N.A.

-target-compare-sections
========================

Compare section data on target to the exec file.

GDB command
-----------

compare-sections

Example
-------

N.A.

-target-detach
==============

Disconnect from the remote target. No output.

GDB command
-----------

detach

Example
-------

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

-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.

In addition it prints the name and size of the sections, as they are downloaded. These messages include the 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
-----------

load

Example
-------

Note: Each status message appears on a single line. Here the messages have been broken down, so they can fit into 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)

-target-exec-status
===================

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

GDB command
-----------

No equivalent

Example
-------

N.A.

-target-list-available-targets
==============================

List the possible targets to connect to.

GDB command
-----------

help target

Example
-------

N.A.

-target-list-current-targets
============================

What the current target is.

GDB command
-----------

info file (part of it).

Example
-------

N.A.

-target-list-parameters
=======================

????

GDB command
-----------

No equivalent

Example
-------

N.A.

-target-select
==============

Connect GDB to the remote target. It takes two args:

-target-select <type> <parameters>.

Where:

<type>
     The type of target, for instance async, remote, etc.

<parameters>
     Device names, host names and the like.

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
-----------

target

Example
-------

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

Thread commands
***************

-thread-info
============

GDB command
-----------

Example
-------

-thread-list-all-threads
========================

GDB command
-----------

Example
-------

-thread-list-ids
================

Produces a list of the currently known gdb thread ids. At the end of the list it also prints the toal number of such threads.

GDB command
-----------

None equivalent. (Maybe part of info threads).

Example 1
---------

No threads present, besides the main process.

     (gdb)
     -thread-list-ids
     ^done,thread-ids={},number-of-threads="0"
     (gdb)

Example 2
---------

Several threads.

     (gdb)
     -thread-list-ids
     ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},
     number-of-threads="3"
     (gdb)

-thread-select <threadnum>
==========================

Make <threadnum> the current thread. It prints the number of the new current thread, and the topmost frame for that thread.

GDB command
-----------

thread

Example
-------

     (gdb)
     -exec-next
     ^running
     (gdb)
     *stopped,reason="end-stepping-range",thread-id="2",line="187",
     file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
     (gdb)
     -thread-list-ids
     ^done,
     thread-ids={thread-id="3",thread-id="2",thread-id="1"},
     number-of-threads="3"
     (gdb)
     -thread-select 3
     ^done,new-thread-id="3",
     frame={level="0 ",func="vprintf",
     args={{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},
     {name="arg",value="0x2"}},file="vprintf.c",line="31"}
     (gdb)

Tracepoint Commands
*******************

The tracepoint commands are not implemented.

Variable Objects
****************

Motivation
==========

For the implementation of a variable debugger window (locals, watched expressions, etc.), we are proposing the adaptation of the existent code used by Insight.

The two main reason for that are:

 1. It has been proven in practice (it is already on it's second generation)

 2. It will shorten development time (needless to say how important it is now)

The original interface was designed to be used by Tcl code, so it was slightly changed so it can be used through flathead.  This document describes the flathead operations that will be available and gives some hints about its use.

Note: In addition to the set of operations described here, we expect the GUI implementation of a variable window to require, at least, the following operations:

  bullet -gdb-show output-radix

  bullet -stack-list-arguments

  bullet -stack-list-locals

  bullet -stack-select-frame

Introduction
============

The basic idea behind variable objects is the creation of a named object to represent a variable, an expression, a memory location or even a CPU register.  For each object created, a set of operations is available for examining or changing its properties.

Furthermore, complex data types, such as C structures, are represented in a tree format.  For instance, the struct type variable is the root and the children will represent the struct members.  If a children is itself of a complex type, it will also have children of its own. Appropriate language differences are handled for C, C++ and Java.

When returning the actual values of the objects, this facility allows for the individual selection of the display format used in the result creation.  It can be chosen among: binary, decimal, hexadecimal, octal and natural. Natural refers to the a default format automatically chosen based on the variable type (like decimal for int, hex for pointers, etc.).

The following is the complete set of flathead operations defined to access this functionality:

Operation
Description

-var-create
create a variable object
-var-delete
delete the variable object and its children
-var-set-format
set the display format of this variable
-var-show-format
show the display format of this variable
-var-info-num-children
tells how many children this object has
-var-list-children
return a list of the object's children
-var-info-type
show the type of this variable object
-var-info-expression
print what this variable object represents
-var-show-attributes
is this variable editable? does it exist here?
-var-evaluate-expression
get the value of this variable
-var-assign
set the value of this variable
-var-update
update the variable and its children

In the next section we describe each operation in detail and suggest how it can be used.

Operations Description And Use
==============================

-var-create {<name> | '-'} {<frame-addr> | '*'} <expression>
------------------------------------------------------------

This operation creates a variable object, which allows the monitoring of a variable, the result of an expression, a memory cell or a CPU register.

The <name> parameter is the string by which the object can be referenced.  It must be unique.  If '-' is specified, the varobj system will generate a string "varNNNNNN" automatically.  It will be unique provided that one does not specify <name> on that format.  The command fails if a duplicate name is found.

The frame under which the expression should be evaluated can be specified.  A '*' indicates that the current frame should be used.

Expression is any expression valid on the current language set (must not begin with '*') or: *<addr> - The address of a memory cell *<addr>-<addr> - An memory address range (TBD) $<regname> - A CPU register

This operation returns the name, number of children and the type of the object created.  Type is returned as a string as the ones generated by gdb CLI.

name="<name>",numchild="N",type="<type>"

-var-delete <name>
------------------

Deletes a previously created variable object and all of it's children.

Returns an error if the object <name> is not found.

-var-set-format <name> <format-spec>
------------------------------------

Sets the output format for the value of the object.

<format-spec> = {binary | decimal | hexadecimal | octal | natural}

-var-show-format <name>
-----------------------

Returns the format used to display the value of the object.

format="<format-spec>"

-var-info-num-children <name>
-----------------------------

Returns the number of children of a variable object.

numchild="N"

-var-list-children <name>
-------------------------

Returns a list of the children of the specified variable object.

numchild="N",children={{name="<name>",numchild="N",type="<type>"},(repeats N times)}

-var-info-type <name>
---------------------

Returns the type of the specified variable.  The type is returned as a string in the same format as it is output by gdb's CLI.

type="<type>"

-var-info-expression <name>
---------------------------

Returns what is represented by the specified variable object.

lang="<lang-spec>",exp="<expression>"

where <lang-spec> = {"C" | "C++" | "Java"}

-var-show-attributes <name>
---------------------------

List attributes of the specified variable object.

status="<attr>[,<attr>]*"

where <attr> = { { editable | noneditable } | TBD }

-var-evaluate-expression <name>
-------------------------------

Evaluates the expression that is represented by the specified variable object and returns its value as a string in the current format specified for the object.

value="<value>"

-var-assign <name> <expression>
-------------------------------

Assigns a new value for the variable object specified.  The object must be "editable".

-var-update {<name> | '*'}
--------------------------

Update the value of the variable object by evaluating its expression after fetching all the new values from memory or registers.  A '*' causes all existing variable objects to be updated.

%%%%%%%%%%%%%%%%%%%%%%%%%%%% APPENDIX %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Proposed v2.0 Output Syntax
***************************

This appendix is not part of the MI specification.  It is provided as a discussion point.

The output from GDB/MI consists of zero or more out-of-band records optionally followed by a single result record.  The result record being for the most recent command input.  The sequence being terminated by ``(gdb)''.

Asynchronous GDB/MI output is similar.

Each output record directly associated with an input command is prefixed by the input commands <token>.

<output> ==>
     { <out-of-band-record> } [ <result-record> ] ``(gdb)'' <nl>

<result-record> ==>
     [ <token> ] ``^'' <result-class> { ``,'' <result> } <nl>

<out-of-band-record> ==>
     <async-record> | <stream-record>

<async-record> ==>
     <exec-async-output> | <status-async-output> | <notify-async-output>

<exec-async-output> ==>
     [ <token> ] ``*'' <async-output>

<status-async-output> ==>
     [ <token> ] ``+'' <async-output>

<notify-async-output> ==>
     [ <token> ] ``='' <async-output>

<async-output> ==>
     <async-class> { ``,'' <result> } <nl>

<result-class> ==>
     ``done'' | ``running'' | ``connected'' | ``error'' | ``exit''

<async-class> ==>
     ``stopped'' | others depending on need as still in development

<result> ==>
     <string> ``='' <value>

<value> ==>
     <c-string> | <tupple> | <list>

<tupple> ==>
     ``{}'' | ``{'' <result> { ``,'' <result> } ``}''

<list> ==>
     ``[]'' | ``['' <value> { ``,'' <value> } ``]''

<string> ==>
     [-A-Za-z\.0-9_]*

<c-string> ==>
     See the input specification

<stream-record> ==>
     <console-stream-output> | <target-stream-output> | <log-stream-output>

<console-stream-output> ==>
     ``~'' <c-string>

<target-stream-output> ==>
     ``@'' <c-string>

<log-stream-output> ==>
     ``&'' <c-string>

<nl> ==>
     CR | CR-LF

<token> ==>
     ``any sequence of digits''

In addition, the following are still being developed.

<query>
     This action is currently undefined.

Notes:

  * All output sequences end in a single line containing a period.

  * The <token> is from the corresponding request.  If an execution command is interrupted by the -exec-interrupt command, the token associated with the `*stopped' message is the one of the original execution command, not the one of the interrupt-command.

  * <status-async-output> contains on-going status information about the progress of a slow operation.  It can be discarded. All status output is prefixed by the prefix `+'.

  * <exec-async-output> contains asynchronous state change on the target (stopped, started, disappeared). All async output is prefixed by the prefix `*'.

  * <notify-async-output> contains supplementary information that the client should handle (new breakpoint information). All notify output is prefixed by the prefix `='.

  * <console-stream-output> is output that should be displayed as is in the console.  It is the textual response to a CLI command. All the console output is prefixed by the prefix ``~''.

  * <target-stream-output> is the output produced by the target program. All the target output is prefixed by the prefix ``@''.

  * <log-stream-output> is output text coming from GDB's internals, for instance messages that should be displayed as part of an error log.  All the log output is prefixed by the prefix ``&''.