26.9. gdb/mi Data Manipulation

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

26.9.1. The -data-disassembleCommand

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

26.9.1.2. 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, that is, it is not possible to adjust its format.

26.9.1.3. gdb Command

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

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

26.9.2. The -data-evaluate-expressionCommand

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

26.9.2.2. gdb Command

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

26.9.2.3. Example

In the following example, the numbers that precede the commands are the tokens described in (refer to Section 26.4 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)

26.9.3. The -data-list-changed-registersCommand

26.9.3.1. Synopsis

 -data-list-changed-registers

Display a list of the registers that have changed.

26.9.3.2. gdb Command

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

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

26.9.4. The -data-list-register-namesCommand

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

26.9.4.2. gdb Command

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

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

26.9.5. The -data-list-register-valuesCommand

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

26.9.5.2. gdb Command

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

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

26.9.6. The -data-read-memoryCommand

26.9.6.1. 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 (refer to Section 10.4 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.

26.9.6.2. gdb Command

The corresponding gdb command is x. gdbtk has gdb_get_mem memory read command.

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

26.9.7. The -display-deleteCommand

26.9.7.1. Synopsis

 -display-delete number

Delete the display number.

26.9.7.2. gdb Command

The corresponding gdb command is delete display.

26.9.7.3. Example

N.A.

26.9.8. The -display-disableCommand

26.9.8.1. Synopsis

 -display-disable number

Disable display number.

26.9.8.2. gdb Command

The corresponding gdb command is disable display.

26.9.8.3. Example

N.A.

26.9.9. The -display-enableCommand

26.9.9.1. Synopsis

 -display-enable number

Enable display number.

26.9.9.2. gdb Command

The corresponding gdb command is enable display.

26.9.9.3. Example

N.A.

26.9.10. The -display-insertCommand

26.9.10.1. Synopsis

 -display-insert expression

Display expression every time the program stops.

26.9.10.2. gdb Command

The corresponding gdb command is display.

26.9.10.3. Example

N.A.

26.9.11. The -display-listCommand

26.9.11.1. Synopsis

 -display-list

List the displays. Do not show the current values.

26.9.11.2. gdb Command

The corresponding gdb command is info display.

26.9.11.3. Example

N.A.

26.9.12. The -environment-cdCommand

26.9.12.1. Synopsis

 -environment-cd pathdir

Set gdb's working directory.

26.9.12.2. gdb Command

The corresponding gdb command is cd.

26.9.12.3. Example

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

26.9.13. The -environment-directoryCommand

26.9.13.1. Synopsis

 -environment-directory [ -r ] [ pathdir ]+

Add directories pathdir to beginning of search path for source files. If the -r option is used, the search path is reset to the default search path. If directories pathdir are supplied in addition to the -r option, the search path is first reset and then addition occurs as normal. Multiple directories may be specified, separated by blanks. Specifying multiple directories in a single command results in the directories added to the beginning of the search path in the same order they were presented in the command. If blanks are needed as part of a directory name, double-quotes should be used around the name. In the command output, the path will show up separated by the system directory-separator character. The directory-seperator character must not be used in any directory name. If no directories are specified, the current search path is displayed.

26.9.13.2. gdb Command

The corresponding gdb command is dir.

26.9.13.3. Example

(gdb)
-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
(gdb)
-environment-directory ""
^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
(gdb)
-environment-directory -r /home/jjohnstn/src/gdb /usr/src
^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
(gdb)
-environment-directory -r
^done,source-path="$cdir:$cwd"
(gdb)

26.9.14. The -environment-pathCommand

26.9.14.1. Synopsis

 -environment-path [ -r ] [ pathdir ]+

Add directories pathdir to beginning of search path for object files. If the -r option is used, the search path is reset to the original search path that existed at gdb start-up. If directories pathdir are supplied in addition to the -r option, the search path is first reset and then addition occurs as normal. Multiple directories may be specified, separated by blanks. Specifying multiple directories in a single command results in the directories added to the beginning of the search path in the same order they were presented in the command. If blanks are needed as part of a directory name, double-quotes should be used around the name. In the command output, the path will show up separated by the system directory-separator character. The directory-seperator character must not be used in any directory name. If no directories are specified, the current path is displayed.

26.9.14.2. gdb Command

The corresponding gdb command is path.

26.9.14.3. Example

(gdb)
-environment-path
^done,path="/usr/bin"
(gdb)
-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
(gdb)
-environment-path -r /usr/local/bin
^done,path="/usr/local/bin:/usr/bin"
(gdb)

26.9.15. The -environment-pwdCommand

26.9.15.1. Synopsis

 -environment-pwd

Show the current working directory.

26.9.15.2. gdb command

The corresponding gdb command is pwd.

26.9.15.3. Example

(gdb)
-environment-pwd
^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
(gdb)