This is gdb.info, produced by makeinfo version 4.8 from
|
This is gdb.info, produced by makeinfo version 4.8 from
|
../.././gdb/doc/gdb.texinfo.
|
../.././gdb/doc/gdb.texinfo.
|
|
|
INFO-DIR-SECTION Software development
|
INFO-DIR-SECTION Software development
|
START-INFO-DIR-ENTRY
|
START-INFO-DIR-ENTRY
|
* Gdb: (gdb). The GNU debugger.
|
* Gdb: (gdb). The GNU debugger.
|
END-INFO-DIR-ENTRY
|
END-INFO-DIR-ENTRY
|
|
|
This file documents the GNU debugger GDB.
|
This file documents the GNU debugger GDB.
|
|
|
This is the Ninth Edition, of `Debugging with GDB: the GNU
|
This is the Ninth Edition, of `Debugging with GDB: the GNU
|
Source-Level Debugger' for GDB Version 6.8.
|
Source-Level Debugger' for GDB Version 6.8.
|
|
|
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
1998,
|
1998,
|
1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
|
1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
|
Free Software Foundation, Inc.
|
Free Software Foundation, Inc.
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.1 or
|
under the terms of the GNU Free Documentation License, Version 1.1 or
|
any later version published by the Free Software Foundation; with the
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being "Free Software" and "Free Software Needs Free
|
Invariant Sections being "Free Software" and "Free Software Needs Free
|
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
with the Back-Cover Texts as in (a) below.
|
with the Back-Cover Texts as in (a) below.
|
|
|
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
|
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
|
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
developing GNU and promoting software freedom."
|
developing GNU and promoting software freedom."
|
|
|
|
|
File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI
|
|
|
24.6 GDB/MI Command Description Format
|
24.6 GDB/MI Command Description Format
|
======================================
|
======================================
|
|
|
The remaining sections describe blocks of commands. Each block of
|
The remaining sections describe blocks of commands. Each block of
|
commands is laid out in a fashion similar to this section.
|
commands is laid out in a fashion similar to this section.
|
|
|
Motivation
|
Motivation
|
----------
|
----------
|
|
|
The motivation for this collection of commands.
|
The motivation for this collection of commands.
|
|
|
Introduction
|
Introduction
|
------------
|
------------
|
|
|
A brief introduction to this collection of commands as a whole.
|
A brief introduction to this collection of commands as a whole.
|
|
|
Commands
|
Commands
|
--------
|
--------
|
|
|
For each command in the block, the following is described:
|
For each command in the block, the following is described:
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-command ARGS...
|
-command ARGS...
|
|
|
Result
|
Result
|
......
|
......
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB CLI command(s), if any.
|
The corresponding GDB CLI command(s), if any.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
Example(s) formatted for readability. Some of the described commands
|
Example(s) formatted for readability. Some of the described commands
|
have not been implemented yet and these are labeled N.A. (not
|
have not been implemented yet and these are labeled N.A. (not
|
available).
|
available).
|
|
|
|
|
File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Command Description Format, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Command Description Format, Up: GDB/MI
|
|
|
24.7 GDB/MI Breakpoint Commands
|
24.7 GDB/MI Breakpoint Commands
|
===============================
|
===============================
|
|
|
This section documents GDB/MI commands for manipulating breakpoints.
|
This section documents GDB/MI commands for manipulating breakpoints.
|
|
|
The `-break-after' Command
|
The `-break-after' Command
|
--------------------------
|
--------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-break-after NUMBER COUNT
|
-break-after NUMBER COUNT
|
|
|
The breakpoint number NUMBER is not in effect until it has been hit
|
The breakpoint number NUMBER is not in effect until it has been hit
|
COUNT times. To see how this is reflected in the output of the
|
COUNT times. To see how this is reflected in the output of the
|
`-break-list' command, see the description of the `-break-list' command
|
`-break-list' command, see the description of the `-break-list' command
|
below.
|
below.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `ignore'.
|
The corresponding GDB command is `ignore'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-break-insert main
|
-break-insert main
|
^done,bkpt={number="1",addr="0x000100d0",file="hello.c",
|
^done,bkpt={number="1",addr="0x000100d0",file="hello.c",
|
fullname="/home/foo/hello.c",line="5",times="0"}
|
fullname="/home/foo/hello.c",line="5",times="0"}
|
(gdb)
|
(gdb)
|
-break-after 1 3
|
-break-after 1 3
|
~
|
~
|
^done
|
^done
|
(gdb)
|
(gdb)
|
-break-list
|
-break-list
|
^done,BreakpointTable={nr_rows="1",nr_cols="6",
|
^done,BreakpointTable={nr_rows="1",nr_cols="6",
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
line="5",times="0",ignore="3"}]}
|
line="5",times="0",ignore="3"}]}
|
(gdb)
|
(gdb)
|
|
|
The `-break-condition' Command
|
The `-break-condition' Command
|
------------------------------
|
------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-break-condition NUMBER EXPR
|
-break-condition NUMBER EXPR
|
|
|
Breakpoint NUMBER will stop the program only if the condition in
|
Breakpoint NUMBER will stop the program only if the condition in
|
EXPR is true. The condition becomes part of the `-break-list' output
|
EXPR is true. The condition becomes part of the `-break-list' output
|
(see the description of the `-break-list' command below).
|
(see the description of the `-break-list' command below).
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `condition'.
|
The corresponding GDB command is `condition'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-break-condition 1 1
|
-break-condition 1 1
|
^done
|
^done
|
(gdb)
|
(gdb)
|
-break-list
|
-break-list
|
^done,BreakpointTable={nr_rows="1",nr_cols="6",
|
^done,BreakpointTable={nr_rows="1",nr_cols="6",
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
line="5",cond="1",times="0",ignore="3"}]}
|
line="5",cond="1",times="0",ignore="3"}]}
|
(gdb)
|
(gdb)
|
|
|
The `-break-delete' Command
|
The `-break-delete' Command
|
---------------------------
|
---------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-break-delete ( BREAKPOINT )+
|
-break-delete ( BREAKPOINT )+
|
|
|
Delete the breakpoint(s) whose number(s) are specified in the
|
Delete the breakpoint(s) whose number(s) are specified in the
|
argument list. This is obviously reflected in the breakpoint list.
|
argument list. This is obviously reflected in the breakpoint list.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `delete'.
|
The corresponding GDB command is `delete'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-break-delete 1
|
-break-delete 1
|
^done
|
^done
|
(gdb)
|
(gdb)
|
-break-list
|
-break-list
|
^done,BreakpointTable={nr_rows="0",nr_cols="6",
|
^done,BreakpointTable={nr_rows="0",nr_cols="6",
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
body=[]}
|
body=[]}
|
(gdb)
|
(gdb)
|
|
|
The `-break-disable' Command
|
The `-break-disable' Command
|
----------------------------
|
----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-break-disable ( BREAKPOINT )+
|
-break-disable ( BREAKPOINT )+
|
|
|
Disable the named BREAKPOINT(s). The field `enabled' in the break
|
Disable the named BREAKPOINT(s). The field `enabled' in the break
|
list is now set to `n' for the named BREAKPOINT(s).
|
list is now set to `n' for the named BREAKPOINT(s).
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `disable'.
|
The corresponding GDB command is `disable'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-break-disable 2
|
-break-disable 2
|
^done
|
^done
|
(gdb)
|
(gdb)
|
-break-list
|
-break-list
|
^done,BreakpointTable={nr_rows="1",nr_cols="6",
|
^done,BreakpointTable={nr_rows="1",nr_cols="6",
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
|
body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
|
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
line="5",times="0"}]}
|
line="5",times="0"}]}
|
(gdb)
|
(gdb)
|
|
|
The `-break-enable' Command
|
The `-break-enable' Command
|
---------------------------
|
---------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-break-enable ( BREAKPOINT )+
|
-break-enable ( BREAKPOINT )+
|
|
|
Enable (previously disabled) BREAKPOINT(s).
|
Enable (previously disabled) BREAKPOINT(s).
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `enable'.
|
The corresponding GDB command is `enable'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-break-enable 2
|
-break-enable 2
|
^done
|
^done
|
(gdb)
|
(gdb)
|
-break-list
|
-break-list
|
^done,BreakpointTable={nr_rows="1",nr_cols="6",
|
^done,BreakpointTable={nr_rows="1",nr_cols="6",
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
|
body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
|
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
line="5",times="0"}]}
|
line="5",times="0"}]}
|
(gdb)
|
(gdb)
|
|
|
The `-break-info' Command
|
The `-break-info' Command
|
-------------------------
|
-------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-break-info BREAKPOINT
|
-break-info BREAKPOINT
|
|
|
Get information about a single breakpoint.
|
Get information about a single breakpoint.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `info break BREAKPOINT'.
|
The corresponding GDB command is `info break BREAKPOINT'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-break-insert' Command
|
The `-break-insert' Command
|
---------------------------
|
---------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-break-insert [ -t ] [ -h ] [ -f ]
|
-break-insert [ -t ] [ -h ] [ -f ]
|
[ -c CONDITION ] [ -i IGNORE-COUNT ]
|
[ -c CONDITION ] [ -i IGNORE-COUNT ]
|
[ -p THREAD ] [ LOCATION ]
|
[ -p THREAD ] [ LOCATION ]
|
|
|
If specified, LOCATION, can be one of:
|
If specified, LOCATION, can be one of:
|
|
|
* function
|
* function
|
|
|
* filename:linenum
|
* filename:linenum
|
|
|
* filename:function
|
* filename:function
|
|
|
* *address
|
* *address
|
|
|
The possible optional parameters of this command are:
|
The possible optional parameters of this command are:
|
|
|
`-t'
|
`-t'
|
Insert a temporary breakpoint.
|
Insert a temporary breakpoint.
|
|
|
`-h'
|
`-h'
|
Insert a hardware breakpoint.
|
Insert a hardware breakpoint.
|
|
|
`-c CONDITION'
|
`-c CONDITION'
|
Make the breakpoint conditional on CONDITION.
|
Make the breakpoint conditional on CONDITION.
|
|
|
`-i IGNORE-COUNT'
|
`-i IGNORE-COUNT'
|
Initialize the IGNORE-COUNT.
|
Initialize the IGNORE-COUNT.
|
|
|
`-f'
|
`-f'
|
If LOCATION cannot be parsed (for example if it refers to unknown
|
If LOCATION cannot be parsed (for example if it refers to unknown
|
files or functions), create a pending breakpoint. Without this
|
files or functions), create a pending breakpoint. Without this
|
flag, GDB will report an error, and won't create a breakpoint, if
|
flag, GDB will report an error, and won't create a breakpoint, if
|
LOCATION cannot be parsed.
|
LOCATION cannot be parsed.
|
|
|
Result
|
Result
|
......
|
......
|
|
|
The result is in the form:
|
The result is in the form:
|
|
|
^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep",
|
^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep",
|
enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME",
|
enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME",
|
fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,]
|
fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,]
|
times="TIMES"}
|
times="TIMES"}
|
|
|
where NUMBER is the GDB number for this breakpoint, FUNCNAME is the
|
where NUMBER is the GDB number for this breakpoint, FUNCNAME is the
|
name of the function where the breakpoint was inserted, FILENAME is the
|
name of the function where the breakpoint was inserted, FILENAME is the
|
name of the source file which contains this function, LINENO is the
|
name of the source file which contains this function, LINENO is the
|
source line number within that file and TIMES the number of times that
|
source line number within that file and TIMES the number of times that
|
the breakpoint has been hit (always 0 for -break-insert but may be
|
the breakpoint has been hit (always 0 for -break-insert but may be
|
greater for -break-info or -break-list which use the same output).
|
greater for -break-info or -break-list which use the same output).
|
|
|
Note: this format is open to change.
|
Note: this format is open to change.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB commands are `break', `tbreak', `hbreak',
|
The corresponding GDB commands are `break', `tbreak', `hbreak',
|
`thbreak', and `rbreak'.
|
`thbreak', and `rbreak'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-break-insert main
|
-break-insert main
|
^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",
|
^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",
|
fullname="/home/foo/recursive2.c,line="4",times="0"}
|
fullname="/home/foo/recursive2.c,line="4",times="0"}
|
(gdb)
|
(gdb)
|
-break-insert -t foo
|
-break-insert -t foo
|
^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",
|
^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",
|
fullname="/home/foo/recursive2.c,line="11",times="0"}
|
fullname="/home/foo/recursive2.c,line="11",times="0"}
|
(gdb)
|
(gdb)
|
-break-list
|
-break-list
|
^done,BreakpointTable={nr_rows="2",nr_cols="6",
|
^done,BreakpointTable={nr_rows="2",nr_cols="6",
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
addr="0x0001072c", func="main",file="recursive2.c",
|
addr="0x0001072c", func="main",file="recursive2.c",
|
fullname="/home/foo/recursive2.c,"line="4",times="0"},
|
fullname="/home/foo/recursive2.c,"line="4",times="0"},
|
bkpt={number="2",type="breakpoint",disp="del",enabled="y",
|
bkpt={number="2",type="breakpoint",disp="del",enabled="y",
|
addr="0x00010774",func="foo",file="recursive2.c",
|
addr="0x00010774",func="foo",file="recursive2.c",
|
fullname="/home/foo/recursive2.c",line="11",times="0"}]}
|
fullname="/home/foo/recursive2.c",line="11",times="0"}]}
|
(gdb)
|
(gdb)
|
-break-insert -r foo.*
|
-break-insert -r foo.*
|
~int foo(int, int);
|
~int foo(int, int);
|
^done,bkpt={number="3",addr="0x00010774",file="recursive2.c,
|
^done,bkpt={number="3",addr="0x00010774",file="recursive2.c,
|
"fullname="/home/foo/recursive2.c",line="11",times="0"}
|
"fullname="/home/foo/recursive2.c",line="11",times="0"}
|
(gdb)
|
(gdb)
|
|
|
The `-break-list' Command
|
The `-break-list' Command
|
-------------------------
|
-------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-break-list
|
-break-list
|
|
|
Displays the list of inserted breakpoints, showing the following
|
Displays the list of inserted breakpoints, showing the following
|
fields:
|
fields:
|
|
|
`Number'
|
`Number'
|
number of the breakpoint
|
number of the breakpoint
|
|
|
`Type'
|
`Type'
|
type of the breakpoint: `breakpoint' or `watchpoint'
|
type of the breakpoint: `breakpoint' or `watchpoint'
|
|
|
`Disposition'
|
`Disposition'
|
should the breakpoint be deleted or disabled when it is hit: `keep'
|
should the breakpoint be deleted or disabled when it is hit: `keep'
|
or `nokeep'
|
or `nokeep'
|
|
|
`Enabled'
|
`Enabled'
|
is the breakpoint enabled or no: `y' or `n'
|
is the breakpoint enabled or no: `y' or `n'
|
|
|
`Address'
|
`Address'
|
memory location at which the breakpoint is set
|
memory location at which the breakpoint is set
|
|
|
`What'
|
`What'
|
logical location of the breakpoint, expressed by function name,
|
logical location of the breakpoint, expressed by function name,
|
file name, line number
|
file name, line number
|
|
|
`Times'
|
`Times'
|
number of times the breakpoint has been hit
|
number of times the breakpoint has been hit
|
|
|
If there are no breakpoints or watchpoints, the `BreakpointTable'
|
If there are no breakpoints or watchpoints, the `BreakpointTable'
|
`body' field is an empty list.
|
`body' field is an empty list.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `info break'.
|
The corresponding GDB command is `info break'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-break-list
|
-break-list
|
^done,BreakpointTable={nr_rows="2",nr_cols="6",
|
^done,BreakpointTable={nr_rows="2",nr_cols="6",
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
addr="0x000100d0",func="main",file="hello.c",line="5",times="0"},
|
addr="0x000100d0",func="main",file="hello.c",line="5",times="0"},
|
bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
|
bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
|
addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
|
addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
|
line="13",times="0"}]}
|
line="13",times="0"}]}
|
(gdb)
|
(gdb)
|
|
|
Here's an example of the result when there are no breakpoints:
|
Here's an example of the result when there are no breakpoints:
|
|
|
(gdb)
|
(gdb)
|
-break-list
|
-break-list
|
^done,BreakpointTable={nr_rows="0",nr_cols="6",
|
^done,BreakpointTable={nr_rows="0",nr_cols="6",
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
body=[]}
|
body=[]}
|
(gdb)
|
(gdb)
|
|
|
The `-break-watch' Command
|
The `-break-watch' Command
|
--------------------------
|
--------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-break-watch [ -a | -r ]
|
-break-watch [ -a | -r ]
|
|
|
Create a watchpoint. With the `-a' option it will create an
|
Create a watchpoint. With the `-a' option it will create an
|
"access" watchpoint, i.e., a watchpoint that triggers either on a read
|
"access" watchpoint, i.e., a watchpoint that triggers either on a read
|
from or on a write to the memory location. With the `-r' option, the
|
from or on a write to the memory location. With the `-r' option, the
|
watchpoint created is a "read" watchpoint, i.e., it will trigger only
|
watchpoint created is a "read" watchpoint, i.e., it will trigger only
|
when the memory location is accessed for reading. Without either of
|
when the memory location is accessed for reading. Without either of
|
the options, the watchpoint created is a regular watchpoint, i.e., it
|
the options, the watchpoint created is a regular watchpoint, i.e., it
|
will trigger when the memory location is accessed for writing. *Note
|
will trigger when the memory location is accessed for writing. *Note
|
Setting Watchpoints: Set Watchpoints.
|
Setting Watchpoints: Set Watchpoints.
|
|
|
Note that `-break-list' will report a single list of watchpoints and
|
Note that `-break-list' will report a single list of watchpoints and
|
breakpoints inserted.
|
breakpoints inserted.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB commands are `watch', `awatch', and `rwatch'.
|
The corresponding GDB commands are `watch', `awatch', and `rwatch'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
Setting a watchpoint on a variable in the `main' function:
|
Setting a watchpoint on a variable in the `main' function:
|
|
|
(gdb)
|
(gdb)
|
-break-watch x
|
-break-watch x
|
^done,wpt={number="2",exp="x"}
|
^done,wpt={number="2",exp="x"}
|
(gdb)
|
(gdb)
|
-exec-continue
|
-exec-continue
|
^running
|
^running
|
(gdb)
|
(gdb)
|
*stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"},
|
*stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"},
|
value={old="-268439212",new="55"},
|
value={old="-268439212",new="55"},
|
frame={func="main",args=[],file="recursive2.c",
|
frame={func="main",args=[],file="recursive2.c",
|
fullname="/home/foo/bar/recursive2.c",line="5"}
|
fullname="/home/foo/bar/recursive2.c",line="5"}
|
(gdb)
|
(gdb)
|
|
|
Setting a watchpoint on a variable local to a function. GDB will
|
Setting a watchpoint on a variable local to a function. GDB will
|
stop the program execution twice: first for the variable changing
|
stop the program execution twice: first for the variable changing
|
value, then for the watchpoint going out of scope.
|
value, then for the watchpoint going out of scope.
|
|
|
(gdb)
|
(gdb)
|
-break-watch C
|
-break-watch C
|
^done,wpt={number="5",exp="C"}
|
^done,wpt={number="5",exp="C"}
|
(gdb)
|
(gdb)
|
-exec-continue
|
-exec-continue
|
^running
|
^running
|
(gdb)
|
(gdb)
|
*stopped,reason="watchpoint-trigger",
|
*stopped,reason="watchpoint-trigger",
|
wpt={number="5",exp="C"},value={old="-276895068",new="3"},
|
wpt={number="5",exp="C"},value={old="-276895068",new="3"},
|
frame={func="callee4",args=[],
|
frame={func="callee4",args=[],
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
|
(gdb)
|
(gdb)
|
-exec-continue
|
-exec-continue
|
^running
|
^running
|
(gdb)
|
(gdb)
|
*stopped,reason="watchpoint-scope",wpnum="5",
|
*stopped,reason="watchpoint-scope",wpnum="5",
|
frame={func="callee3",args=[{name="strarg",
|
frame={func="callee3",args=[{name="strarg",
|
value="0x11940 \"A string argument.\""}],
|
value="0x11940 \"A string argument.\""}],
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
|
(gdb)
|
(gdb)
|
|
|
Listing breakpoints and watchpoints, at different points in the
|
Listing breakpoints and watchpoints, at different points in the
|
program execution. Note that once the watchpoint goes out of scope, it
|
program execution. Note that once the watchpoint goes out of scope, it
|
is deleted.
|
is deleted.
|
|
|
(gdb)
|
(gdb)
|
-break-watch C
|
-break-watch C
|
^done,wpt={number="2",exp="C"}
|
^done,wpt={number="2",exp="C"}
|
(gdb)
|
(gdb)
|
-break-list
|
-break-list
|
^done,BreakpointTable={nr_rows="2",nr_cols="6",
|
^done,BreakpointTable={nr_rows="2",nr_cols="6",
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
addr="0x00010734",func="callee4",
|
addr="0x00010734",func="callee4",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"},
|
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"},
|
bkpt={number="2",type="watchpoint",disp="keep",
|
bkpt={number="2",type="watchpoint",disp="keep",
|
enabled="y",addr="",what="C",times="0"}]}
|
enabled="y",addr="",what="C",times="0"}]}
|
(gdb)
|
(gdb)
|
-exec-continue
|
-exec-continue
|
^running
|
^running
|
(gdb)
|
(gdb)
|
*stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"},
|
*stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"},
|
value={old="-276895068",new="3"},
|
value={old="-276895068",new="3"},
|
frame={func="callee4",args=[],
|
frame={func="callee4",args=[],
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
|
(gdb)
|
(gdb)
|
-break-list
|
-break-list
|
^done,BreakpointTable={nr_rows="2",nr_cols="6",
|
^done,BreakpointTable={nr_rows="2",nr_cols="6",
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
addr="0x00010734",func="callee4",
|
addr="0x00010734",func="callee4",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
|
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
|
bkpt={number="2",type="watchpoint",disp="keep",
|
bkpt={number="2",type="watchpoint",disp="keep",
|
enabled="y",addr="",what="C",times="-5"}]}
|
enabled="y",addr="",what="C",times="-5"}]}
|
(gdb)
|
(gdb)
|
-exec-continue
|
-exec-continue
|
^running
|
^running
|
^done,reason="watchpoint-scope",wpnum="2",
|
^done,reason="watchpoint-scope",wpnum="2",
|
frame={func="callee3",args=[{name="strarg",
|
frame={func="callee3",args=[{name="strarg",
|
value="0x11940 \"A string argument.\""}],
|
value="0x11940 \"A string argument.\""}],
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
|
(gdb)
|
(gdb)
|
-break-list
|
-break-list
|
^done,BreakpointTable={nr_rows="1",nr_cols="6",
|
^done,BreakpointTable={nr_rows="1",nr_cols="6",
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="14",alignment="-1",col_name="type",colhdr="Type"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
{width="40",alignment="2",col_name="what",colhdr="What"}],
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
addr="0x00010734",func="callee4",
|
addr="0x00010734",func="callee4",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
|
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
|
times="1"}]}
|
times="1"}]}
|
(gdb)
|
(gdb)
|
|
|
|
|
File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI
|
|
|
24.8 GDB/MI Program Context
|
24.8 GDB/MI Program Context
|
============================
|
============================
|
|
|
The `-exec-arguments' Command
|
The `-exec-arguments' Command
|
-----------------------------
|
-----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-arguments ARGS
|
-exec-arguments ARGS
|
|
|
Set the inferior program arguments, to be used in the next
|
Set the inferior program arguments, to be used in the next
|
`-exec-run'.
|
`-exec-run'.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `set args'.
|
The corresponding GDB command is `set args'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
Don't have one around.
|
Don't have one around.
|
|
|
The `-exec-show-arguments' Command
|
The `-exec-show-arguments' Command
|
----------------------------------
|
----------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-show-arguments
|
-exec-show-arguments
|
|
|
Print the arguments of the program.
|
Print the arguments of the program.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `show args'.
|
The corresponding GDB command is `show args'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-environment-cd' Command
|
The `-environment-cd' Command
|
-----------------------------
|
-----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-environment-cd PATHDIR
|
-environment-cd PATHDIR
|
|
|
Set GDB's working directory.
|
Set GDB's working directory.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `cd'.
|
The corresponding GDB command is `cd'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
|
-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
The `-environment-directory' Command
|
The `-environment-directory' Command
|
------------------------------------
|
------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-environment-directory [ -r ] [ PATHDIR ]+
|
-environment-directory [ -r ] [ PATHDIR ]+
|
|
|
Add directories PATHDIR to beginning of search path for source files.
|
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
|
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
|
search path. If directories PATHDIR are supplied in addition to the
|
`-r' option, the search path is first reset and then addition occurs as
|
`-r' option, the search path is first reset and then addition occurs as
|
normal. Multiple directories may be specified, separated by blanks.
|
normal. Multiple directories may be specified, separated by blanks.
|
Specifying multiple directories in a single command results in the
|
Specifying multiple directories in a single command results in the
|
directories added to the beginning of the search path in the same order
|
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
|
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
|
directory name, double-quotes should be used around the name. In the
|
command output, the path will show up separated by the system
|
command output, the path will show up separated by the system
|
directory-separator character. The directory-separator character must
|
directory-separator character. The directory-separator character must
|
not be used in any directory name. If no directories are specified,
|
not be used in any directory name. If no directories are specified,
|
the current search path is displayed.
|
the current search path is displayed.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `dir'.
|
The corresponding GDB command is `dir'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
|
-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
|
^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
|
^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
|
(gdb)
|
(gdb)
|
-environment-directory ""
|
-environment-directory ""
|
^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
|
^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
|
(gdb)
|
(gdb)
|
-environment-directory -r /home/jjohnstn/src/gdb /usr/src
|
-environment-directory -r /home/jjohnstn/src/gdb /usr/src
|
^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
|
^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
|
(gdb)
|
(gdb)
|
-environment-directory -r
|
-environment-directory -r
|
^done,source-path="$cdir:$cwd"
|
^done,source-path="$cdir:$cwd"
|
(gdb)
|
(gdb)
|
|
|
The `-environment-path' Command
|
The `-environment-path' Command
|
-------------------------------
|
-------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-environment-path [ -r ] [ PATHDIR ]+
|
-environment-path [ -r ] [ PATHDIR ]+
|
|
|
Add directories PATHDIR to beginning of search path for object files.
|
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
|
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
|
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
|
supplied in addition to the `-r' option, the search path is first reset
|
and then addition occurs as normal. Multiple directories may be
|
and then addition occurs as normal. Multiple directories may be
|
specified, separated by blanks. Specifying multiple directories in a
|
specified, separated by blanks. Specifying multiple directories in a
|
single command results in the directories added to the beginning of the
|
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
|
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
|
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
|
used around the name. In the command output, the path will show up
|
separated by the system directory-separator character. The
|
separated by the system directory-separator character. The
|
directory-separator character must not be used in any directory name.
|
directory-separator character must not be used in any directory name.
|
If no directories are specified, the current path is displayed.
|
If no directories are specified, the current path is displayed.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `path'.
|
The corresponding GDB command is `path'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-environment-path
|
-environment-path
|
^done,path="/usr/bin"
|
^done,path="/usr/bin"
|
(gdb)
|
(gdb)
|
-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
|
-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
|
^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
|
^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
|
(gdb)
|
(gdb)
|
-environment-path -r /usr/local/bin
|
-environment-path -r /usr/local/bin
|
^done,path="/usr/local/bin:/usr/bin"
|
^done,path="/usr/local/bin:/usr/bin"
|
(gdb)
|
(gdb)
|
|
|
The `-environment-pwd' Command
|
The `-environment-pwd' Command
|
------------------------------
|
------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-environment-pwd
|
-environment-pwd
|
|
|
Show the current working directory.
|
Show the current working directory.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `pwd'.
|
The corresponding GDB command is `pwd'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-environment-pwd
|
-environment-pwd
|
^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
|
^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
|
(gdb)
|
(gdb)
|
|
|
|
|
File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Program Context, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Program Context, Up: GDB/MI
|
|
|
24.9 GDB/MI Thread Commands
|
24.9 GDB/MI Thread Commands
|
===========================
|
===========================
|
|
|
The `-thread-info' Command
|
The `-thread-info' Command
|
--------------------------
|
--------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-thread-info
|
-thread-info
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
No equivalent.
|
No equivalent.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-thread-list-all-threads' Command
|
The `-thread-list-all-threads' Command
|
--------------------------------------
|
--------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-thread-list-all-threads
|
-thread-list-all-threads
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The equivalent GDB command is `info threads'.
|
The equivalent GDB command is `info threads'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-thread-list-ids' Command
|
The `-thread-list-ids' Command
|
------------------------------
|
------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-thread-list-ids
|
-thread-list-ids
|
|
|
Produces a list of the currently known GDB thread ids. At the end
|
Produces a list of the currently known GDB thread ids. At the end
|
of the list it also prints the total number of such threads.
|
of the list it also prints the total number of such threads.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
Part of `info threads' supplies the same information.
|
Part of `info threads' supplies the same information.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
No threads present, besides the main process:
|
No threads present, besides the main process:
|
|
|
(gdb)
|
(gdb)
|
-thread-list-ids
|
-thread-list-ids
|
^done,thread-ids={},number-of-threads="0"
|
^done,thread-ids={},number-of-threads="0"
|
(gdb)
|
(gdb)
|
|
|
Several threads:
|
Several threads:
|
|
|
(gdb)
|
(gdb)
|
-thread-list-ids
|
-thread-list-ids
|
^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},
|
^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},
|
number-of-threads="3"
|
number-of-threads="3"
|
(gdb)
|
(gdb)
|
|
|
The `-thread-select' Command
|
The `-thread-select' Command
|
----------------------------
|
----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-thread-select THREADNUM
|
-thread-select THREADNUM
|
|
|
Make THREADNUM the current thread. It prints the number of the new
|
Make THREADNUM the current thread. It prints the number of the new
|
current thread, and the topmost frame for that thread.
|
current thread, and the topmost frame for that thread.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `thread'.
|
The corresponding GDB command is `thread'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-exec-next
|
-exec-next
|
^running
|
^running
|
(gdb)
|
(gdb)
|
*stopped,reason="end-stepping-range",thread-id="2",line="187",
|
*stopped,reason="end-stepping-range",thread-id="2",line="187",
|
file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
|
file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
|
(gdb)
|
(gdb)
|
-thread-list-ids
|
-thread-list-ids
|
^done,
|
^done,
|
thread-ids={thread-id="3",thread-id="2",thread-id="1"},
|
thread-ids={thread-id="3",thread-id="2",thread-id="1"},
|
number-of-threads="3"
|
number-of-threads="3"
|
(gdb)
|
(gdb)
|
-thread-select 3
|
-thread-select 3
|
^done,new-thread-id="3",
|
^done,new-thread-id="3",
|
frame={level="0",func="vprintf",
|
frame={level="0",func="vprintf",
|
args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},
|
args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},
|
{name="arg",value="0x2"}],file="vprintf.c",line="31"}
|
{name="arg",value="0x2"}],file="vprintf.c",line="31"}
|
(gdb)
|
(gdb)
|
|
|
|
|
File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Thread Commands, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Thread Commands, Up: GDB/MI
|
|
|
24.10 GDB/MI Program Execution
|
24.10 GDB/MI Program Execution
|
==============================
|
==============================
|
|
|
These are the asynchronous commands which generate the out-of-band
|
These are the asynchronous commands which generate the out-of-band
|
record `*stopped'. Currently GDB only really executes asynchronously
|
record `*stopped'. Currently GDB only really executes asynchronously
|
with remote targets and this interaction is mimicked in other cases.
|
with remote targets and this interaction is mimicked in other cases.
|
|
|
The `-exec-continue' Command
|
The `-exec-continue' Command
|
----------------------------
|
----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-continue
|
-exec-continue
|
|
|
Resumes the execution of the inferior program until a breakpoint is
|
Resumes the execution of the inferior program until a breakpoint is
|
encountered, or until the inferior exits.
|
encountered, or until the inferior exits.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB corresponding is `continue'.
|
The corresponding GDB corresponding is `continue'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
-exec-continue
|
-exec-continue
|
^running
|
^running
|
(gdb)
|
(gdb)
|
@Hello world
|
@Hello world
|
*stopped,reason="breakpoint-hit",bkptno="2",frame={func="foo",args=[],
|
*stopped,reason="breakpoint-hit",bkptno="2",frame={func="foo",args=[],
|
file="hello.c",fullname="/home/foo/bar/hello.c",line="13"}
|
file="hello.c",fullname="/home/foo/bar/hello.c",line="13"}
|
(gdb)
|
(gdb)
|
|
|
The `-exec-finish' Command
|
The `-exec-finish' Command
|
--------------------------
|
--------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-finish
|
-exec-finish
|
|
|
Resumes the execution of the inferior program until the current
|
Resumes the execution of the inferior program until the current
|
function is exited. Displays the results returned by the function.
|
function is exited. Displays the results returned by the function.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `finish'.
|
The corresponding GDB command is `finish'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
Function returning `void'.
|
Function returning `void'.
|
|
|
-exec-finish
|
-exec-finish
|
^running
|
^running
|
(gdb)
|
(gdb)
|
@hello from foo
|
@hello from foo
|
*stopped,reason="function-finished",frame={func="main",args=[],
|
*stopped,reason="function-finished",frame={func="main",args=[],
|
file="hello.c",fullname="/home/foo/bar/hello.c",line="7"}
|
file="hello.c",fullname="/home/foo/bar/hello.c",line="7"}
|
(gdb)
|
(gdb)
|
|
|
Function returning other than `void'. The name of the internal GDB
|
Function returning other than `void'. The name of the internal GDB
|
variable storing the result is printed, together with the value itself.
|
variable storing the result is printed, together with the value itself.
|
|
|
-exec-finish
|
-exec-finish
|
^running
|
^running
|
(gdb)
|
(gdb)
|
*stopped,reason="function-finished",frame={addr="0x000107b0",func="foo",
|
*stopped,reason="function-finished",frame={addr="0x000107b0",func="foo",
|
args=[{name="a",value="1"],{name="b",value="9"}},
|
args=[{name="a",value="1"],{name="b",value="9"}},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
gdb-result-var="$1",return-value="0"
|
gdb-result-var="$1",return-value="0"
|
(gdb)
|
(gdb)
|
|
|
The `-exec-interrupt' Command
|
The `-exec-interrupt' Command
|
-----------------------------
|
-----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-interrupt
|
-exec-interrupt
|
|
|
Interrupts the background execution of the target. Note how the
|
Interrupts the background execution of the target. Note how the
|
token associated with the stop message is the one for the execution
|
token associated with the stop message is the one for the execution
|
command that has been interrupted. The token for the interrupt itself
|
command that has been interrupted. The token for the interrupt itself
|
only appears in the `^done' output. If the user is trying to interrupt
|
only appears in the `^done' output. If the user is trying to interrupt
|
a non-running program, an error message will be printed.
|
a non-running program, an error message will be printed.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `interrupt'.
|
The corresponding GDB command is `interrupt'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
111-exec-continue
|
111-exec-continue
|
111^running
|
111^running
|
|
|
(gdb)
|
(gdb)
|
222-exec-interrupt
|
222-exec-interrupt
|
222^done
|
222^done
|
(gdb)
|
(gdb)
|
111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
|
111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
|
frame={addr="0x00010140",func="foo",args=[],file="try.c",
|
frame={addr="0x00010140",func="foo",args=[],file="try.c",
|
fullname="/home/foo/bar/try.c",line="13"}
|
fullname="/home/foo/bar/try.c",line="13"}
|
(gdb)
|
(gdb)
|
|
|
(gdb)
|
(gdb)
|
-exec-interrupt
|
-exec-interrupt
|
^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
|
^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
|
(gdb)
|
(gdb)
|
|
|
The `-exec-next' Command
|
The `-exec-next' Command
|
------------------------
|
------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-next
|
-exec-next
|
|
|
Resumes execution of the inferior program, stopping when the
|
Resumes execution of the inferior program, stopping when the
|
beginning of the next source line is reached.
|
beginning of the next source line is reached.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `next'.
|
The corresponding GDB command is `next'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
-exec-next
|
-exec-next
|
^running
|
^running
|
(gdb)
|
(gdb)
|
*stopped,reason="end-stepping-range",line="8",file="hello.c"
|
*stopped,reason="end-stepping-range",line="8",file="hello.c"
|
(gdb)
|
(gdb)
|
|
|
The `-exec-next-instruction' Command
|
The `-exec-next-instruction' Command
|
------------------------------------
|
------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-next-instruction
|
-exec-next-instruction
|
|
|
Executes one machine instruction. If the instruction is a function
|
Executes one machine instruction. If the instruction is a function
|
call, continues until the function returns. If the program stops at an
|
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
|
instruction in the middle of a source line, the address will be printed
|
as well.
|
as well.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `nexti'.
|
The corresponding GDB command is `nexti'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-exec-next-instruction
|
-exec-next-instruction
|
^running
|
^running
|
|
|
(gdb)
|
(gdb)
|
*stopped,reason="end-stepping-range",
|
*stopped,reason="end-stepping-range",
|
addr="0x000100d4",line="5",file="hello.c"
|
addr="0x000100d4",line="5",file="hello.c"
|
(gdb)
|
(gdb)
|
|
|
The `-exec-return' Command
|
The `-exec-return' Command
|
--------------------------
|
--------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-return
|
-exec-return
|
|
|
Makes current function return immediately. Doesn't execute the
|
Makes current function return immediately. Doesn't execute the
|
inferior. Displays the new current frame.
|
inferior. Displays the new current frame.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `return'.
|
The corresponding GDB command is `return'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
200-break-insert callee4
|
200-break-insert callee4
|
200^done,bkpt={number="1",addr="0x00010734",
|
200^done,bkpt={number="1",addr="0x00010734",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
|
(gdb)
|
(gdb)
|
000-exec-run
|
000-exec-run
|
000^running
|
000^running
|
(gdb)
|
(gdb)
|
000*stopped,reason="breakpoint-hit",bkptno="1",
|
000*stopped,reason="breakpoint-hit",bkptno="1",
|
frame={func="callee4",args=[],
|
frame={func="callee4",args=[],
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
|
(gdb)
|
(gdb)
|
205-break-delete
|
205-break-delete
|
205^done
|
205^done
|
(gdb)
|
(gdb)
|
111-exec-return
|
111-exec-return
|
111^done,frame={level="0",func="callee3",
|
111^done,frame={level="0",func="callee3",
|
args=[{name="strarg",
|
args=[{name="strarg",
|
value="0x11940 \"A string argument.\""}],
|
value="0x11940 \"A string argument.\""}],
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
|
(gdb)
|
(gdb)
|
|
|
The `-exec-run' Command
|
The `-exec-run' Command
|
-----------------------
|
-----------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-run
|
-exec-run
|
|
|
Starts execution of the inferior from the beginning. The inferior
|
Starts execution of the inferior from the beginning. The inferior
|
executes until either a breakpoint is encountered or the program exits.
|
executes until either a breakpoint is encountered or the program exits.
|
In the latter case the output will include an exit code, if the
|
In the latter case the output will include an exit code, if the
|
program has exited exceptionally.
|
program has exited exceptionally.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `run'.
|
The corresponding GDB command is `run'.
|
|
|
Examples
|
Examples
|
........
|
........
|
|
|
(gdb)
|
(gdb)
|
-break-insert main
|
-break-insert main
|
^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
|
^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
|
(gdb)
|
(gdb)
|
-exec-run
|
-exec-run
|
^running
|
^running
|
(gdb)
|
(gdb)
|
*stopped,reason="breakpoint-hit",bkptno="1",
|
*stopped,reason="breakpoint-hit",bkptno="1",
|
frame={func="main",args=[],file="recursive2.c",
|
frame={func="main",args=[],file="recursive2.c",
|
fullname="/home/foo/bar/recursive2.c",line="4"}
|
fullname="/home/foo/bar/recursive2.c",line="4"}
|
(gdb)
|
(gdb)
|
|
|
Program exited normally:
|
Program exited normally:
|
|
|
(gdb)
|
(gdb)
|
-exec-run
|
-exec-run
|
^running
|
^running
|
(gdb)
|
(gdb)
|
x = 55
|
x = 55
|
*stopped,reason="exited-normally"
|
*stopped,reason="exited-normally"
|
(gdb)
|
(gdb)
|
|
|
Program exited exceptionally:
|
Program exited exceptionally:
|
|
|
(gdb)
|
(gdb)
|
-exec-run
|
-exec-run
|
^running
|
^running
|
(gdb)
|
(gdb)
|
x = 55
|
x = 55
|
*stopped,reason="exited",exit-code="01"
|
*stopped,reason="exited",exit-code="01"
|
(gdb)
|
(gdb)
|
|
|
Another way the program can terminate is if it receives a signal
|
Another way the program can terminate is if it receives a signal
|
such as `SIGINT'. In this case, GDB/MI displays this:
|
such as `SIGINT'. In this case, GDB/MI displays this:
|
|
|
(gdb)
|
(gdb)
|
*stopped,reason="exited-signalled",signal-name="SIGINT",
|
*stopped,reason="exited-signalled",signal-name="SIGINT",
|
signal-meaning="Interrupt"
|
signal-meaning="Interrupt"
|
|
|
The `-exec-step' Command
|
The `-exec-step' Command
|
------------------------
|
------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-step
|
-exec-step
|
|
|
Resumes execution of the inferior program, stopping when the
|
Resumes execution of the inferior program, stopping when the
|
beginning of the next source line is reached, if the next source line
|
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
|
is not a function call. If it is, stop at the first instruction of the
|
called function.
|
called function.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `step'.
|
The corresponding GDB command is `step'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
Stepping into a function:
|
Stepping into a function:
|
|
|
-exec-step
|
-exec-step
|
^running
|
^running
|
(gdb)
|
(gdb)
|
*stopped,reason="end-stepping-range",
|
*stopped,reason="end-stepping-range",
|
frame={func="foo",args=[{name="a",value="10"},
|
frame={func="foo",args=[{name="a",value="10"},
|
{name="b",value="0"}],file="recursive2.c",
|
{name="b",value="0"}],file="recursive2.c",
|
fullname="/home/foo/bar/recursive2.c",line="11"}
|
fullname="/home/foo/bar/recursive2.c",line="11"}
|
(gdb)
|
(gdb)
|
|
|
Regular stepping:
|
Regular stepping:
|
|
|
-exec-step
|
-exec-step
|
^running
|
^running
|
(gdb)
|
(gdb)
|
*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
|
*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
|
(gdb)
|
(gdb)
|
|
|
The `-exec-step-instruction' Command
|
The `-exec-step-instruction' Command
|
------------------------------------
|
------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-step-instruction
|
-exec-step-instruction
|
|
|
Resumes the inferior which executes one machine instruction. The
|
Resumes the inferior which executes one machine instruction. The
|
output, once GDB has stopped, will vary depending on whether we have
|
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
|
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.
|
address at which the program stopped will be printed as well.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `stepi'.
|
The corresponding GDB command is `stepi'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-exec-step-instruction
|
-exec-step-instruction
|
^running
|
^running
|
|
|
(gdb)
|
(gdb)
|
*stopped,reason="end-stepping-range",
|
*stopped,reason="end-stepping-range",
|
frame={func="foo",args=[],file="try.c",
|
frame={func="foo",args=[],file="try.c",
|
fullname="/home/foo/bar/try.c",line="10"}
|
fullname="/home/foo/bar/try.c",line="10"}
|
(gdb)
|
(gdb)
|
-exec-step-instruction
|
-exec-step-instruction
|
^running
|
^running
|
|
|
(gdb)
|
(gdb)
|
*stopped,reason="end-stepping-range",
|
*stopped,reason="end-stepping-range",
|
frame={addr="0x000100f4",func="foo",args=[],file="try.c",
|
frame={addr="0x000100f4",func="foo",args=[],file="try.c",
|
fullname="/home/foo/bar/try.c",line="10"}
|
fullname="/home/foo/bar/try.c",line="10"}
|
(gdb)
|
(gdb)
|
|
|
The `-exec-until' Command
|
The `-exec-until' Command
|
-------------------------
|
-------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-until [ LOCATION ]
|
-exec-until [ LOCATION ]
|
|
|
Executes the inferior until the LOCATION specified in the argument
|
Executes the inferior until the LOCATION specified in the argument
|
is reached. If there is no argument, the inferior executes until a
|
is reached. If there is no argument, the inferior executes until a
|
source line greater than the current one is reached. The reason for
|
source line greater than the current one is reached. The reason for
|
stopping in this case will be `location-reached'.
|
stopping in this case will be `location-reached'.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `until'.
|
The corresponding GDB command is `until'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-exec-until recursive2.c:6
|
-exec-until recursive2.c:6
|
^running
|
^running
|
(gdb)
|
(gdb)
|
x = 55
|
x = 55
|
*stopped,reason="location-reached",frame={func="main",args=[],
|
*stopped,reason="location-reached",frame={func="main",args=[],
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"}
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"}
|
(gdb)
|
(gdb)
|
|
|
|
|
File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI
|
|
|
24.11 GDB/MI Stack Manipulation Commands
|
24.11 GDB/MI Stack Manipulation Commands
|
========================================
|
========================================
|
|
|
The `-stack-info-frame' Command
|
The `-stack-info-frame' Command
|
-------------------------------
|
-------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-stack-info-frame
|
-stack-info-frame
|
|
|
Get info on the selected frame.
|
Get info on the selected frame.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `info frame' or `frame' (without
|
The corresponding GDB command is `info frame' or `frame' (without
|
arguments).
|
arguments).
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-stack-info-frame
|
-stack-info-frame
|
^done,frame={level="1",addr="0x0001076c",func="callee3",
|
^done,frame={level="1",addr="0x0001076c",func="callee3",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}
|
(gdb)
|
(gdb)
|
|
|
The `-stack-info-depth' Command
|
The `-stack-info-depth' Command
|
-------------------------------
|
-------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-stack-info-depth [ MAX-DEPTH ]
|
-stack-info-depth [ MAX-DEPTH ]
|
|
|
Return the depth of the stack. If the integer argument MAX-DEPTH is
|
Return the depth of the stack. If the integer argument MAX-DEPTH is
|
specified, do not count beyond MAX-DEPTH frames.
|
specified, do not count beyond MAX-DEPTH frames.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
There's no equivalent GDB command.
|
There's no equivalent GDB command.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
For a stack with frame levels 0 through 11:
|
For a stack with frame levels 0 through 11:
|
|
|
(gdb)
|
(gdb)
|
-stack-info-depth
|
-stack-info-depth
|
^done,depth="12"
|
^done,depth="12"
|
(gdb)
|
(gdb)
|
-stack-info-depth 4
|
-stack-info-depth 4
|
^done,depth="4"
|
^done,depth="4"
|
(gdb)
|
(gdb)
|
-stack-info-depth 12
|
-stack-info-depth 12
|
^done,depth="12"
|
^done,depth="12"
|
(gdb)
|
(gdb)
|
-stack-info-depth 11
|
-stack-info-depth 11
|
^done,depth="11"
|
^done,depth="11"
|
(gdb)
|
(gdb)
|
-stack-info-depth 13
|
-stack-info-depth 13
|
^done,depth="12"
|
^done,depth="12"
|
(gdb)
|
(gdb)
|
|
|
The `-stack-list-arguments' Command
|
The `-stack-list-arguments' Command
|
-----------------------------------
|
-----------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-stack-list-arguments SHOW-VALUES
|
-stack-list-arguments SHOW-VALUES
|
[ LOW-FRAME HIGH-FRAME ]
|
[ LOW-FRAME HIGH-FRAME ]
|
|
|
Display a list of the arguments for the frames between LOW-FRAME and
|
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,
|
HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided,
|
list the arguments for the whole call stack. If the two arguments are
|
list the arguments for the whole call stack. If the two arguments are
|
equal, show the single frame at the corresponding level. It is an
|
equal, show the single frame at the corresponding level. It is an
|
error if LOW-FRAME is larger than the actual number of frames. On the
|
error if LOW-FRAME is larger than the actual number of frames. On the
|
other hand, HIGH-FRAME may be larger than the actual number of frames,
|
other hand, HIGH-FRAME may be larger than the actual number of frames,
|
in which case only existing frames will be returned.
|
in which case only existing frames will be returned.
|
|
|
The SHOW-VALUES argument must have a value of 0 or 1. A value of 0
|
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 only the names of the arguments are listed, a value of 1
|
means that both names and values of the arguments are printed.
|
means that both names and values of the arguments are printed.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args'
|
GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args'
|
command which partially overlaps with the functionality of
|
command which partially overlaps with the functionality of
|
`-stack-list-arguments'.
|
`-stack-list-arguments'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-stack-list-frames
|
-stack-list-frames
|
^done,
|
^done,
|
stack=[
|
stack=[
|
frame={level="0",addr="0x00010734",func="callee4",
|
frame={level="0",addr="0x00010734",func="callee4",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"},
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"},
|
frame={level="1",addr="0x0001076c",func="callee3",
|
frame={level="1",addr="0x0001076c",func="callee3",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"},
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"},
|
frame={level="2",addr="0x0001078c",func="callee2",
|
frame={level="2",addr="0x0001078c",func="callee2",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"},
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"},
|
frame={level="3",addr="0x000107b4",func="callee1",
|
frame={level="3",addr="0x000107b4",func="callee1",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"},
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"},
|
frame={level="4",addr="0x000107e0",func="main",
|
frame={level="4",addr="0x000107e0",func="main",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}]
|
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}]
|
(gdb)
|
(gdb)
|
-stack-list-arguments 0
|
-stack-list-arguments 0
|
^done,
|
^done,
|
stack-args=[
|
stack-args=[
|
frame={level="0",args=[]},
|
frame={level="0",args=[]},
|
frame={level="1",args=[name="strarg"]},
|
frame={level="1",args=[name="strarg"]},
|
frame={level="2",args=[name="intarg",name="strarg"]},
|
frame={level="2",args=[name="intarg",name="strarg"]},
|
frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]},
|
frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]},
|
frame={level="4",args=[]}]
|
frame={level="4",args=[]}]
|
(gdb)
|
(gdb)
|
-stack-list-arguments 1
|
-stack-list-arguments 1
|
^done,
|
^done,
|
stack-args=[
|
stack-args=[
|
frame={level="0",args=[]},
|
frame={level="0",args=[]},
|
frame={level="1",
|
frame={level="1",
|
args=[{name="strarg",value="0x11940 \"A string argument.\""}]},
|
args=[{name="strarg",value="0x11940 \"A string argument.\""}]},
|
frame={level="2",args=[
|
frame={level="2",args=[
|
{name="intarg",value="2"},
|
{name="intarg",value="2"},
|
{name="strarg",value="0x11940 \"A string argument.\""}]},
|
{name="strarg",value="0x11940 \"A string argument.\""}]},
|
{frame={level="3",args=[
|
{frame={level="3",args=[
|
{name="intarg",value="2"},
|
{name="intarg",value="2"},
|
{name="strarg",value="0x11940 \"A string argument.\""},
|
{name="strarg",value="0x11940 \"A string argument.\""},
|
{name="fltarg",value="3.5"}]},
|
{name="fltarg",value="3.5"}]},
|
frame={level="4",args=[]}]
|
frame={level="4",args=[]}]
|
(gdb)
|
(gdb)
|
-stack-list-arguments 0 2 2
|
-stack-list-arguments 0 2 2
|
^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}]
|
^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}]
|
(gdb)
|
(gdb)
|
-stack-list-arguments 1 2 2
|
-stack-list-arguments 1 2 2
|
^done,stack-args=[frame={level="2",
|
^done,stack-args=[frame={level="2",
|
args=[{name="intarg",value="2"},
|
args=[{name="intarg",value="2"},
|
{name="strarg",value="0x11940 \"A string argument.\""}]}]
|
{name="strarg",value="0x11940 \"A string argument.\""}]}]
|
(gdb)
|
(gdb)
|
|
|
The `-stack-list-frames' Command
|
The `-stack-list-frames' Command
|
--------------------------------
|
--------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-stack-list-frames [ LOW-FRAME HIGH-FRAME ]
|
-stack-list-frames [ LOW-FRAME HIGH-FRAME ]
|
|
|
List the frames currently on the stack. For each frame it displays
|
List the frames currently on the stack. For each frame it displays
|
the following info:
|
the following info:
|
|
|
`LEVEL'
|
`LEVEL'
|
The frame number, 0 being the topmost frame, i.e., the innermost
|
The frame number, 0 being the topmost frame, i.e., the innermost
|
function.
|
function.
|
|
|
`ADDR'
|
`ADDR'
|
The `$pc' value for that frame.
|
The `$pc' value for that frame.
|
|
|
`FUNC'
|
`FUNC'
|
Function name.
|
Function name.
|
|
|
`FILE'
|
`FILE'
|
File name of the source file where the function lives.
|
File name of the source file where the function lives.
|
|
|
`LINE'
|
`LINE'
|
Line number corresponding to the `$pc'.
|
Line number corresponding to the `$pc'.
|
|
|
If invoked without arguments, this command prints a backtrace for the
|
If invoked without arguments, this command prints a backtrace for the
|
whole stack. If given two integer arguments, it shows the frames whose
|
whole stack. If given two integer arguments, it shows the frames whose
|
levels are between the two arguments (inclusive). If the two arguments
|
levels are between the two arguments (inclusive). If the two arguments
|
are equal, it shows the single frame at the corresponding level. It is
|
are equal, it shows the single frame at the corresponding level. It is
|
an error if LOW-FRAME is larger than the actual number of frames. On
|
an error if LOW-FRAME is larger than the actual number of frames. On
|
the other hand, HIGH-FRAME may be larger than the actual number of
|
the other hand, HIGH-FRAME may be larger than the actual number of
|
frames, in which case only existing frames will be returned.
|
frames, in which case only existing frames will be returned.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB commands are `backtrace' and `where'.
|
The corresponding GDB commands are `backtrace' and `where'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
Full stack backtrace:
|
Full stack backtrace:
|
|
|
(gdb)
|
(gdb)
|
-stack-list-frames
|
-stack-list-frames
|
^done,stack=
|
^done,stack=
|
[frame={level="0",addr="0x0001076c",func="foo",
|
[frame={level="0",addr="0x0001076c",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"},
|
frame={level="1",addr="0x000107a4",func="foo",
|
frame={level="1",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
frame={level="2",addr="0x000107a4",func="foo",
|
frame={level="2",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
frame={level="3",addr="0x000107a4",func="foo",
|
frame={level="3",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
frame={level="4",addr="0x000107a4",func="foo",
|
frame={level="4",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
frame={level="5",addr="0x000107a4",func="foo",
|
frame={level="5",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
frame={level="6",addr="0x000107a4",func="foo",
|
frame={level="6",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
frame={level="7",addr="0x000107a4",func="foo",
|
frame={level="7",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
frame={level="8",addr="0x000107a4",func="foo",
|
frame={level="8",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
frame={level="9",addr="0x000107a4",func="foo",
|
frame={level="9",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
frame={level="10",addr="0x000107a4",func="foo",
|
frame={level="10",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
frame={level="11",addr="0x00010738",func="main",
|
frame={level="11",addr="0x00010738",func="main",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}]
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}]
|
(gdb)
|
(gdb)
|
|
|
Show frames between LOW_FRAME and HIGH_FRAME:
|
Show frames between LOW_FRAME and HIGH_FRAME:
|
|
|
(gdb)
|
(gdb)
|
-stack-list-frames 3 5
|
-stack-list-frames 3 5
|
^done,stack=
|
^done,stack=
|
[frame={level="3",addr="0x000107a4",func="foo",
|
[frame={level="3",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
frame={level="4",addr="0x000107a4",func="foo",
|
frame={level="4",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
|
frame={level="5",addr="0x000107a4",func="foo",
|
frame={level="5",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
|
(gdb)
|
(gdb)
|
|
|
Show a single frame:
|
Show a single frame:
|
|
|
(gdb)
|
(gdb)
|
-stack-list-frames 3 3
|
-stack-list-frames 3 3
|
^done,stack=
|
^done,stack=
|
[frame={level="3",addr="0x000107a4",func="foo",
|
[frame={level="3",addr="0x000107a4",func="foo",
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
|
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
|
(gdb)
|
(gdb)
|
|
|
The `-stack-list-locals' Command
|
The `-stack-list-locals' Command
|
--------------------------------
|
--------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-stack-list-locals PRINT-VALUES
|
-stack-list-locals PRINT-VALUES
|
|
|
Display the local variable names for the selected frame. If
|
Display the local variable names for the selected frame. If
|
PRINT-VALUES is 0 or `--no-values', print only the names of the
|
PRINT-VALUES is 0 or `--no-values', print only the names of the
|
variables; if it is 1 or `--all-values', print also their values; and
|
variables; if it is 1 or `--all-values', print also their values; and
|
if it is 2 or `--simple-values', print the name, type and value for
|
if it is 2 or `--simple-values', print the name, type and value for
|
simple data types and the name and type for arrays, structures and
|
simple data types and the name and type for arrays, structures and
|
unions. In this last case, a frontend can immediately display the
|
unions. In this last case, a frontend can immediately display the
|
value of simple data types and create variable objects for other data
|
value of simple data types and create variable objects for other data
|
types when the user wishes to explore their values in more detail.
|
types when the user wishes to explore their values in more detail.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
`info locals' in GDB, `gdb_get_locals' in `gdbtk'.
|
`info locals' in GDB, `gdb_get_locals' in `gdbtk'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-stack-list-locals 0
|
-stack-list-locals 0
|
^done,locals=[name="A",name="B",name="C"]
|
^done,locals=[name="A",name="B",name="C"]
|
(gdb)
|
(gdb)
|
-stack-list-locals --all-values
|
-stack-list-locals --all-values
|
^done,locals=[{name="A",value="1"},{name="B",value="2"},
|
^done,locals=[{name="A",value="1"},{name="B",value="2"},
|
{name="C",value="{1, 2, 3}"}]
|
{name="C",value="{1, 2, 3}"}]
|
-stack-list-locals --simple-values
|
-stack-list-locals --simple-values
|
^done,locals=[{name="A",type="int",value="1"},
|
^done,locals=[{name="A",type="int",value="1"},
|
{name="B",type="int",value="2"},{name="C",type="int [3]"}]
|
{name="B",type="int",value="2"},{name="C",type="int [3]"}]
|
(gdb)
|
(gdb)
|
|
|
The `-stack-select-frame' Command
|
The `-stack-select-frame' Command
|
---------------------------------
|
---------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-stack-select-frame FRAMENUM
|
-stack-select-frame FRAMENUM
|
|
|
Change the selected frame. Select a different frame FRAMENUM on the
|
Change the selected frame. Select a different frame FRAMENUM on the
|
stack.
|
stack.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB commands are `frame', `up', `down',
|
The corresponding GDB commands are `frame', `up', `down',
|
`select-frame', `up-silent', and `down-silent'.
|
`select-frame', `up-silent', and `down-silent'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-stack-select-frame 2
|
-stack-select-frame 2
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
|
|
File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI
|
|
|
24.12 GDB/MI Variable Objects
|
24.12 GDB/MI Variable Objects
|
=============================
|
=============================
|
|
|
Introduction to Variable Objects
|
Introduction to Variable Objects
|
--------------------------------
|
--------------------------------
|
|
|
Variable objects are "object-oriented" MI interface for examining and
|
Variable objects are "object-oriented" MI interface for examining and
|
changing values of expressions. Unlike some other MI interfaces that
|
changing values of expressions. Unlike some other MI interfaces that
|
work with expressions, variable objects are specifically designed for
|
work with expressions, variable objects are specifically designed for
|
simple and efficient presentation in the frontend. A variable object
|
simple and efficient presentation in the frontend. A variable object
|
is identified by string name. When a variable object is created, the
|
is identified by string name. When a variable object is created, the
|
frontend specifies the expression for that variable object. The
|
frontend specifies the expression for that variable object. The
|
expression can be a simple variable, or it can be an arbitrary complex
|
expression can be a simple variable, or it can be an arbitrary complex
|
expression, and can even involve CPU registers. After creating a
|
expression, and can even involve CPU registers. After creating a
|
variable object, the frontend can invoke other variable object
|
variable object, the frontend can invoke other variable object
|
operations--for example to obtain or change the value of a variable
|
operations--for example to obtain or change the value of a variable
|
object, or to change display format.
|
object, or to change display format.
|
|
|
Variable objects have hierarchical tree structure. Any variable
|
Variable objects have hierarchical tree structure. Any variable
|
object that corresponds to a composite type, such as structure in C, has
|
object that corresponds to a composite type, such as structure in C, has
|
a number of child variable objects, for example corresponding to each
|
a number of child variable objects, for example corresponding to each
|
element of a structure. A child variable object can itself have
|
element of a structure. A child variable object can itself have
|
children, recursively. Recursion ends when we reach leaf variable
|
children, recursively. Recursion ends when we reach leaf variable
|
objects, which always have built-in types. Child variable objects are
|
objects, which always have built-in types. Child variable objects are
|
created only by explicit request, so if a frontend is not interested in
|
created only by explicit request, so if a frontend is not interested in
|
the children of a particular variable object, no child will be created.
|
the children of a particular variable object, no child will be created.
|
|
|
For a leaf variable object it is possible to obtain its value as a
|
For a leaf variable object it is possible to obtain its value as a
|
string, or set the value from a string. String value can be also
|
string, or set the value from a string. String value can be also
|
obtained for a non-leaf variable object, but it's generally a string
|
obtained for a non-leaf variable object, but it's generally a string
|
that only indicates the type of the object, and does not list its
|
that only indicates the type of the object, and does not list its
|
contents. Assignment to a non-leaf variable object is not allowed.
|
contents. Assignment to a non-leaf variable object is not allowed.
|
|
|
A frontend does not need to read the values of all variable objects
|
A frontend does not need to read the values of all variable objects
|
each time the program stops. Instead, MI provides an update command
|
each time the program stops. Instead, MI provides an update command
|
that lists all variable objects whose values has changed since the last
|
that lists all variable objects whose values has changed since the last
|
update operation. This considerably reduces the amount of data that
|
update operation. This considerably reduces the amount of data that
|
must be transferred to the frontend. As noted above, children variable
|
must be transferred to the frontend. As noted above, children variable
|
objects are created on demand, and only leaf variable objects have a
|
objects are created on demand, and only leaf variable objects have a
|
real value. As result, gdb will read target memory only for leaf
|
real value. As result, gdb will read target memory only for leaf
|
variables that frontend has created.
|
variables that frontend has created.
|
|
|
The automatic update is not always desirable. For example, a
|
The automatic update is not always desirable. For example, a
|
frontend might want to keep a value of some expression for future
|
frontend might want to keep a value of some expression for future
|
reference, and never update it. For another example, fetching memory
|
reference, and never update it. For another example, fetching memory
|
is relatively slow for embedded targets, so a frontend might want to
|
is relatively slow for embedded targets, so a frontend might want to
|
disable automatic update for the variables that are either not visible
|
disable automatic update for the variables that are either not visible
|
on the screen, or "closed". This is possible using so called "frozen
|
on the screen, or "closed". This is possible using so called "frozen
|
variable objects". Such variable objects are never implicitly updated.
|
variable objects". Such variable objects are never implicitly updated.
|
|
|
The following is the complete set of GDB/MI operations defined to
|
The following is the complete set of GDB/MI operations defined to
|
access this functionality:
|
access this functionality:
|
|
|
*Operation* *Description*
|
*Operation* *Description*
|
`-var-create' create a variable object
|
`-var-create' create a variable object
|
`-var-delete' delete the variable object and/or its
|
`-var-delete' delete the variable object and/or its
|
children
|
children
|
`-var-set-format' set the display format of this variable
|
`-var-set-format' set the display format of this variable
|
`-var-show-format' show 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-info-num-children' tells how many children this object has
|
`-var-list-children' return a list of the object's children
|
`-var-list-children' return a list of the object's children
|
`-var-info-type' show the type of this variable object
|
`-var-info-type' show the type of this variable object
|
`-var-info-expression' print parent-relative expression that this
|
`-var-info-expression' print parent-relative expression that this
|
variable object represents
|
variable object represents
|
`-var-info-path-expression' print full expression that this variable
|
`-var-info-path-expression' print full expression that this variable
|
object represents
|
object represents
|
`-var-show-attributes' is this variable editable? does it exist
|
`-var-show-attributes' is this variable editable? does it exist
|
here?
|
here?
|
`-var-evaluate-expression' get the value of this variable
|
`-var-evaluate-expression' get the value of this variable
|
`-var-assign' set the value of this variable
|
`-var-assign' set the value of this variable
|
`-var-update' update the variable and its children
|
`-var-update' update the variable and its children
|
`-var-set-frozen' set frozeness attribute
|
`-var-set-frozen' set frozeness attribute
|
|
|
In the next subsection we describe each operation in detail and
|
In the next subsection we describe each operation in detail and
|
suggest how it can be used.
|
suggest how it can be used.
|
|
|
Description And Use of Operations on Variable Objects
|
Description And Use of Operations on Variable Objects
|
-----------------------------------------------------
|
-----------------------------------------------------
|
|
|
The `-var-create' Command
|
The `-var-create' Command
|
-------------------------
|
-------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-create {NAME | "-"}
|
-var-create {NAME | "-"}
|
{FRAME-ADDR | "*"} EXPRESSION
|
{FRAME-ADDR | "*"} EXPRESSION
|
|
|
This operation creates a variable object, which allows the
|
This operation creates a variable object, which allows the
|
monitoring of a variable, the result of an expression, a memory cell or
|
monitoring of a variable, the result of an expression, a memory cell or
|
a CPU register.
|
a CPU register.
|
|
|
The NAME parameter is the string by which the object can be
|
The NAME parameter is the string by which the object can be
|
referenced. It must be unique. If `-' is specified, the varobj system
|
referenced. It must be unique. If `-' is specified, the varobj system
|
will generate a string "varNNNNNN" automatically. It will be unique
|
will generate a string "varNNNNNN" automatically. It will be unique
|
provided that one does not specify NAME on that format. The command
|
provided that one does not specify NAME on that format. The command
|
fails if a duplicate name is found.
|
fails if a duplicate name is found.
|
|
|
The frame under which the expression should be evaluated can be
|
The frame under which the expression should be evaluated can be
|
specified by FRAME-ADDR. A `*' indicates that the current frame should
|
specified by FRAME-ADDR. A `*' indicates that the current frame should
|
be used.
|
be used.
|
|
|
EXPRESSION is any expression valid on the current language set (must
|
EXPRESSION is any expression valid on the current language set (must
|
not begin with a `*'), or one of the following:
|
not begin with a `*'), or one of the following:
|
|
|
* `*ADDR', where ADDR is the address of a memory cell
|
* `*ADDR', where ADDR is the address of a memory cell
|
|
|
* `*ADDR-ADDR' -- a memory address range (TBD)
|
* `*ADDR-ADDR' -- a memory address range (TBD)
|
|
|
* `$REGNAME' -- a CPU register name
|
* `$REGNAME' -- a CPU register name
|
|
|
Result
|
Result
|
......
|
......
|
|
|
This operation returns the name, number of children and the type of the
|
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
|
object created. Type is returned as a string as the ones generated by
|
the GDB CLI:
|
the GDB CLI:
|
|
|
name="NAME",numchild="N",type="TYPE"
|
name="NAME",numchild="N",type="TYPE"
|
|
|
The `-var-delete' Command
|
The `-var-delete' Command
|
-------------------------
|
-------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-delete [ -c ] NAME
|
-var-delete [ -c ] NAME
|
|
|
Deletes a previously created variable object and all of its children.
|
Deletes a previously created variable object and all of its children.
|
With the `-c' option, just deletes the children.
|
With the `-c' option, just deletes the children.
|
|
|
Returns an error if the object NAME is not found.
|
Returns an error if the object NAME is not found.
|
|
|
The `-var-set-format' Command
|
The `-var-set-format' Command
|
-----------------------------
|
-----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-set-format NAME FORMAT-SPEC
|
-var-set-format NAME FORMAT-SPEC
|
|
|
Sets the output format for the value of the object NAME to be
|
Sets the output format for the value of the object NAME to be
|
FORMAT-SPEC.
|
FORMAT-SPEC.
|
|
|
The syntax for the FORMAT-SPEC is as follows:
|
The syntax for the FORMAT-SPEC is as follows:
|
|
|
FORMAT-SPEC ==>
|
FORMAT-SPEC ==>
|
{binary | decimal | hexadecimal | octal | natural}
|
{binary | decimal | hexadecimal | octal | natural}
|
|
|
The natural format is the default format choosen automatically based
|
The natural format is the default format choosen automatically based
|
on the variable type (like decimal for an `int', hex for pointers,
|
on the variable type (like decimal for an `int', hex for pointers,
|
etc.).
|
etc.).
|
|
|
For a variable with children, the format is set only on the variable
|
For a variable with children, the format is set only on the variable
|
itself, and the children are not affected.
|
itself, and the children are not affected.
|
|
|
The `-var-show-format' Command
|
The `-var-show-format' Command
|
------------------------------
|
------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-show-format NAME
|
-var-show-format NAME
|
|
|
Returns the format used to display the value of the object NAME.
|
Returns the format used to display the value of the object NAME.
|
|
|
FORMAT ==>
|
FORMAT ==>
|
FORMAT-SPEC
|
FORMAT-SPEC
|
|
|
The `-var-info-num-children' Command
|
The `-var-info-num-children' Command
|
------------------------------------
|
------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-info-num-children NAME
|
-var-info-num-children NAME
|
|
|
Returns the number of children of a variable object NAME:
|
Returns the number of children of a variable object NAME:
|
|
|
numchild=N
|
numchild=N
|
|
|
The `-var-list-children' Command
|
The `-var-list-children' Command
|
--------------------------------
|
--------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-list-children [PRINT-VALUES] NAME
|
-var-list-children [PRINT-VALUES] NAME
|
|
|
Return a list of the children of the specified variable object and
|
Return a list of the children of the specified variable object and
|
create variable objects for them, if they do not already exist. With a
|
create variable objects for them, if they do not already exist. With a
|
single argument or if PRINT-VALUES has a value for of 0 or
|
single argument or if PRINT-VALUES has a value for of 0 or
|
`--no-values', print only the names of the variables; if PRINT-VALUES
|
`--no-values', print only the names of the variables; if PRINT-VALUES
|
is 1 or `--all-values', also print their values; and if it is 2 or
|
is 1 or `--all-values', also print their values; and if it is 2 or
|
`--simple-values' print the name and value for simple data types and
|
`--simple-values' print the name and value for simple data types and
|
just the name for arrays, structures and unions.
|
just the name for arrays, structures and unions.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-var-list-children n
|
-var-list-children n
|
^done,numchild=N,children=[{name=NAME,
|
^done,numchild=N,children=[{name=NAME,
|
numchild=N,type=TYPE},(repeats N times)]
|
numchild=N,type=TYPE},(repeats N times)]
|
(gdb)
|
(gdb)
|
-var-list-children --all-values n
|
-var-list-children --all-values n
|
^done,numchild=N,children=[{name=NAME,
|
^done,numchild=N,children=[{name=NAME,
|
numchild=N,value=VALUE,type=TYPE},(repeats N times)]
|
numchild=N,value=VALUE,type=TYPE},(repeats N times)]
|
|
|
The `-var-info-type' Command
|
The `-var-info-type' Command
|
----------------------------
|
----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-info-type NAME
|
-var-info-type NAME
|
|
|
Returns the type of the specified variable NAME. The type is
|
Returns the type of the specified variable NAME. The type is
|
returned as a string in the same format as it is output by the GDB CLI:
|
returned as a string in the same format as it is output by the GDB CLI:
|
|
|
type=TYPENAME
|
type=TYPENAME
|
|
|
The `-var-info-expression' Command
|
The `-var-info-expression' Command
|
----------------------------------
|
----------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-info-expression NAME
|
-var-info-expression NAME
|
|
|
Returns a string that is suitable for presenting this variable
|
Returns a string that is suitable for presenting this variable
|
object in user interface. The string is generally not valid expression
|
object in user interface. The string is generally not valid expression
|
in the current language, and cannot be evaluated.
|
in the current language, and cannot be evaluated.
|
|
|
For example, if `a' is an array, and variable object `A' was created
|
For example, if `a' is an array, and variable object `A' was created
|
for `a', then we'll get this output:
|
for `a', then we'll get this output:
|
|
|
(gdb) -var-info-expression A.1
|
(gdb) -var-info-expression A.1
|
^done,lang="C",exp="1"
|
^done,lang="C",exp="1"
|
|
|
Here, the values of `lang' can be `{"C" | "C++" | "Java"}'.
|
Here, the values of `lang' can be `{"C" | "C++" | "Java"}'.
|
|
|
Note that the output of the `-var-list-children' command also
|
Note that the output of the `-var-list-children' command also
|
includes those expressions, so the `-var-info-expression' command is of
|
includes those expressions, so the `-var-info-expression' command is of
|
limited use.
|
limited use.
|
|
|
The `-var-info-path-expression' Command
|
The `-var-info-path-expression' Command
|
---------------------------------------
|
---------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-info-path-expression NAME
|
-var-info-path-expression NAME
|
|
|
Returns an expression that can be evaluated in the current context
|
Returns an expression that can be evaluated in the current context
|
and will yield the same value that a variable object has. Compare this
|
and will yield the same value that a variable object has. Compare this
|
with the `-var-info-expression' command, which result can be used only
|
with the `-var-info-expression' command, which result can be used only
|
for UI presentation. Typical use of the `-var-info-path-expression'
|
for UI presentation. Typical use of the `-var-info-path-expression'
|
command is creating a watchpoint from a variable object.
|
command is creating a watchpoint from a variable object.
|
|
|
For example, suppose `C' is a C++ class, derived from class `Base',
|
For example, suppose `C' is a C++ class, derived from class `Base',
|
and that the `Base' class has a member called `m_size'. Assume a
|
and that the `Base' class has a member called `m_size'. Assume a
|
variable `c' is has the type of `C' and a variable object `C' was
|
variable `c' is has the type of `C' and a variable object `C' was
|
created for variable `c'. Then, we'll get this output:
|
created for variable `c'. Then, we'll get this output:
|
(gdb) -var-info-path-expression C.Base.public.m_size
|
(gdb) -var-info-path-expression C.Base.public.m_size
|
^done,path_expr=((Base)c).m_size)
|
^done,path_expr=((Base)c).m_size)
|
|
|
The `-var-show-attributes' Command
|
The `-var-show-attributes' Command
|
----------------------------------
|
----------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-show-attributes NAME
|
-var-show-attributes NAME
|
|
|
List attributes of the specified variable object NAME:
|
List attributes of the specified variable object NAME:
|
|
|
status=ATTR [ ( ,ATTR )* ]
|
status=ATTR [ ( ,ATTR )* ]
|
|
|
where ATTR is `{ { editable | noneditable } | TBD }'.
|
where ATTR is `{ { editable | noneditable } | TBD }'.
|
|
|
The `-var-evaluate-expression' Command
|
The `-var-evaluate-expression' Command
|
--------------------------------------
|
--------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-evaluate-expression NAME
|
-var-evaluate-expression NAME
|
|
|
Evaluates the expression that is represented by the specified
|
Evaluates the expression that is represented by the specified
|
variable object and returns its value as a string. The format of the
|
variable object and returns its value as a string. The format of the
|
string can be changed using the `-var-set-format' command.
|
string can be changed using the `-var-set-format' command.
|
|
|
value=VALUE
|
value=VALUE
|
|
|
Note that one must invoke `-var-list-children' for a variable before
|
Note that one must invoke `-var-list-children' for a variable before
|
the value of a child variable can be evaluated.
|
the value of a child variable can be evaluated.
|
|
|
The `-var-assign' Command
|
The `-var-assign' Command
|
-------------------------
|
-------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-assign NAME EXPRESSION
|
-var-assign NAME EXPRESSION
|
|
|
Assigns the value of EXPRESSION to the variable object specified by
|
Assigns the value of EXPRESSION to the variable object specified by
|
NAME. The object must be `editable'. If the variable's value is
|
NAME. The object must be `editable'. If the variable's value is
|
altered by the assign, the variable will show up in any subsequent
|
altered by the assign, the variable will show up in any subsequent
|
`-var-update' list.
|
`-var-update' list.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-var-assign var1 3
|
-var-assign var1 3
|
^done,value="3"
|
^done,value="3"
|
(gdb)
|
(gdb)
|
-var-update *
|
-var-update *
|
^done,changelist=[{name="var1",in_scope="true",type_changed="false"}]
|
^done,changelist=[{name="var1",in_scope="true",type_changed="false"}]
|
(gdb)
|
(gdb)
|
|
|
The `-var-update' Command
|
The `-var-update' Command
|
-------------------------
|
-------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-update [PRINT-VALUES] {NAME | "*"}
|
-var-update [PRINT-VALUES] {NAME | "*"}
|
|
|
Reevaluate the expressions corresponding to the variable object NAME
|
Reevaluate the expressions corresponding to the variable object NAME
|
and all its direct and indirect children, and return the list of
|
and all its direct and indirect children, and return the list of
|
variable objects whose values have changed; NAME must be a root
|
variable objects whose values have changed; NAME must be a root
|
variable object. Here, "changed" means that the result of
|
variable object. Here, "changed" means that the result of
|
`-var-evaluate-expression' before and after the `-var-update' is
|
`-var-evaluate-expression' before and after the `-var-update' is
|
different. If `*' is used as the variable object names, all existing
|
different. If `*' is used as the variable object names, all existing
|
variable objects are updated, except for frozen ones (*note
|
variable objects are updated, except for frozen ones (*note
|
-var-set-frozen::). The option PRINT-VALUES determines whether both
|
-var-set-frozen::). The option PRINT-VALUES determines whether both
|
names and values, or just names are printed. The possible values of
|
names and values, or just names are printed. The possible values of
|
this options are the same as for `-var-list-children' (*note
|
this options are the same as for `-var-list-children' (*note
|
-var-list-children::). It is recommended to use the `--all-values'
|
-var-list-children::). It is recommended to use the `--all-values'
|
option, to reduce the number of MI commands needed on each program stop.
|
option, to reduce the number of MI commands needed on each program stop.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-var-assign var1 3
|
-var-assign var1 3
|
^done,value="3"
|
^done,value="3"
|
(gdb)
|
(gdb)
|
-var-update --all-values var1
|
-var-update --all-values var1
|
^done,changelist=[{name="var1",value="3",in_scope="true",
|
^done,changelist=[{name="var1",value="3",in_scope="true",
|
type_changed="false"}]
|
type_changed="false"}]
|
(gdb)
|
(gdb)
|
|
|
The field in_scope may take three values:
|
The field in_scope may take three values:
|
|
|
`"true"'
|
`"true"'
|
The variable object's current value is valid.
|
The variable object's current value is valid.
|
|
|
`"false"'
|
`"false"'
|
The variable object does not currently hold a valid value but it
|
The variable object does not currently hold a valid value but it
|
may hold one in the future if its associated expression comes back
|
may hold one in the future if its associated expression comes back
|
into scope.
|
into scope.
|
|
|
`"invalid"'
|
`"invalid"'
|
The variable object no longer holds a valid value. This can occur
|
The variable object no longer holds a valid value. This can occur
|
when the executable file being debugged has changed, either
|
when the executable file being debugged has changed, either
|
through recompilation or by using the GDB `file' command. The
|
through recompilation or by using the GDB `file' command. The
|
front end should normally choose to delete these variable objects.
|
front end should normally choose to delete these variable objects.
|
|
|
In the future new values may be added to this list so the front
|
In the future new values may be added to this list so the front
|
should be prepared for this possibility. *Note GDB/MI Development and
|
should be prepared for this possibility. *Note GDB/MI Development and
|
Front Ends: GDB/MI Development and Front Ends.
|
Front Ends: GDB/MI Development and Front Ends.
|
|
|
The `-var-set-frozen' Command
|
The `-var-set-frozen' Command
|
-----------------------------
|
-----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-var-set-frozen NAME FLAG
|
-var-set-frozen NAME FLAG
|
|
|
Set the frozenness flag on the variable object NAME. The FLAG
|
Set the frozenness flag on the variable object NAME. The FLAG
|
parameter should be either `1' to make the variable frozen or `0' to
|
parameter should be either `1' to make the variable frozen or `0' to
|
make it unfrozen. If a variable object is frozen, then neither itself,
|
make it unfrozen. If a variable object is frozen, then neither itself,
|
nor any of its children, are implicitly updated by `-var-update' of a
|
nor any of its children, are implicitly updated by `-var-update' of a
|
parent variable or by `-var-update *'. Only `-var-update' of the
|
parent variable or by `-var-update *'. Only `-var-update' of the
|
variable itself will update its value and values of its children.
|
variable itself will update its value and values of its children.
|
After a variable object is unfrozen, it is implicitly updated by all
|
After a variable object is unfrozen, it is implicitly updated by all
|
subsequent `-var-update' operations. Unfreezing a variable does not
|
subsequent `-var-update' operations. Unfreezing a variable does not
|
update it, only subsequent `-var-update' does.
|
update it, only subsequent `-var-update' does.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-var-set-frozen V 1
|
-var-set-frozen V 1
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
|
|
File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI
|
|
|
24.13 GDB/MI Data Manipulation
|
24.13 GDB/MI Data Manipulation
|
==============================
|
==============================
|
|
|
This section describes the GDB/MI commands that manipulate data:
|
This section describes the GDB/MI commands that manipulate data:
|
examine memory and registers, evaluate expressions, etc.
|
examine memory and registers, evaluate expressions, etc.
|
|
|
The `-data-disassemble' Command
|
The `-data-disassemble' Command
|
-------------------------------
|
-------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-data-disassemble
|
-data-disassemble
|
[ -s START-ADDR -e END-ADDR ]
|
[ -s START-ADDR -e END-ADDR ]
|
| [ -f FILENAME -l LINENUM [ -n LINES ] ]
|
| [ -f FILENAME -l LINENUM [ -n LINES ] ]
|
-- MODE
|
-- MODE
|
|
|
Where:
|
Where:
|
|
|
`START-ADDR'
|
`START-ADDR'
|
is the beginning address (or `$pc')
|
is the beginning address (or `$pc')
|
|
|
`END-ADDR'
|
`END-ADDR'
|
is the end address
|
is the end address
|
|
|
`FILENAME'
|
`FILENAME'
|
is the name of the file to disassemble
|
is the name of the file to disassemble
|
|
|
`LINENUM'
|
`LINENUM'
|
is the line number to disassemble around
|
is the line number to disassemble around
|
|
|
`LINES'
|
`LINES'
|
is the number of disassembly lines to be produced. If it is -1,
|
is the number of disassembly lines to be produced. If it is -1,
|
the whole function will be disassembled, in case no END-ADDR is
|
the whole function will be disassembled, in case no END-ADDR is
|
specified. If END-ADDR is specified as a non-zero value, and
|
specified. If END-ADDR is specified as a non-zero value, and
|
LINES is lower than the number of disassembly lines between
|
LINES is lower than the number of disassembly lines between
|
START-ADDR and END-ADDR, only LINES lines are displayed; if LINES
|
START-ADDR and END-ADDR, only LINES lines are displayed; if LINES
|
is higher than the number of lines between START-ADDR and
|
is higher than the number of lines between START-ADDR and
|
END-ADDR, only the lines up to END-ADDR are displayed.
|
END-ADDR, only the lines up to END-ADDR are displayed.
|
|
|
`MODE'
|
`MODE'
|
is either 0 (meaning only disassembly) or 1 (meaning mixed source
|
is either 0 (meaning only disassembly) or 1 (meaning mixed source
|
and disassembly).
|
and disassembly).
|
|
|
Result
|
Result
|
......
|
......
|
|
|
The output for each instruction is composed of four fields:
|
The output for each instruction is composed of four fields:
|
|
|
* Address
|
* Address
|
|
|
* Func-name
|
* Func-name
|
|
|
* Offset
|
* Offset
|
|
|
* Instruction
|
* Instruction
|
|
|
Note that whatever included in the instruction field, is not
|
Note that whatever included in the instruction field, is not
|
manipulated directly by GDB/MI, i.e., it is not possible to adjust its
|
manipulated directly by GDB/MI, i.e., it is not possible to adjust its
|
format.
|
format.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
There's no direct mapping from this command to the CLI.
|
There's no direct mapping from this command to the CLI.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
Disassemble from the current value of `$pc' to `$pc + 20':
|
Disassemble from the current value of `$pc' to `$pc + 20':
|
|
|
(gdb)
|
(gdb)
|
-data-disassemble -s $pc -e "$pc + 20" -- 0
|
-data-disassemble -s $pc -e "$pc + 20" -- 0
|
^done,
|
^done,
|
asm_insns=[
|
asm_insns=[
|
{address="0x000107c0",func-name="main",offset="4",
|
{address="0x000107c0",func-name="main",offset="4",
|
inst="mov 2, %o0"},
|
inst="mov 2, %o0"},
|
{address="0x000107c4",func-name="main",offset="8",
|
{address="0x000107c4",func-name="main",offset="8",
|
inst="sethi %hi(0x11800), %o2"},
|
inst="sethi %hi(0x11800), %o2"},
|
{address="0x000107c8",func-name="main",offset="12",
|
{address="0x000107c8",func-name="main",offset="12",
|
inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},
|
inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},
|
{address="0x000107cc",func-name="main",offset="16",
|
{address="0x000107cc",func-name="main",offset="16",
|
inst="sethi %hi(0x11800), %o2"},
|
inst="sethi %hi(0x11800), %o2"},
|
{address="0x000107d0",func-name="main",offset="20",
|
{address="0x000107d0",func-name="main",offset="20",
|
inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}]
|
inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}]
|
(gdb)
|
(gdb)
|
|
|
Disassemble the whole `main' function. Line 32 is part of `main'.
|
Disassemble the whole `main' function. Line 32 is part of `main'.
|
|
|
-data-disassemble -f basics.c -l 32 -- 0
|
-data-disassemble -f basics.c -l 32 -- 0
|
^done,asm_insns=[
|
^done,asm_insns=[
|
{address="0x000107bc",func-name="main",offset="0",
|
{address="0x000107bc",func-name="main",offset="0",
|
inst="save %sp, -112, %sp"},
|
inst="save %sp, -112, %sp"},
|
{address="0x000107c0",func-name="main",offset="4",
|
{address="0x000107c0",func-name="main",offset="4",
|
inst="mov 2, %o0"},
|
inst="mov 2, %o0"},
|
{address="0x000107c4",func-name="main",offset="8",
|
{address="0x000107c4",func-name="main",offset="8",
|
inst="sethi %hi(0x11800), %o2"},
|
inst="sethi %hi(0x11800), %o2"},
|
[...]
|
[...]
|
{address="0x0001081c",func-name="main",offset="96",inst="ret "},
|
{address="0x0001081c",func-name="main",offset="96",inst="ret "},
|
{address="0x00010820",func-name="main",offset="100",inst="restore "}]
|
{address="0x00010820",func-name="main",offset="100",inst="restore "}]
|
(gdb)
|
(gdb)
|
|
|
Disassemble 3 instructions from the start of `main':
|
Disassemble 3 instructions from the start of `main':
|
|
|
(gdb)
|
(gdb)
|
-data-disassemble -f basics.c -l 32 -n 3 -- 0
|
-data-disassemble -f basics.c -l 32 -n 3 -- 0
|
^done,asm_insns=[
|
^done,asm_insns=[
|
{address="0x000107bc",func-name="main",offset="0",
|
{address="0x000107bc",func-name="main",offset="0",
|
inst="save %sp, -112, %sp"},
|
inst="save %sp, -112, %sp"},
|
{address="0x000107c0",func-name="main",offset="4",
|
{address="0x000107c0",func-name="main",offset="4",
|
inst="mov 2, %o0"},
|
inst="mov 2, %o0"},
|
{address="0x000107c4",func-name="main",offset="8",
|
{address="0x000107c4",func-name="main",offset="8",
|
inst="sethi %hi(0x11800), %o2"}]
|
inst="sethi %hi(0x11800), %o2"}]
|
(gdb)
|
(gdb)
|
|
|
Disassemble 3 instructions from the start of `main' in mixed mode:
|
Disassemble 3 instructions from the start of `main' in mixed mode:
|
|
|
(gdb)
|
(gdb)
|
-data-disassemble -f basics.c -l 32 -n 3 -- 1
|
-data-disassemble -f basics.c -l 32 -n 3 -- 1
|
^done,asm_insns=[
|
^done,asm_insns=[
|
src_and_asm_line={line="31",
|
src_and_asm_line={line="31",
|
file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
|
file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
|
testsuite/gdb.mi/basics.c",line_asm_insn=[
|
testsuite/gdb.mi/basics.c",line_asm_insn=[
|
{address="0x000107bc",func-name="main",offset="0",
|
{address="0x000107bc",func-name="main",offset="0",
|
inst="save %sp, -112, %sp"}]},
|
inst="save %sp, -112, %sp"}]},
|
src_and_asm_line={line="32",
|
src_and_asm_line={line="32",
|
file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
|
file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
|
testsuite/gdb.mi/basics.c",line_asm_insn=[
|
testsuite/gdb.mi/basics.c",line_asm_insn=[
|
{address="0x000107c0",func-name="main",offset="4",
|
{address="0x000107c0",func-name="main",offset="4",
|
inst="mov 2, %o0"},
|
inst="mov 2, %o0"},
|
{address="0x000107c4",func-name="main",offset="8",
|
{address="0x000107c4",func-name="main",offset="8",
|
inst="sethi %hi(0x11800), %o2"}]}]
|
inst="sethi %hi(0x11800), %o2"}]}]
|
(gdb)
|
(gdb)
|
|
|
The `-data-evaluate-expression' Command
|
The `-data-evaluate-expression' Command
|
---------------------------------------
|
---------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-data-evaluate-expression EXPR
|
-data-evaluate-expression EXPR
|
|
|
Evaluate EXPR as an expression. The expression could contain an
|
Evaluate EXPR as an expression. The expression could contain an
|
inferior function call. The function call will execute synchronously.
|
inferior function call. The function call will execute synchronously.
|
If the expression contains spaces, it must be enclosed in double quotes.
|
If the expression contains spaces, it must be enclosed in double quotes.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB commands are `print', `output', and `call'. In
|
The corresponding GDB commands are `print', `output', and `call'. In
|
`gdbtk' only, there's a corresponding `gdb_eval' command.
|
`gdbtk' only, there's a corresponding `gdb_eval' command.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
In the following example, the numbers that precede the commands are the
|
In the following example, the numbers that precede the commands are the
|
"tokens" described in *Note GDB/MI Command Syntax: GDB/MI Command
|
"tokens" described in *Note GDB/MI Command Syntax: GDB/MI Command
|
Syntax. Notice how GDB/MI returns the same tokens in its output.
|
Syntax. Notice how GDB/MI returns the same tokens in its output.
|
|
|
211-data-evaluate-expression A
|
211-data-evaluate-expression A
|
211^done,value="1"
|
211^done,value="1"
|
(gdb)
|
(gdb)
|
311-data-evaluate-expression &A
|
311-data-evaluate-expression &A
|
311^done,value="0xefffeb7c"
|
311^done,value="0xefffeb7c"
|
(gdb)
|
(gdb)
|
411-data-evaluate-expression A+3
|
411-data-evaluate-expression A+3
|
411^done,value="4"
|
411^done,value="4"
|
(gdb)
|
(gdb)
|
511-data-evaluate-expression "A + 3"
|
511-data-evaluate-expression "A + 3"
|
511^done,value="4"
|
511^done,value="4"
|
(gdb)
|
(gdb)
|
|
|
The `-data-list-changed-registers' Command
|
The `-data-list-changed-registers' Command
|
------------------------------------------
|
------------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-data-list-changed-registers
|
-data-list-changed-registers
|
|
|
Display a list of the registers that have changed.
|
Display a list of the registers that have changed.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
GDB doesn't have a direct analog for this command; `gdbtk' has the
|
GDB doesn't have a direct analog for this command; `gdbtk' has the
|
corresponding command `gdb_changed_register_list'.
|
corresponding command `gdb_changed_register_list'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
On a PPC MBX board:
|
On a PPC MBX board:
|
|
|
(gdb)
|
(gdb)
|
-exec-continue
|
-exec-continue
|
^running
|
^running
|
|
|
(gdb)
|
(gdb)
|
*stopped,reason="breakpoint-hit",bkptno="1",frame={func="main",
|
*stopped,reason="breakpoint-hit",bkptno="1",frame={func="main",
|
args=[],file="try.c",fullname="/home/foo/bar/try.c",line="5"}
|
args=[],file="try.c",fullname="/home/foo/bar/try.c",line="5"}
|
(gdb)
|
(gdb)
|
-data-list-changed-registers
|
-data-list-changed-registers
|
^done,changed-registers=["0","1","2","4","5","6","7","8","9",
|
^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",
|
"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"]
|
"24","25","26","27","28","30","31","64","65","66","67","69"]
|
(gdb)
|
(gdb)
|
|
|
The `-data-list-register-names' Command
|
The `-data-list-register-names' Command
|
---------------------------------------
|
---------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-data-list-register-names [ ( REGNO )+ ]
|
-data-list-register-names [ ( REGNO )+ ]
|
|
|
Show a list of register names for the current target. If no
|
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.
|
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
|
If integer numbers are given as arguments, it will print a list of the
|
names of the registers corresponding to the arguments. To ensure
|
names of the registers corresponding to the arguments. To ensure
|
consistency between a register name and its number, the output list may
|
consistency between a register name and its number, the output list may
|
include empty register names.
|
include empty register names.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
GDB does not have a command which corresponds to
|
GDB does not have a command which corresponds to
|
`-data-list-register-names'. In `gdbtk' there is a corresponding
|
`-data-list-register-names'. In `gdbtk' there is a corresponding
|
command `gdb_regnames'.
|
command `gdb_regnames'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
For the PPC MBX board:
|
For the PPC MBX board:
|
(gdb)
|
(gdb)
|
-data-list-register-names
|
-data-list-register-names
|
^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
|
^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
|
"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
|
"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
|
"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
|
"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
|
"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
|
"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
|
"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
|
"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
|
"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
|
"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
|
"", "pc","ps","cr","lr","ctr","xer"]
|
"", "pc","ps","cr","lr","ctr","xer"]
|
(gdb)
|
(gdb)
|
-data-list-register-names 1 2 3
|
-data-list-register-names 1 2 3
|
^done,register-names=["r1","r2","r3"]
|
^done,register-names=["r1","r2","r3"]
|
(gdb)
|
(gdb)
|
|
|
The `-data-list-register-values' Command
|
The `-data-list-register-values' Command
|
----------------------------------------
|
----------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-data-list-register-values FMT [ ( REGNO )*]
|
-data-list-register-values FMT [ ( REGNO )*]
|
|
|
Display the registers' contents. FMT is the format according to
|
Display the registers' contents. FMT is the format according to
|
which the registers' contents are to be returned, followed by an
|
which the registers' contents are to be returned, followed by an
|
optional list of numbers specifying the registers to display. A
|
optional list of numbers specifying the registers to display. A
|
missing list of numbers indicates that the contents of all the
|
missing list of numbers indicates that the contents of all the
|
registers must be returned.
|
registers must be returned.
|
|
|
Allowed formats for FMT are:
|
Allowed formats for FMT are:
|
|
|
`x'
|
`x'
|
Hexadecimal
|
Hexadecimal
|
|
|
`o'
|
`o'
|
Octal
|
Octal
|
|
|
`t'
|
`t'
|
Binary
|
Binary
|
|
|
`d'
|
`d'
|
Decimal
|
Decimal
|
|
|
`r'
|
`r'
|
Raw
|
Raw
|
|
|
`N'
|
`N'
|
Natural
|
Natural
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB commands are `info reg', `info all-reg', and (in
|
The corresponding GDB commands are `info reg', `info all-reg', and (in
|
`gdbtk') `gdb_fetch_registers'.
|
`gdbtk') `gdb_fetch_registers'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
For a PPC MBX board (note: line breaks are for readability only, they
|
For a PPC MBX board (note: line breaks are for readability only, they
|
don't appear in the actual output):
|
don't appear in the actual output):
|
|
|
(gdb)
|
(gdb)
|
-data-list-register-values r 64 65
|
-data-list-register-values r 64 65
|
^done,register-values=[{number="64",value="0xfe00a300"},
|
^done,register-values=[{number="64",value="0xfe00a300"},
|
{number="65",value="0x00029002"}]
|
{number="65",value="0x00029002"}]
|
(gdb)
|
(gdb)
|
-data-list-register-values x
|
-data-list-register-values x
|
^done,register-values=[{number="0",value="0xfe0043c8"},
|
^done,register-values=[{number="0",value="0xfe0043c8"},
|
{number="1",value="0x3fff88"},{number="2",value="0xfffffffe"},
|
{number="1",value="0x3fff88"},{number="2",value="0xfffffffe"},
|
{number="3",value="0x0"},{number="4",value="0xa"},
|
{number="3",value="0x0"},{number="4",value="0xa"},
|
{number="5",value="0x3fff68"},{number="6",value="0x3fff58"},
|
{number="5",value="0x3fff68"},{number="6",value="0x3fff58"},
|
{number="7",value="0xfe011e98"},{number="8",value="0x2"},
|
{number="7",value="0xfe011e98"},{number="8",value="0x2"},
|
{number="9",value="0xfa202820"},{number="10",value="0xfa202808"},
|
{number="9",value="0xfa202820"},{number="10",value="0xfa202808"},
|
{number="11",value="0x1"},{number="12",value="0x0"},
|
{number="11",value="0x1"},{number="12",value="0x0"},
|
{number="13",value="0x4544"},{number="14",value="0xffdfffff"},
|
{number="13",value="0x4544"},{number="14",value="0xffdfffff"},
|
{number="15",value="0xffffffff"},{number="16",value="0xfffffeff"},
|
{number="15",value="0xffffffff"},{number="16",value="0xfffffeff"},
|
{number="17",value="0xefffffed"},{number="18",value="0xfffffffe"},
|
{number="17",value="0xefffffed"},{number="18",value="0xfffffffe"},
|
{number="19",value="0xffffffff"},{number="20",value="0xffffffff"},
|
{number="19",value="0xffffffff"},{number="20",value="0xffffffff"},
|
{number="21",value="0xffffffff"},{number="22",value="0xfffffff7"},
|
{number="21",value="0xffffffff"},{number="22",value="0xfffffff7"},
|
{number="23",value="0xffffffff"},{number="24",value="0xffffffff"},
|
{number="23",value="0xffffffff"},{number="24",value="0xffffffff"},
|
{number="25",value="0xffffffff"},{number="26",value="0xfffffffb"},
|
{number="25",value="0xffffffff"},{number="26",value="0xfffffffb"},
|
{number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"},
|
{number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"},
|
{number="29",value="0x0"},{number="30",value="0xfe010000"},
|
{number="29",value="0x0"},{number="30",value="0xfe010000"},
|
{number="31",value="0x0"},{number="32",value="0x0"},
|
{number="31",value="0x0"},{number="32",value="0x0"},
|
{number="33",value="0x0"},{number="34",value="0x0"},
|
{number="33",value="0x0"},{number="34",value="0x0"},
|
{number="35",value="0x0"},{number="36",value="0x0"},
|
{number="35",value="0x0"},{number="36",value="0x0"},
|
{number="37",value="0x0"},{number="38",value="0x0"},
|
{number="37",value="0x0"},{number="38",value="0x0"},
|
{number="39",value="0x0"},{number="40",value="0x0"},
|
{number="39",value="0x0"},{number="40",value="0x0"},
|
{number="41",value="0x0"},{number="42",value="0x0"},
|
{number="41",value="0x0"},{number="42",value="0x0"},
|
{number="43",value="0x0"},{number="44",value="0x0"},
|
{number="43",value="0x0"},{number="44",value="0x0"},
|
{number="45",value="0x0"},{number="46",value="0x0"},
|
{number="45",value="0x0"},{number="46",value="0x0"},
|
{number="47",value="0x0"},{number="48",value="0x0"},
|
{number="47",value="0x0"},{number="48",value="0x0"},
|
{number="49",value="0x0"},{number="50",value="0x0"},
|
{number="49",value="0x0"},{number="50",value="0x0"},
|
{number="51",value="0x0"},{number="52",value="0x0"},
|
{number="51",value="0x0"},{number="52",value="0x0"},
|
{number="53",value="0x0"},{number="54",value="0x0"},
|
{number="53",value="0x0"},{number="54",value="0x0"},
|
{number="55",value="0x0"},{number="56",value="0x0"},
|
{number="55",value="0x0"},{number="56",value="0x0"},
|
{number="57",value="0x0"},{number="58",value="0x0"},
|
{number="57",value="0x0"},{number="58",value="0x0"},
|
{number="59",value="0x0"},{number="60",value="0x0"},
|
{number="59",value="0x0"},{number="60",value="0x0"},
|
{number="61",value="0x0"},{number="62",value="0x0"},
|
{number="61",value="0x0"},{number="62",value="0x0"},
|
{number="63",value="0x0"},{number="64",value="0xfe00a300"},
|
{number="63",value="0x0"},{number="64",value="0xfe00a300"},
|
{number="65",value="0x29002"},{number="66",value="0x202f04b5"},
|
{number="65",value="0x29002"},{number="66",value="0x202f04b5"},
|
{number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"},
|
{number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"},
|
{number="69",value="0x20002b03"}]
|
{number="69",value="0x20002b03"}]
|
(gdb)
|
(gdb)
|
|
|
The `-data-read-memory' Command
|
The `-data-read-memory' Command
|
-------------------------------
|
-------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-data-read-memory [ -o BYTE-OFFSET ]
|
-data-read-memory [ -o BYTE-OFFSET ]
|
ADDRESS WORD-FORMAT WORD-SIZE
|
ADDRESS WORD-FORMAT WORD-SIZE
|
NR-ROWS NR-COLS [ ASCHAR ]
|
NR-ROWS NR-COLS [ ASCHAR ]
|
|
|
where:
|
where:
|
|
|
`ADDRESS'
|
`ADDRESS'
|
An expression specifying the address of the first memory word to be
|
An expression specifying the address of the first memory word to be
|
read. Complex expressions containing embedded white space should
|
read. Complex expressions containing embedded white space should
|
be quoted using the C convention.
|
be quoted using the C convention.
|
|
|
`WORD-FORMAT'
|
`WORD-FORMAT'
|
The format to be used to print the memory words. The notation is
|
The format to be used to print the memory words. The notation is
|
the same as for GDB's `print' command (*note Output Formats:
|
the same as for GDB's `print' command (*note Output Formats:
|
Output Formats.).
|
Output Formats.).
|
|
|
`WORD-SIZE'
|
`WORD-SIZE'
|
The size of each memory word in bytes.
|
The size of each memory word in bytes.
|
|
|
`NR-ROWS'
|
`NR-ROWS'
|
The number of rows in the output table.
|
The number of rows in the output table.
|
|
|
`NR-COLS'
|
`NR-COLS'
|
The number of columns in the output table.
|
The number of columns in the output table.
|
|
|
`ASCHAR'
|
`ASCHAR'
|
If present, indicates that each row should include an ASCII dump.
|
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
|
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
|
not a member of the printable ASCII character set (printable ASCII
|
characters are those whose code is between 32 and 126,
|
characters are those whose code is between 32 and 126,
|
inclusively).
|
inclusively).
|
|
|
`BYTE-OFFSET'
|
`BYTE-OFFSET'
|
An offset to add to the ADDRESS before fetching memory.
|
An offset to add to the ADDRESS before fetching memory.
|
|
|
This command displays memory contents as a table of NR-ROWS by
|
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 words, each word being WORD-SIZE bytes. In total, `NR-ROWS *
|
NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes').
|
NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes').
|
Should less than the requested number of bytes be returned by the
|
Should less than the requested number of bytes be returned by the
|
target, the missing words are identified using `N/A'. The number of
|
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
|
bytes read from the target is returned in `nr-bytes' and the starting
|
address used to read memory in `addr'.
|
address used to read memory in `addr'.
|
|
|
The address of the next/previous row or page is available in
|
The address of the next/previous row or page is available in
|
`next-row' and `prev-row', `next-page' and `prev-page'.
|
`next-row' and `prev-row', `next-page' and `prev-page'.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `x'. `gdbtk' has `gdb_get_mem' memory
|
The corresponding GDB command is `x'. `gdbtk' has `gdb_get_mem' memory
|
read command.
|
read command.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
Read six bytes of memory starting at `bytes+6' but then offset by `-6'
|
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.
|
bytes. Format as three rows of two columns. One byte per word.
|
Display each word in hex.
|
Display each word in hex.
|
|
|
(gdb)
|
(gdb)
|
9-data-read-memory -o -6 -- bytes+6 x 1 3 2
|
9-data-read-memory -o -6 -- bytes+6 x 1 3 2
|
9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
|
9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
|
next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
|
next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
|
prev-page="0x0000138a",memory=[
|
prev-page="0x0000138a",memory=[
|
{addr="0x00001390",data=["0x00","0x01"]},
|
{addr="0x00001390",data=["0x00","0x01"]},
|
{addr="0x00001392",data=["0x02","0x03"]},
|
{addr="0x00001392",data=["0x02","0x03"]},
|
{addr="0x00001394",data=["0x04","0x05"]}]
|
{addr="0x00001394",data=["0x04","0x05"]}]
|
(gdb)
|
(gdb)
|
|
|
Read two bytes of memory starting at address `shorts + 64' and
|
Read two bytes of memory starting at address `shorts + 64' and
|
display as a single word formatted in decimal.
|
display as a single word formatted in decimal.
|
|
|
(gdb)
|
(gdb)
|
5-data-read-memory shorts+64 d 2 1 1
|
5-data-read-memory shorts+64 d 2 1 1
|
5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
|
5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
|
next-row="0x00001512",prev-row="0x0000150e",
|
next-row="0x00001512",prev-row="0x0000150e",
|
next-page="0x00001512",prev-page="0x0000150e",memory=[
|
next-page="0x00001512",prev-page="0x0000150e",memory=[
|
{addr="0x00001510",data=["128"]}]
|
{addr="0x00001510",data=["128"]}]
|
(gdb)
|
(gdb)
|
|
|
Read thirty two bytes of memory starting at `bytes+16' and format as
|
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
|
eight rows of four columns. Include a string encoding with `x' used as
|
the non-printable character.
|
the non-printable character.
|
|
|
(gdb)
|
(gdb)
|
4-data-read-memory bytes+16 x 1 8 4 x
|
4-data-read-memory bytes+16 x 1 8 4 x
|
4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
|
4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
|
next-row="0x000013c0",prev-row="0x0000139c",
|
next-row="0x000013c0",prev-row="0x0000139c",
|
next-page="0x000013c0",prev-page="0x00001380",memory=[
|
next-page="0x000013c0",prev-page="0x00001380",memory=[
|
{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"},
|
{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"},
|
{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"},
|
{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"},
|
{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"},
|
{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"},
|
{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"},
|
{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"},
|
{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"},
|
{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"},
|
{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"},
|
{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"},
|
{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"},
|
{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"},
|
{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}]
|
{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}]
|
(gdb)
|
(gdb)
|
|
|
|
|
File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI
|
|
|
24.14 GDB/MI Tracepoint Commands
|
24.14 GDB/MI Tracepoint Commands
|
================================
|
================================
|
|
|
The tracepoint commands are not yet implemented.
|
The tracepoint commands are not yet implemented.
|
|
|
|
|
File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI
|
|
|
24.15 GDB/MI Symbol Query Commands
|
24.15 GDB/MI Symbol Query Commands
|
==================================
|
==================================
|
|
|
The `-symbol-info-address' Command
|
The `-symbol-info-address' Command
|
----------------------------------
|
----------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-symbol-info-address SYMBOL
|
-symbol-info-address SYMBOL
|
|
|
Describe where SYMBOL is stored.
|
Describe where SYMBOL is stored.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `info address'.
|
The corresponding GDB command is `info address'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-symbol-info-file' Command
|
The `-symbol-info-file' Command
|
-------------------------------
|
-------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-symbol-info-file
|
-symbol-info-file
|
|
|
Show the file for the symbol.
|
Show the file for the symbol.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
There's no equivalent GDB command. `gdbtk' has `gdb_find_file'.
|
There's no equivalent GDB command. `gdbtk' has `gdb_find_file'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-symbol-info-function' Command
|
The `-symbol-info-function' Command
|
-----------------------------------
|
-----------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-symbol-info-function
|
-symbol-info-function
|
|
|
Show which function the symbol lives in.
|
Show which function the symbol lives in.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
`gdb_get_function' in `gdbtk'.
|
`gdb_get_function' in `gdbtk'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-symbol-info-line' Command
|
The `-symbol-info-line' Command
|
-------------------------------
|
-------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-symbol-info-line
|
-symbol-info-line
|
|
|
Show the core addresses of the code for a source line.
|
Show the core addresses of the code for a source line.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `info line'. `gdbtk' has the
|
The corresponding GDB command is `info line'. `gdbtk' has the
|
`gdb_get_line' and `gdb_get_file' commands.
|
`gdb_get_line' and `gdb_get_file' commands.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-symbol-info-symbol' Command
|
The `-symbol-info-symbol' Command
|
---------------------------------
|
---------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-symbol-info-symbol ADDR
|
-symbol-info-symbol ADDR
|
|
|
Describe what symbol is at location ADDR.
|
Describe what symbol is at location ADDR.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `info symbol'.
|
The corresponding GDB command is `info symbol'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-symbol-list-functions' Command
|
The `-symbol-list-functions' Command
|
------------------------------------
|
------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-symbol-list-functions
|
-symbol-list-functions
|
|
|
List the functions in the executable.
|
List the functions in the executable.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
`info functions' in GDB, `gdb_listfunc' and `gdb_search' in `gdbtk'.
|
`info functions' in GDB, `gdb_listfunc' and `gdb_search' in `gdbtk'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-symbol-list-lines' Command
|
The `-symbol-list-lines' Command
|
--------------------------------
|
--------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-symbol-list-lines FILENAME
|
-symbol-list-lines FILENAME
|
|
|
Print the list of lines that contain code and their associated
|
Print the list of lines that contain code and their associated
|
program addresses for the given source filename. The entries are
|
program addresses for the given source filename. The entries are
|
sorted in ascending PC order.
|
sorted in ascending PC order.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
There is no corresponding GDB command.
|
There is no corresponding GDB command.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-symbol-list-lines basics.c
|
-symbol-list-lines basics.c
|
^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}]
|
^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}]
|
(gdb)
|
(gdb)
|
|
|
The `-symbol-list-types' Command
|
The `-symbol-list-types' Command
|
--------------------------------
|
--------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-symbol-list-types
|
-symbol-list-types
|
|
|
List all the type names.
|
List all the type names.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding commands are `info types' in GDB, `gdb_search' in
|
The corresponding commands are `info types' in GDB, `gdb_search' in
|
`gdbtk'.
|
`gdbtk'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-symbol-list-variables' Command
|
The `-symbol-list-variables' Command
|
------------------------------------
|
------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-symbol-list-variables
|
-symbol-list-variables
|
|
|
List all the global and static variable names.
|
List all the global and static variable names.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
`info variables' in GDB, `gdb_search' in `gdbtk'.
|
`info variables' in GDB, `gdb_search' in `gdbtk'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-symbol-locate' Command
|
The `-symbol-locate' Command
|
----------------------------
|
----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-symbol-locate
|
-symbol-locate
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
`gdb_loc' in `gdbtk'.
|
`gdb_loc' in `gdbtk'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-symbol-type' Command
|
The `-symbol-type' Command
|
--------------------------
|
--------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-symbol-type VARIABLE
|
-symbol-type VARIABLE
|
|
|
Show type of VARIABLE.
|
Show type of VARIABLE.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `ptype', `gdbtk' has
|
The corresponding GDB command is `ptype', `gdbtk' has
|
`gdb_obj_variable'.
|
`gdb_obj_variable'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
|
|
File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI
|
|
|
24.16 GDB/MI File Commands
|
24.16 GDB/MI File Commands
|
==========================
|
==========================
|
|
|
This section describes the GDB/MI commands to specify executable file
|
This section describes the GDB/MI commands to specify executable file
|
names and to read in and obtain symbol table information.
|
names and to read in and obtain symbol table information.
|
|
|
The `-file-exec-and-symbols' Command
|
The `-file-exec-and-symbols' Command
|
------------------------------------
|
------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-file-exec-and-symbols FILE
|
-file-exec-and-symbols FILE
|
|
|
Specify the executable file to be debugged. This file is the one
|
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
|
from which the symbol table is also read. If no file is specified, the
|
command clears the executable and symbol information. If breakpoints
|
command clears the executable and symbol information. If breakpoints
|
are set when using this command with no arguments, GDB will produce
|
are set when using this command with no arguments, GDB will produce
|
error messages. Otherwise, no output is produced, except a completion
|
error messages. Otherwise, no output is produced, except a completion
|
notification.
|
notification.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `file'.
|
The corresponding GDB command is `file'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
|
-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
The `-file-exec-file' Command
|
The `-file-exec-file' Command
|
-----------------------------
|
-----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-file-exec-file FILE
|
-file-exec-file FILE
|
|
|
Specify the executable file to be debugged. Unlike
|
Specify the executable file to be debugged. Unlike
|
`-file-exec-and-symbols', the symbol table is _not_ read from this
|
`-file-exec-and-symbols', the symbol table is _not_ read from this
|
file. If used without argument, GDB clears the information about the
|
file. If used without argument, GDB clears the information about the
|
executable file. No output is produced, except a completion
|
executable file. No output is produced, except a completion
|
notification.
|
notification.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `exec-file'.
|
The corresponding GDB command is `exec-file'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
|
-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
The `-file-list-exec-sections' Command
|
The `-file-list-exec-sections' Command
|
--------------------------------------
|
--------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-file-list-exec-sections
|
-file-list-exec-sections
|
|
|
List the sections of the current executable file.
|
List the sections of the current executable file.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The GDB command `info file' shows, among the rest, the same information
|
The GDB command `info file' shows, among the rest, the same information
|
as this command. `gdbtk' has a corresponding command `gdb_load_info'.
|
as this command. `gdbtk' has a corresponding command `gdb_load_info'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-file-list-exec-source-file' Command
|
The `-file-list-exec-source-file' Command
|
-----------------------------------------
|
-----------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-file-list-exec-source-file
|
-file-list-exec-source-file
|
|
|
List the line number, the current source file, and the absolute path
|
List the line number, the current source file, and the absolute path
|
to the current source file for the current executable. The macro
|
to the current source file for the current executable. The macro
|
information field has a value of `1' or `0' depending on whether or not
|
information field has a value of `1' or `0' depending on whether or not
|
the file includes preprocessor macro information.
|
the file includes preprocessor macro information.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The GDB equivalent is `info source'
|
The GDB equivalent is `info source'
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
123-file-list-exec-source-file
|
123-file-list-exec-source-file
|
123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
|
123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
|
(gdb)
|
(gdb)
|
|
|
The `-file-list-exec-source-files' Command
|
The `-file-list-exec-source-files' Command
|
------------------------------------------
|
------------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-file-list-exec-source-files
|
-file-list-exec-source-files
|
|
|
List the source files for the current executable.
|
List the source files for the current executable.
|
|
|
It will always output the filename, but only when GDB can find the
|
It will always output the filename, but only when GDB can find the
|
absolute file name of a source file, will it output the fullname.
|
absolute file name of a source file, will it output the fullname.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The GDB equivalent is `info sources'. `gdbtk' has an analogous command
|
The GDB equivalent is `info sources'. `gdbtk' has an analogous command
|
`gdb_listfiles'.
|
`gdb_listfiles'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-file-list-exec-source-files
|
-file-list-exec-source-files
|
^done,files=[
|
^done,files=[
|
{file=foo.c,fullname=/home/foo.c},
|
{file=foo.c,fullname=/home/foo.c},
|
{file=/home/bar.c,fullname=/home/bar.c},
|
{file=/home/bar.c,fullname=/home/bar.c},
|
{file=gdb_could_not_find_fullpath.c}]
|
{file=gdb_could_not_find_fullpath.c}]
|
(gdb)
|
(gdb)
|
|
|
The `-file-list-shared-libraries' Command
|
The `-file-list-shared-libraries' Command
|
-----------------------------------------
|
-----------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-file-list-shared-libraries
|
-file-list-shared-libraries
|
|
|
List the shared libraries in the program.
|
List the shared libraries in the program.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `info shared'.
|
The corresponding GDB command is `info shared'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-file-list-symbol-files' Command
|
The `-file-list-symbol-files' Command
|
-------------------------------------
|
-------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-file-list-symbol-files
|
-file-list-symbol-files
|
|
|
List symbol files.
|
List symbol files.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `info file' (part of it).
|
The corresponding GDB command is `info file' (part of it).
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-file-symbol-file' Command
|
The `-file-symbol-file' Command
|
-------------------------------
|
-------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-file-symbol-file FILE
|
-file-symbol-file FILE
|
|
|
Read symbol table info from the specified FILE argument. When used
|
Read symbol table info from the specified FILE argument. When used
|
without arguments, clears GDB's symbol table info. No output is
|
without arguments, clears GDB's symbol table info. No output is
|
produced, except for a completion notification.
|
produced, except for a completion notification.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `symbol-file'.
|
The corresponding GDB command is `symbol-file'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
|
-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
|
|
File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI
|
|
|
24.17 GDB/MI Target Manipulation Commands
|
24.17 GDB/MI Target Manipulation Commands
|
=========================================
|
=========================================
|
|
|
The `-target-attach' Command
|
The `-target-attach' Command
|
----------------------------
|
----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-attach PID | FILE
|
-target-attach PID | FILE
|
|
|
Attach to a process PID or a file FILE outside of GDB.
|
Attach to a process PID or a file FILE outside of GDB.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `attach'.
|
The corresponding GDB command is `attach'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-target-compare-sections' Command
|
The `-target-compare-sections' Command
|
--------------------------------------
|
--------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-compare-sections [ SECTION ]
|
-target-compare-sections [ SECTION ]
|
|
|
Compare data of section SECTION on target to the exec file. Without
|
Compare data of section SECTION on target to the exec file. Without
|
the argument, all sections are compared.
|
the argument, all sections are compared.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The GDB equivalent is `compare-sections'.
|
The GDB equivalent is `compare-sections'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-target-detach' Command
|
The `-target-detach' Command
|
----------------------------
|
----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-detach
|
-target-detach
|
|
|
Detach from the remote target which normally resumes its execution.
|
Detach from the remote target which normally resumes its execution.
|
There's no output.
|
There's no output.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `detach'.
|
The corresponding GDB command is `detach'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-target-detach
|
-target-detach
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
The `-target-disconnect' Command
|
The `-target-disconnect' Command
|
--------------------------------
|
--------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-disconnect
|
-target-disconnect
|
|
|
Disconnect from the remote target. There's no output and the target
|
Disconnect from the remote target. There's no output and the target
|
is generally not resumed.
|
is generally not resumed.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `disconnect'.
|
The corresponding GDB command is `disconnect'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-target-disconnect
|
-target-disconnect
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
The `-target-download' Command
|
The `-target-download' Command
|
------------------------------
|
------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-download
|
-target-download
|
|
|
Loads the executable onto the remote target. It prints out an
|
Loads the executable onto the remote target. It prints out an
|
update message every half second, which includes the fields:
|
update message every half second, which includes the fields:
|
|
|
`section'
|
`section'
|
The name of the section.
|
The name of the section.
|
|
|
`section-sent'
|
`section-sent'
|
The size of what has been sent so far for that section.
|
The size of what has been sent so far for that section.
|
|
|
`section-size'
|
`section-size'
|
The size of the section.
|
The size of the section.
|
|
|
`total-sent'
|
`total-sent'
|
The total size of what was sent so far (the current and the
|
The total size of what was sent so far (the current and the
|
previous sections).
|
previous sections).
|
|
|
`total-size'
|
`total-size'
|
The size of the overall executable to download.
|
The size of the overall executable to download.
|
|
|
Each message is sent as status record (*note GDB/MI Output Syntax:
|
Each message is sent as status record (*note GDB/MI Output Syntax:
|
GDB/MI Output Syntax.).
|
GDB/MI Output Syntax.).
|
|
|
In addition, it prints the name and size of the sections, as they are
|
In addition, it prints the name and size of the sections, as they are
|
downloaded. These messages include the following fields:
|
downloaded. These messages include the following fields:
|
|
|
`section'
|
`section'
|
The name of the section.
|
The name of the section.
|
|
|
`section-size'
|
`section-size'
|
The size of the section.
|
The size of the section.
|
|
|
`total-size'
|
`total-size'
|
The size of the overall executable to download.
|
The size of the overall executable to download.
|
|
|
At the end, a summary is printed.
|
At the end, a summary is printed.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `load'.
|
The corresponding GDB command is `load'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
Note: each status message appears on a single line. Here the messages
|
Note: each status message appears on a single line. Here the messages
|
have been broken down so that they can fit onto a page.
|
have been broken down so that they can fit onto a page.
|
|
|
(gdb)
|
(gdb)
|
-target-download
|
-target-download
|
+download,{section=".text",section-size="6668",total-size="9880"}
|
+download,{section=".text",section-size="6668",total-size="9880"}
|
+download,{section=".text",section-sent="512",section-size="6668",
|
+download,{section=".text",section-sent="512",section-size="6668",
|
total-sent="512",total-size="9880"}
|
total-sent="512",total-size="9880"}
|
+download,{section=".text",section-sent="1024",section-size="6668",
|
+download,{section=".text",section-sent="1024",section-size="6668",
|
total-sent="1024",total-size="9880"}
|
total-sent="1024",total-size="9880"}
|
+download,{section=".text",section-sent="1536",section-size="6668",
|
+download,{section=".text",section-sent="1536",section-size="6668",
|
total-sent="1536",total-size="9880"}
|
total-sent="1536",total-size="9880"}
|
+download,{section=".text",section-sent="2048",section-size="6668",
|
+download,{section=".text",section-sent="2048",section-size="6668",
|
total-sent="2048",total-size="9880"}
|
total-sent="2048",total-size="9880"}
|
+download,{section=".text",section-sent="2560",section-size="6668",
|
+download,{section=".text",section-sent="2560",section-size="6668",
|
total-sent="2560",total-size="9880"}
|
total-sent="2560",total-size="9880"}
|
+download,{section=".text",section-sent="3072",section-size="6668",
|
+download,{section=".text",section-sent="3072",section-size="6668",
|
total-sent="3072",total-size="9880"}
|
total-sent="3072",total-size="9880"}
|
+download,{section=".text",section-sent="3584",section-size="6668",
|
+download,{section=".text",section-sent="3584",section-size="6668",
|
total-sent="3584",total-size="9880"}
|
total-sent="3584",total-size="9880"}
|
+download,{section=".text",section-sent="4096",section-size="6668",
|
+download,{section=".text",section-sent="4096",section-size="6668",
|
total-sent="4096",total-size="9880"}
|
total-sent="4096",total-size="9880"}
|
+download,{section=".text",section-sent="4608",section-size="6668",
|
+download,{section=".text",section-sent="4608",section-size="6668",
|
total-sent="4608",total-size="9880"}
|
total-sent="4608",total-size="9880"}
|
+download,{section=".text",section-sent="5120",section-size="6668",
|
+download,{section=".text",section-sent="5120",section-size="6668",
|
total-sent="5120",total-size="9880"}
|
total-sent="5120",total-size="9880"}
|
+download,{section=".text",section-sent="5632",section-size="6668",
|
+download,{section=".text",section-sent="5632",section-size="6668",
|
total-sent="5632",total-size="9880"}
|
total-sent="5632",total-size="9880"}
|
+download,{section=".text",section-sent="6144",section-size="6668",
|
+download,{section=".text",section-sent="6144",section-size="6668",
|
total-sent="6144",total-size="9880"}
|
total-sent="6144",total-size="9880"}
|
+download,{section=".text",section-sent="6656",section-size="6668",
|
+download,{section=".text",section-sent="6656",section-size="6668",
|
total-sent="6656",total-size="9880"}
|
total-sent="6656",total-size="9880"}
|
+download,{section=".init",section-size="28",total-size="9880"}
|
+download,{section=".init",section-size="28",total-size="9880"}
|
+download,{section=".fini",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-size="3156",total-size="9880"}
|
+download,{section=".data",section-sent="512",section-size="3156",
|
+download,{section=".data",section-sent="512",section-size="3156",
|
total-sent="7236",total-size="9880"}
|
total-sent="7236",total-size="9880"}
|
+download,{section=".data",section-sent="1024",section-size="3156",
|
+download,{section=".data",section-sent="1024",section-size="3156",
|
total-sent="7748",total-size="9880"}
|
total-sent="7748",total-size="9880"}
|
+download,{section=".data",section-sent="1536",section-size="3156",
|
+download,{section=".data",section-sent="1536",section-size="3156",
|
total-sent="8260",total-size="9880"}
|
total-sent="8260",total-size="9880"}
|
+download,{section=".data",section-sent="2048",section-size="3156",
|
+download,{section=".data",section-sent="2048",section-size="3156",
|
total-sent="8772",total-size="9880"}
|
total-sent="8772",total-size="9880"}
|
+download,{section=".data",section-sent="2560",section-size="3156",
|
+download,{section=".data",section-sent="2560",section-size="3156",
|
total-sent="9284",total-size="9880"}
|
total-sent="9284",total-size="9880"}
|
+download,{section=".data",section-sent="3072",section-size="3156",
|
+download,{section=".data",section-sent="3072",section-size="3156",
|
total-sent="9796",total-size="9880"}
|
total-sent="9796",total-size="9880"}
|
^done,address="0x10004",load-size="9880",transfer-rate="6586",
|
^done,address="0x10004",load-size="9880",transfer-rate="6586",
|
write-rate="429"
|
write-rate="429"
|
(gdb)
|
(gdb)
|
|
|
The `-target-exec-status' Command
|
The `-target-exec-status' Command
|
---------------------------------
|
---------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-exec-status
|
-target-exec-status
|
|
|
Provide information on the state of the target (whether it is
|
Provide information on the state of the target (whether it is
|
running or not, for instance).
|
running or not, for instance).
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
There's no equivalent GDB command.
|
There's no equivalent GDB command.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-target-list-available-targets' Command
|
The `-target-list-available-targets' Command
|
--------------------------------------------
|
--------------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-list-available-targets
|
-target-list-available-targets
|
|
|
List the possible targets to connect to.
|
List the possible targets to connect to.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `help target'.
|
The corresponding GDB command is `help target'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-target-list-current-targets' Command
|
The `-target-list-current-targets' Command
|
------------------------------------------
|
------------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-list-current-targets
|
-target-list-current-targets
|
|
|
Describe the current target.
|
Describe the current target.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding information is printed by `info file' (among other
|
The corresponding information is printed by `info file' (among other
|
things).
|
things).
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-target-list-parameters' Command
|
The `-target-list-parameters' Command
|
-------------------------------------
|
-------------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-list-parameters
|
-target-list-parameters
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
No equivalent.
|
No equivalent.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-target-select' Command
|
The `-target-select' Command
|
----------------------------
|
----------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-select TYPE PARAMETERS ...
|
-target-select TYPE PARAMETERS ...
|
|
|
Connect GDB to the remote target. This command takes two args:
|
Connect GDB to the remote target. This command takes two args:
|
|
|
`TYPE'
|
`TYPE'
|
The type of target, for instance `async', `remote', etc.
|
The type of target, for instance `async', `remote', etc.
|
|
|
`PARAMETERS'
|
`PARAMETERS'
|
Device names, host names and the like. *Note Commands for
|
Device names, host names and the like. *Note Commands for
|
Managing Targets: Target Commands, for more details.
|
Managing Targets: Target Commands, for more details.
|
|
|
The output is a connection notification, followed by the address at
|
The output is a connection notification, followed by the address at
|
which the target program is, in the following form:
|
which the target program is, in the following form:
|
|
|
^connected,addr="ADDRESS",func="FUNCTION NAME",
|
^connected,addr="ADDRESS",func="FUNCTION NAME",
|
args=[ARG LIST]
|
args=[ARG LIST]
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `target'.
|
The corresponding GDB command is `target'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-target-select async /dev/ttya
|
-target-select async /dev/ttya
|
^connected,addr="0xfe00a300",func="??",args=[]
|
^connected,addr="0xfe00a300",func="??",args=[]
|
(gdb)
|
(gdb)
|
|
|
|
|
File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI
|
|
|
24.18 GDB/MI File Transfer Commands
|
24.18 GDB/MI File Transfer Commands
|
===================================
|
===================================
|
|
|
The `-target-file-put' Command
|
The `-target-file-put' Command
|
------------------------------
|
------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-file-put HOSTFILE TARGETFILE
|
-target-file-put HOSTFILE TARGETFILE
|
|
|
Copy file HOSTFILE from the host system (the machine running GDB) to
|
Copy file HOSTFILE from the host system (the machine running GDB) to
|
TARGETFILE on the target system.
|
TARGETFILE on the target system.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `remote put'.
|
The corresponding GDB command is `remote put'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-target-file-put localfile remotefile
|
-target-file-put localfile remotefile
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
The `-target-file-put' Command
|
The `-target-file-put' Command
|
------------------------------
|
------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-file-get TARGETFILE HOSTFILE
|
-target-file-get TARGETFILE HOSTFILE
|
|
|
Copy file TARGETFILE from the target system to HOSTFILE on the host
|
Copy file TARGETFILE from the target system to HOSTFILE on the host
|
system.
|
system.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `remote get'.
|
The corresponding GDB command is `remote get'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-target-file-get remotefile localfile
|
-target-file-get remotefile localfile
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
The `-target-file-delete' Command
|
The `-target-file-delete' Command
|
---------------------------------
|
---------------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-target-file-delete TARGETFILE
|
-target-file-delete TARGETFILE
|
|
|
Delete TARGETFILE from the target system.
|
Delete TARGETFILE from the target system.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `remote delete'.
|
The corresponding GDB command is `remote delete'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-target-file-delete remotefile
|
-target-file-delete remotefile
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
|
|
File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI
|
|
|
24.19 Miscellaneous GDB/MI Commands
|
24.19 Miscellaneous GDB/MI Commands
|
===================================
|
===================================
|
|
|
The `-gdb-exit' Command
|
The `-gdb-exit' Command
|
-----------------------
|
-----------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-gdb-exit
|
-gdb-exit
|
|
|
Exit GDB immediately.
|
Exit GDB immediately.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
Approximately corresponds to `quit'.
|
Approximately corresponds to `quit'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-gdb-exit
|
-gdb-exit
|
^exit
|
^exit
|
|
|
The `-exec-abort' Command
|
The `-exec-abort' Command
|
-------------------------
|
-------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-exec-abort
|
-exec-abort
|
|
|
Kill the inferior running program.
|
Kill the inferior running program.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `kill'.
|
The corresponding GDB command is `kill'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
N.A.
|
N.A.
|
|
|
The `-gdb-set' Command
|
The `-gdb-set' Command
|
----------------------
|
----------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-gdb-set
|
-gdb-set
|
|
|
Set an internal GDB variable.
|
Set an internal GDB variable.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `set'.
|
The corresponding GDB command is `set'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-gdb-set $foo=3
|
-gdb-set $foo=3
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
The `-gdb-show' Command
|
The `-gdb-show' Command
|
-----------------------
|
-----------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-gdb-show
|
-gdb-show
|
|
|
Show the current value of a GDB variable.
|
Show the current value of a GDB variable.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB command is `show'.
|
The corresponding GDB command is `show'.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-gdb-show annotate
|
-gdb-show annotate
|
^done,value="0"
|
^done,value="0"
|
(gdb)
|
(gdb)
|
|
|
The `-gdb-version' Command
|
The `-gdb-version' Command
|
--------------------------
|
--------------------------
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-gdb-version
|
-gdb-version
|
|
|
Show version information for GDB. Used mostly in testing.
|
Show version information for GDB. Used mostly in testing.
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The GDB equivalent is `show version'. GDB by default shows this
|
The GDB equivalent is `show version'. GDB by default shows this
|
information when you start an interactive session.
|
information when you start an interactive session.
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
(gdb)
|
(gdb)
|
-gdb-version
|
-gdb-version
|
~GNU gdb 5.2.1
|
~GNU gdb 5.2.1
|
~Copyright 2000 Free Software Foundation, Inc.
|
~Copyright 2000 Free Software Foundation, Inc.
|
~GDB is free software, covered by the GNU General Public License, and
|
~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
|
~you are welcome to change it and/or distribute copies of it under
|
~ certain conditions.
|
~ certain conditions.
|
~Type "show copying" to see the conditions.
|
~Type "show copying" to see the conditions.
|
~There is absolutely no warranty for GDB. Type "show warranty" for
|
~There is absolutely no warranty for GDB. Type "show warranty" for
|
~ details.
|
~ details.
|
~This GDB was configured as
|
~This GDB was configured as
|
"--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
|
"--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
The `-list-features' Command
|
The `-list-features' Command
|
----------------------------
|
----------------------------
|
|
|
Returns a list of particular features of the MI protocol that this
|
Returns a list of particular features of the MI protocol that this
|
version of gdb implements. A feature can be a command, or a new field
|
version of gdb implements. A feature can be a command, or a new field
|
in an output of some command, or even an important bugfix. While a
|
in an output of some command, or even an important bugfix. While a
|
frontend can sometimes detect presence of a feature at runtime, it is
|
frontend can sometimes detect presence of a feature at runtime, it is
|
easier to perform detection at debugger startup.
|
easier to perform detection at debugger startup.
|
|
|
The command returns a list of strings, with each string naming an
|
The command returns a list of strings, with each string naming an
|
available feature. Each returned string is just a name, it does not
|
available feature. Each returned string is just a name, it does not
|
have any internal structure. The list of possible feature names is
|
have any internal structure. The list of possible feature names is
|
given below.
|
given below.
|
|
|
Example output:
|
Example output:
|
|
|
(gdb) -list-features
|
(gdb) -list-features
|
^done,result=["feature1","feature2"]
|
^done,result=["feature1","feature2"]
|
|
|
The current list of features is:
|
The current list of features is:
|
|
|
- `frozen-varobjs'--indicates presence of the `-var-set-frozen'
|
- `frozen-varobjs'--indicates presence of the `-var-set-frozen'
|
command, as well as possible presense of the `frozen' field in the
|
command, as well as possible presense of the `frozen' field in the
|
output of `-varobj-create'.
|
output of `-varobj-create'.
|
|
|
- `pending-breakpoints'--indicates presence of the `-f' option to
|
- `pending-breakpoints'--indicates presence of the `-f' option to
|
the `-break-insert' command.
|
the `-break-insert' command.
|
|
|
|
|
The `-interpreter-exec' Command
|
The `-interpreter-exec' Command
|
-------------------------------
|
-------------------------------
|
|
|
Synopsis
|
Synopsis
|
--------
|
--------
|
|
|
-interpreter-exec INTERPRETER COMMAND
|
-interpreter-exec INTERPRETER COMMAND
|
|
|
Execute the specified COMMAND in the given INTERPRETER.
|
Execute the specified COMMAND in the given INTERPRETER.
|
|
|
GDB Command
|
GDB Command
|
-----------
|
-----------
|
|
|
The corresponding GDB command is `interpreter-exec'.
|
The corresponding GDB command is `interpreter-exec'.
|
|
|
Example
|
Example
|
-------
|
-------
|
|
|
(gdb)
|
(gdb)
|
-interpreter-exec console "break main"
|
-interpreter-exec console "break main"
|
&"During symbol reading, couldn't parse type; debugger out of date?.\n"
|
&"During symbol reading, couldn't parse type; debugger out of date?.\n"
|
&"During symbol reading, bad structure-type format.\n"
|
&"During symbol reading, bad structure-type format.\n"
|
~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
|
~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
The `-inferior-tty-set' Command
|
The `-inferior-tty-set' Command
|
-------------------------------
|
-------------------------------
|
|
|
Synopsis
|
Synopsis
|
--------
|
--------
|
|
|
-inferior-tty-set /dev/pts/1
|
-inferior-tty-set /dev/pts/1
|
|
|
Set terminal for future runs of the program being debugged.
|
Set terminal for future runs of the program being debugged.
|
|
|
GDB Command
|
GDB Command
|
-----------
|
-----------
|
|
|
The corresponding GDB command is `set inferior-tty' /dev/pts/1.
|
The corresponding GDB command is `set inferior-tty' /dev/pts/1.
|
|
|
Example
|
Example
|
-------
|
-------
|
|
|
(gdb)
|
(gdb)
|
-inferior-tty-set /dev/pts/1
|
-inferior-tty-set /dev/pts/1
|
^done
|
^done
|
(gdb)
|
(gdb)
|
|
|
The `-inferior-tty-show' Command
|
The `-inferior-tty-show' Command
|
--------------------------------
|
--------------------------------
|
|
|
Synopsis
|
Synopsis
|
--------
|
--------
|
|
|
-inferior-tty-show
|
-inferior-tty-show
|
|
|
Show terminal for future runs of program being debugged.
|
Show terminal for future runs of program being debugged.
|
|
|
GDB Command
|
GDB Command
|
-----------
|
-----------
|
|
|
The corresponding GDB command is `show inferior-tty'.
|
The corresponding GDB command is `show inferior-tty'.
|
|
|
Example
|
Example
|
-------
|
-------
|
|
|
(gdb)
|
(gdb)
|
-inferior-tty-set /dev/pts/1
|
-inferior-tty-set /dev/pts/1
|
^done
|
^done
|
(gdb)
|
(gdb)
|
-inferior-tty-show
|
-inferior-tty-show
|
^done,inferior_tty_terminal="/dev/pts/1"
|
^done,inferior_tty_terminal="/dev/pts/1"
|
(gdb)
|
(gdb)
|
|
|
The `-enable-timings' Command
|
The `-enable-timings' Command
|
-----------------------------
|
-----------------------------
|
|
|
Synopsis
|
Synopsis
|
--------
|
--------
|
|
|
-enable-timings [yes | no]
|
-enable-timings [yes | no]
|
|
|
Toggle the printing of the wallclock, user and system times for an MI
|
Toggle the printing of the wallclock, user and system times for an MI
|
command as a field in its output. This command is to help frontend
|
command as a field in its output. This command is to help frontend
|
developers optimize the performance of their code. No argument is
|
developers optimize the performance of their code. No argument is
|
equivalent to `yes'.
|
equivalent to `yes'.
|
|
|
GDB Command
|
GDB Command
|
-----------
|
-----------
|
|
|
No equivalent.
|
No equivalent.
|
|
|
Example
|
Example
|
-------
|
-------
|
|
|
(gdb)
|
(gdb)
|
-enable-timings
|
-enable-timings
|
^done
|
^done
|
(gdb)
|
(gdb)
|
-break-insert main
|
-break-insert main
|
^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
addr="0x080484ed",func="main",file="myprog.c",
|
addr="0x080484ed",func="main",file="myprog.c",
|
fullname="/home/nickrob/myprog.c",line="73",times="0"},
|
fullname="/home/nickrob/myprog.c",line="73",times="0"},
|
time={wallclock="0.05185",user="0.00800",system="0.00000"}
|
time={wallclock="0.05185",user="0.00800",system="0.00000"}
|
(gdb)
|
(gdb)
|
-enable-timings no
|
-enable-timings no
|
^done
|
^done
|
(gdb)
|
(gdb)
|
-exec-run
|
-exec-run
|
^running
|
^running
|
(gdb)
|
(gdb)
|
*stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
|
*stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
|
frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"},
|
frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"},
|
{name="argv",value="0xbfb60364"}],file="myprog.c",
|
{name="argv",value="0xbfb60364"}],file="myprog.c",
|
fullname="/home/nickrob/myprog.c",line="73"}
|
fullname="/home/nickrob/myprog.c",line="73"}
|
(gdb)
|
(gdb)
|
|
|
|
|
File: gdb.info, Node: Annotations, Next: GDB Bugs, Prev: GDB/MI, Up: Top
|
File: gdb.info, Node: Annotations, Next: GDB Bugs, Prev: GDB/MI, Up: Top
|
|
|
25 GDB Annotations
|
25 GDB Annotations
|
******************
|
******************
|
|
|
This chapter describes annotations in GDB. Annotations were designed
|
This chapter describes annotations in GDB. Annotations were designed
|
to interface GDB to graphical user interfaces or other similar programs
|
to interface GDB to graphical user interfaces or other similar programs
|
which want to interact with GDB at a relatively high level.
|
which want to interact with GDB at a relatively high level.
|
|
|
The annotation mechanism has largely been superseded by GDB/MI
|
The annotation mechanism has largely been superseded by GDB/MI
|
(*note GDB/MI::).
|
(*note GDB/MI::).
|
|
|
* Menu:
|
* Menu:
|
|
|
* Annotations Overview:: What annotations are; the general syntax.
|
* Annotations Overview:: What annotations are; the general syntax.
|
* Server Prefix:: Issuing a command without affecting user state.
|
* Server Prefix:: Issuing a command without affecting user state.
|
* Prompting:: Annotations marking GDB's need for input.
|
* Prompting:: Annotations marking GDB's need for input.
|
* Errors:: Annotations for error messages.
|
* Errors:: Annotations for error messages.
|
* Invalidation:: Some annotations describe things now invalid.
|
* Invalidation:: Some annotations describe things now invalid.
|
* Annotations for Running::
|
* Annotations for Running::
|
Whether the program is running, how it stopped, etc.
|
Whether the program is running, how it stopped, etc.
|
* Source Annotations:: Annotations describing source code.
|
* Source Annotations:: Annotations describing source code.
|
|
|
|
|
File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations
|
File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations
|
|
|
25.1 What is an Annotation?
|
25.1 What is an Annotation?
|
===========================
|
===========================
|
|
|
Annotations start with a newline character, two `control-z' characters,
|
Annotations start with a newline character, two `control-z' characters,
|
and the name of the annotation. If there is no additional information
|
and the name of the annotation. If there is no additional information
|
associated with this annotation, the name of the annotation is followed
|
associated with this annotation, the name of the annotation is followed
|
immediately by a newline. If there is additional information, the name
|
immediately by a newline. If there is additional information, the name
|
of the annotation is followed by a space, the additional information,
|
of the annotation is followed by a space, the additional information,
|
and a newline. The additional information cannot contain newline
|
and a newline. The additional information cannot contain newline
|
characters.
|
characters.
|
|
|
Any output not beginning with a newline and two `control-z'
|
Any output not beginning with a newline and two `control-z'
|
characters denotes literal output from GDB. Currently there is no need
|
characters denotes literal output from GDB. Currently there is no need
|
for GDB to output a newline followed by two `control-z' characters, but
|
for GDB to output a newline followed by two `control-z' characters, but
|
if there was such a need, the annotations could be extended with an
|
if there was such a need, the annotations could be extended with an
|
`escape' annotation which means those three characters as output.
|
`escape' annotation which means those three characters as output.
|
|
|
The annotation LEVEL, which is specified using the `--annotate'
|
The annotation LEVEL, which is specified using the `--annotate'
|
command line option (*note Mode Options::), controls how much
|
command line option (*note Mode Options::), controls how much
|
information GDB prints together with its prompt, values of expressions,
|
information GDB prints together with its prompt, values of expressions,
|
source lines, and other types of output. Level 0 is for no
|
source lines, and other types of output. Level 0 is for no
|
annotations, level 1 is for use when GDB is run as a subprocess of GNU
|
annotations, level 1 is for use when GDB is run as a subprocess of GNU
|
Emacs, level 3 is the maximum annotation suitable for programs that
|
Emacs, level 3 is the maximum annotation suitable for programs that
|
control GDB, and level 2 annotations have been made obsolete (*note
|
control GDB, and level 2 annotations have been made obsolete (*note
|
Limitations of the Annotation Interface: (annotate)Limitations.).
|
Limitations of the Annotation Interface: (annotate)Limitations.).
|
|
|
`set annotate LEVEL'
|
`set annotate LEVEL'
|
The GDB command `set annotate' sets the level of annotations to
|
The GDB command `set annotate' sets the level of annotations to
|
the specified LEVEL.
|
the specified LEVEL.
|
|
|
`show annotate'
|
`show annotate'
|
Show the current annotation level.
|
Show the current annotation level.
|
|
|
This chapter describes level 3 annotations.
|
This chapter describes level 3 annotations.
|
|
|
A simple example of starting up GDB with annotations is:
|
A simple example of starting up GDB with annotations is:
|
|
|
$ gdb --annotate=3
|
$ gdb --annotate=3
|
GNU gdb 6.0
|
GNU gdb 6.0
|
Copyright 2003 Free Software Foundation, Inc.
|
Copyright 2003 Free Software Foundation, Inc.
|
GDB is free software, covered by the GNU General Public License,
|
GDB is free software, covered by the GNU General Public License,
|
and you are welcome to change it and/or distribute copies of it
|
and you are welcome to change it and/or distribute copies of it
|
under certain conditions.
|
under certain conditions.
|
Type "show copying" to see the conditions.
|
Type "show copying" to see the conditions.
|
There is absolutely no warranty for GDB. Type "show warranty"
|
There is absolutely no warranty for GDB. Type "show warranty"
|
for details.
|
for details.
|
This GDB was configured as "i386-pc-linux-gnu"
|
This GDB was configured as "i386-pc-linux-gnu"
|
|
|
^Z^Zpre-prompt
|
^Z^Zpre-prompt
|
(gdb)
|
(gdb)
|
^Z^Zprompt
|
^Z^Zprompt
|
quit
|
quit
|
|
|
^Z^Zpost-prompt
|
^Z^Zpost-prompt
|
$
|
$
|
|
|
Here `quit' is input to GDB; the rest is output from GDB. The three
|
Here `quit' is input to GDB; the rest is output from GDB. The three
|
lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
|
lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
|
annotations; the rest is output from GDB.
|
annotations; the rest is output from GDB.
|
|
|
|
|
File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations
|
File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations
|
|
|
25.2 The Server Prefix
|
25.2 The Server Prefix
|
======================
|
======================
|
|
|
If you prefix a command with `server ' then it will not affect the
|
If you prefix a command with `server ' then it will not affect the
|
command history, nor will it affect GDB's notion of which command to
|
command history, nor will it affect GDB's notion of which command to
|
repeat if is pressed on a line by itself. This means that
|
repeat if is pressed on a line by itself. This means that
|
commands can be run behind a user's back by a front-end in a
|
commands can be run behind a user's back by a front-end in a
|
transparent manner.
|
transparent manner.
|
|
|
The server prefix does not affect the recording of values into the
|
The server prefix does not affect the recording of values into the
|
value history; to print a value without recording it into the value
|
value history; to print a value without recording it into the value
|
history, use the `output' command instead of the `print' command.
|
history, use the `output' command instead of the `print' command.
|
|
|
|
|
File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations
|
File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations
|
|
|
25.3 Annotation for GDB Input
|
25.3 Annotation for GDB Input
|
=============================
|
=============================
|
|
|
When GDB prompts for input, it annotates this fact so it is possible to
|
When GDB prompts for input, it annotates this fact so it is possible to
|
know when to send output, when the output from a given command is over,
|
know when to send output, when the output from a given command is over,
|
etc.
|
etc.
|
|
|
Different kinds of input each have a different "input type". Each
|
Different kinds of input each have a different "input type". Each
|
input type has three annotations: a `pre-' annotation, which denotes
|
input type has three annotations: a `pre-' annotation, which denotes
|
the beginning of any prompt which is being output, a plain annotation,
|
the beginning of any prompt which is being output, a plain annotation,
|
which denotes the end of the prompt, and then a `post-' annotation
|
which denotes the end of the prompt, and then a `post-' annotation
|
which denotes the end of any echo which may (or may not) be associated
|
which denotes the end of any echo which may (or may not) be associated
|
with the input. For example, the `prompt' input type features the
|
with the input. For example, the `prompt' input type features the
|
following annotations:
|
following annotations:
|
|
|
^Z^Zpre-prompt
|
^Z^Zpre-prompt
|
^Z^Zprompt
|
^Z^Zprompt
|
^Z^Zpost-prompt
|
^Z^Zpost-prompt
|
|
|
The input types are
|
The input types are
|
|
|
`prompt'
|
`prompt'
|
When GDB is prompting for a command (the main GDB prompt).
|
When GDB is prompting for a command (the main GDB prompt).
|
|
|
`commands'
|
`commands'
|
When GDB prompts for a set of commands, like in the `commands'
|
When GDB prompts for a set of commands, like in the `commands'
|
command. The annotations are repeated for each command which is
|
command. The annotations are repeated for each command which is
|
input.
|
input.
|
|
|
`overload-choice'
|
`overload-choice'
|
When GDB wants the user to select between various overloaded
|
When GDB wants the user to select between various overloaded
|
functions.
|
functions.
|
|
|
`query'
|
`query'
|
When GDB wants the user to confirm a potentially dangerous
|
When GDB wants the user to confirm a potentially dangerous
|
operation.
|
operation.
|
|
|
`prompt-for-continue'
|
`prompt-for-continue'
|
When GDB is asking the user to press return to continue. Note:
|
When GDB is asking the user to press return to continue. Note:
|
Don't expect this to work well; instead use `set height 0' to
|
Don't expect this to work well; instead use `set height 0' to
|
disable prompting. This is because the counting of lines is buggy
|
disable prompting. This is because the counting of lines is buggy
|
in the presence of annotations.
|
in the presence of annotations.
|
|
|
|
|
File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations
|
File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations
|
|
|
25.4 Errors
|
25.4 Errors
|
===========
|
===========
|
|
|
^Z^Zquit
|
^Z^Zquit
|
|
|
This annotation occurs right before GDB responds to an interrupt.
|
This annotation occurs right before GDB responds to an interrupt.
|
|
|
^Z^Zerror
|
^Z^Zerror
|
|
|
This annotation occurs right before GDB responds to an error.
|
This annotation occurs right before GDB responds to an error.
|
|
|
Quit and error annotations indicate that any annotations which GDB
|
Quit and error annotations indicate that any annotations which GDB
|
was in the middle of may end abruptly. For example, if a
|
was in the middle of may end abruptly. For example, if a
|
`value-history-begin' annotation is followed by a `error', one cannot
|
`value-history-begin' annotation is followed by a `error', one cannot
|
expect to receive the matching `value-history-end'. One cannot expect
|
expect to receive the matching `value-history-end'. One cannot expect
|
not to receive it either, however; an error annotation does not
|
not to receive it either, however; an error annotation does not
|
necessarily mean that GDB is immediately returning all the way to the
|
necessarily mean that GDB is immediately returning all the way to the
|
top level.
|
top level.
|
|
|
A quit or error annotation may be preceded by
|
A quit or error annotation may be preceded by
|
|
|
^Z^Zerror-begin
|
^Z^Zerror-begin
|
|
|
Any output between that and the quit or error annotation is the error
|
Any output between that and the quit or error annotation is the error
|
message.
|
message.
|
|
|
Warning messages are not yet annotated.
|
Warning messages are not yet annotated.
|
|
|
|
|
File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations
|
File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations
|
|
|
25.5 Invalidation Notices
|
25.5 Invalidation Notices
|
=========================
|
=========================
|
|
|
The following annotations say that certain pieces of state may have
|
The following annotations say that certain pieces of state may have
|
changed.
|
changed.
|
|
|
`^Z^Zframes-invalid'
|
`^Z^Zframes-invalid'
|
The frames (for example, output from the `backtrace' command) may
|
The frames (for example, output from the `backtrace' command) may
|
have changed.
|
have changed.
|
|
|
`^Z^Zbreakpoints-invalid'
|
`^Z^Zbreakpoints-invalid'
|
The breakpoints may have changed. For example, the user just
|
The breakpoints may have changed. For example, the user just
|
added or deleted a breakpoint.
|
added or deleted a breakpoint.
|
|
|
|
|
File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations
|
File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations
|
|
|
25.6 Running the Program
|
25.6 Running the Program
|
========================
|
========================
|
|
|
When the program starts executing due to a GDB command such as `step'
|
When the program starts executing due to a GDB command such as `step'
|
or `continue',
|
or `continue',
|
|
|
^Z^Zstarting
|
^Z^Zstarting
|
|
|
is output. When the program stops,
|
is output. When the program stops,
|
|
|
^Z^Zstopped
|
^Z^Zstopped
|
|
|
is output. Before the `stopped' annotation, a variety of
|
is output. Before the `stopped' annotation, a variety of
|
annotations describe how the program stopped.
|
annotations describe how the program stopped.
|
|
|
`^Z^Zexited EXIT-STATUS'
|
`^Z^Zexited EXIT-STATUS'
|
The program exited, and EXIT-STATUS is the exit status (zero for
|
The program exited, and EXIT-STATUS is the exit status (zero for
|
successful exit, otherwise nonzero).
|
successful exit, otherwise nonzero).
|
|
|
`^Z^Zsignalled'
|
`^Z^Zsignalled'
|
The program exited with a signal. After the `^Z^Zsignalled', the
|
The program exited with a signal. After the `^Z^Zsignalled', the
|
annotation continues:
|
annotation continues:
|
|
|
INTRO-TEXT
|
INTRO-TEXT
|
^Z^Zsignal-name
|
^Z^Zsignal-name
|
NAME
|
NAME
|
^Z^Zsignal-name-end
|
^Z^Zsignal-name-end
|
MIDDLE-TEXT
|
MIDDLE-TEXT
|
^Z^Zsignal-string
|
^Z^Zsignal-string
|
STRING
|
STRING
|
^Z^Zsignal-string-end
|
^Z^Zsignal-string-end
|
END-TEXT
|
END-TEXT
|
|
|
where NAME is the name of the signal, such as `SIGILL' or
|
where NAME is the name of the signal, such as `SIGILL' or
|
`SIGSEGV', and STRING is the explanation of the signal, such as
|
`SIGSEGV', and STRING is the explanation of the signal, such as
|
`Illegal Instruction' or `Segmentation fault'. INTRO-TEXT,
|
`Illegal Instruction' or `Segmentation fault'. INTRO-TEXT,
|
MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
|
MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
|
particular format.
|
particular format.
|
|
|
`^Z^Zsignal'
|
`^Z^Zsignal'
|
The syntax of this annotation is just like `signalled', but GDB is
|
The syntax of this annotation is just like `signalled', but GDB is
|
just saying that the program received the signal, not that it was
|
just saying that the program received the signal, not that it was
|
terminated with it.
|
terminated with it.
|
|
|
`^Z^Zbreakpoint NUMBER'
|
`^Z^Zbreakpoint NUMBER'
|
The program hit breakpoint number NUMBER.
|
The program hit breakpoint number NUMBER.
|
|
|
`^Z^Zwatchpoint NUMBER'
|
`^Z^Zwatchpoint NUMBER'
|
The program hit watchpoint number NUMBER.
|
The program hit watchpoint number NUMBER.
|
|
|
|
|
File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations
|
File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations
|
|
|
25.7 Displaying Source
|
25.7 Displaying Source
|
======================
|
======================
|
|
|
The following annotation is used instead of displaying source code:
|
The following annotation is used instead of displaying source code:
|
|
|
^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
|
^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
|
|
|
where FILENAME is an absolute file name indicating which source
|
where FILENAME is an absolute file name indicating which source
|
file, LINE is the line number within that file (where 1 is the first
|
file, LINE is the line number within that file (where 1 is the first
|
line in the file), CHARACTER is the character position within the file
|
line in the file), CHARACTER is the character position within the file
|
(where 0 is the first character in the file) (for most debug formats
|
(where 0 is the first character in the file) (for most debug formats
|
this will necessarily point to the beginning of a line), MIDDLE is
|
this will necessarily point to the beginning of a line), MIDDLE is
|
`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
|
`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
|
the beginning of the line, and ADDR is the address in the target
|
the beginning of the line, and ADDR is the address in the target
|
program associated with the source which is being displayed. ADDR is
|
program associated with the source which is being displayed. ADDR is
|
in the form `0x' followed by one or more lowercase hex digits (note
|
in the form `0x' followed by one or more lowercase hex digits (note
|
that this does not depend on the language).
|
that this does not depend on the language).
|
|
|
|
|
File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: Annotations, Up: Top
|
File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: Annotations, Up: Top
|
|
|
26 Reporting Bugs in GDB
|
26 Reporting Bugs in GDB
|
************************
|
************************
|
|
|
Your bug reports play an essential role in making GDB reliable.
|
Your bug reports play an essential role in making GDB reliable.
|
|
|
Reporting a bug may help you by bringing a solution to your problem,
|
Reporting a bug may help you by bringing a solution to your problem,
|
or it may not. But in any case the principal function of a bug report
|
or it may not. But in any case the principal function of a bug report
|
is to help the entire community by making the next version of GDB work
|
is to help the entire community by making the next version of GDB work
|
better. Bug reports are your contribution to the maintenance of GDB.
|
better. Bug reports are your contribution to the maintenance of GDB.
|
|
|
In order for a bug report to serve its purpose, you must include the
|
In order for a bug report to serve its purpose, you must include the
|
information that enables us to fix the bug.
|
information that enables us to fix the bug.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Bug Criteria:: Have you found a bug?
|
* Bug Criteria:: Have you found a bug?
|
* Bug Reporting:: How to report bugs
|
* Bug Reporting:: How to report bugs
|
|
|
|
|
File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs
|
File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs
|
|
|
26.1 Have You Found a Bug?
|
26.1 Have You Found a Bug?
|
==========================
|
==========================
|
|
|
If you are not sure whether you have found a bug, here are some
|
If you are not sure whether you have found a bug, here are some
|
guidelines:
|
guidelines:
|
|
|
* If the debugger gets a fatal signal, for any input whatever, that
|
* If the debugger gets a fatal signal, for any input whatever, that
|
is a GDB bug. Reliable debuggers never crash.
|
is a GDB bug. Reliable debuggers never crash.
|
|
|
* If GDB produces an error message for valid input, that is a bug.
|
* If GDB produces an error message for valid input, that is a bug.
|
(Note that if you're cross debugging, the problem may also be
|
(Note that if you're cross debugging, the problem may also be
|
somewhere in the connection to the target.)
|
somewhere in the connection to the target.)
|
|
|
* If GDB does not produce an error message for invalid input, that
|
* If GDB does not produce an error message for invalid input, that
|
is a bug. However, you should note that your idea of "invalid
|
is a bug. However, you should note that your idea of "invalid
|
input" might be our idea of "an extension" or "support for
|
input" might be our idea of "an extension" or "support for
|
traditional practice".
|
traditional practice".
|
|
|
* If you are an experienced user of debugging tools, your suggestions
|
* If you are an experienced user of debugging tools, your suggestions
|
for improvement of GDB are welcome in any case.
|
for improvement of GDB are welcome in any case.
|
|
|
|
|
File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs
|
File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs
|
|
|
26.2 How to Report Bugs
|
26.2 How to Report Bugs
|
=======================
|
=======================
|
|
|
A number of companies and individuals offer support for GNU products.
|
A number of companies and individuals offer support for GNU products.
|
If you obtained GDB from a support organization, we recommend you
|
If you obtained GDB from a support organization, we recommend you
|
contact that organization first.
|
contact that organization first.
|
|
|
You can find contact information for many support companies and
|
You can find contact information for many support companies and
|
individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
|
individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
|
|
|
In any event, we also recommend that you submit bug reports for GDB.
|
In any event, we also recommend that you submit bug reports for GDB.
|
The preferred method is to submit them directly using GDB's Bugs web
|
The preferred method is to submit them directly using GDB's Bugs web
|
page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the
|
page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the
|
e-mail gateway can be used.
|
e-mail gateway can be used.
|
|
|
*Do not send bug reports to `info-gdb', or to `help-gdb', or to any
|
*Do not send bug reports to `info-gdb', or to `help-gdb', or to any
|
newsgroups.* Most users of GDB do not want to receive bug reports.
|
newsgroups.* Most users of GDB do not want to receive bug reports.
|
Those that do have arranged to receive `bug-gdb'.
|
Those that do have arranged to receive `bug-gdb'.
|
|
|
The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which
|
The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which
|
serves as a repeater. The mailing list and the newsgroup carry exactly
|
serves as a repeater. The mailing list and the newsgroup carry exactly
|
the same messages. Often people think of posting bug reports to the
|
the same messages. Often people think of posting bug reports to the
|
newsgroup instead of mailing them. This appears to work, but it has one
|
newsgroup instead of mailing them. This appears to work, but it has one
|
problem which can be crucial: a newsgroup posting often lacks a mail
|
problem which can be crucial: a newsgroup posting often lacks a mail
|
path back to the sender. Thus, if we need to ask for more information,
|
path back to the sender. Thus, if we need to ask for more information,
|
we may be unable to reach you. For this reason, it is better to send
|
we may be unable to reach you. For this reason, it is better to send
|
bug reports to the mailing list.
|
bug reports to the mailing list.
|
|
|
The fundamental principle of reporting bugs usefully is this:
|
The fundamental principle of reporting bugs usefully is this:
|
*report all the facts*. If you are not sure whether to state a fact or
|
*report all the facts*. If you are not sure whether to state a fact or
|
leave it out, state it!
|
leave it out, state it!
|
|
|
Often people omit facts because they think they know what causes the
|
Often people omit facts because they think they know what causes the
|
problem and assume that some details do not matter. Thus, you might
|
problem and assume that some details do not matter. Thus, you might
|
assume that the name of the variable you use in an example does not
|
assume that the name of the variable you use in an example does not
|
matter. Well, probably it does not, but one cannot be sure. Perhaps
|
matter. Well, probably it does not, but one cannot be sure. Perhaps
|
the bug is a stray memory reference which happens to fetch from the
|
the bug is a stray memory reference which happens to fetch from the
|
location where that name is stored in memory; perhaps, if the name were
|
location where that name is stored in memory; perhaps, if the name were
|
different, the contents of that location would fool the debugger into
|
different, the contents of that location would fool the debugger into
|
doing the right thing despite the bug. Play it safe and give a
|
doing the right thing despite the bug. Play it safe and give a
|
specific, complete example. That is the easiest thing for you to do,
|
specific, complete example. That is the easiest thing for you to do,
|
and the most helpful.
|
and the most helpful.
|
|
|
Keep in mind that the purpose of a bug report is to enable us to fix
|
Keep in mind that the purpose of a bug report is to enable us to fix
|
the bug. It may be that the bug has been reported previously, but
|
the bug. It may be that the bug has been reported previously, but
|
neither you nor we can know that unless your bug report is complete and
|
neither you nor we can know that unless your bug report is complete and
|
self-contained.
|
self-contained.
|
|
|
Sometimes people give a few sketchy facts and ask, "Does this ring a
|
Sometimes people give a few sketchy facts and ask, "Does this ring a
|
bell?" Those bug reports are useless, and we urge everyone to _refuse
|
bell?" Those bug reports are useless, and we urge everyone to _refuse
|
to respond to them_ except to chide the sender to report bugs properly.
|
to respond to them_ except to chide the sender to report bugs properly.
|
|
|
To enable us to fix the bug, you should include all these things:
|
To enable us to fix the bug, you should include all these things:
|
|
|
* The version of GDB. GDB announces it if you start with no
|
* The version of GDB. GDB announces it if you start with no
|
arguments; you can also print it at any time using `show version'.
|
arguments; you can also print it at any time using `show version'.
|
|
|
Without this, we will not know whether there is any point in
|
Without this, we will not know whether there is any point in
|
looking for the bug in the current version of GDB.
|
looking for the bug in the current version of GDB.
|
|
|
* The type of machine you are using, and the operating system name
|
* The type of machine you are using, and the operating system name
|
and version number.
|
and version number.
|
|
|
* What compiler (and its version) was used to compile GDB--e.g.
|
* What compiler (and its version) was used to compile GDB--e.g.
|
"gcc-2.8.1".
|
"gcc-2.8.1".
|
|
|
* What compiler (and its version) was used to compile the program
|
* What compiler (and its version) was used to compile the program
|
you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP
|
you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP
|
C Compiler". For GCC, you can say `gcc --version' to get this
|
C Compiler". For GCC, you can say `gcc --version' to get this
|
information; for other compilers, see the documentation for those
|
information; for other compilers, see the documentation for those
|
compilers.
|
compilers.
|
|
|
* The command arguments you gave the compiler to compile your
|
* The command arguments you gave the compiler to compile your
|
example and observe the bug. For example, did you use `-O'? To
|
example and observe the bug. For example, did you use `-O'? To
|
guarantee you will not omit something important, list them all. A
|
guarantee you will not omit something important, list them all. A
|
copy of the Makefile (or the output from make) is sufficient.
|
copy of the Makefile (or the output from make) is sufficient.
|
|
|
If we were to try to guess the arguments, we would probably guess
|
If we were to try to guess the arguments, we would probably guess
|
wrong and then we might not encounter the bug.
|
wrong and then we might not encounter the bug.
|
|
|
* A complete input script, and all necessary source files, that will
|
* A complete input script, and all necessary source files, that will
|
reproduce the bug.
|
reproduce the bug.
|
|
|
* A description of what behavior you observe that you believe is
|
* A description of what behavior you observe that you believe is
|
incorrect. For example, "It gets a fatal signal."
|
incorrect. For example, "It gets a fatal signal."
|
|
|
Of course, if the bug is that GDB gets a fatal signal, then we
|
Of course, if the bug is that GDB gets a fatal signal, then we
|
will certainly notice it. But if the bug is incorrect output, we
|
will certainly notice it. But if the bug is incorrect output, we
|
might not notice unless it is glaringly wrong. You might as well
|
might not notice unless it is glaringly wrong. You might as well
|
not give us a chance to make a mistake.
|
not give us a chance to make a mistake.
|
|
|
Even if the problem you experience is a fatal signal, you should
|
Even if the problem you experience is a fatal signal, you should
|
still say so explicitly. Suppose something strange is going on,
|
still say so explicitly. Suppose something strange is going on,
|
such as, your copy of GDB is out of synch, or you have encountered
|
such as, your copy of GDB is out of synch, or you have encountered
|
a bug in the C library on your system. (This has happened!) Your
|
a bug in the C library on your system. (This has happened!) Your
|
copy might crash and ours would not. If you told us to expect a
|
copy might crash and ours would not. If you told us to expect a
|
crash, then when ours fails to crash, we would know that the bug
|
crash, then when ours fails to crash, we would know that the bug
|
was not happening for us. If you had not told us to expect a
|
was not happening for us. If you had not told us to expect a
|
crash, then we would not be able to draw any conclusion from our
|
crash, then we would not be able to draw any conclusion from our
|
observations.
|
observations.
|
|
|
To collect all this information, you can use a session recording
|
To collect all this information, you can use a session recording
|
program such as `script', which is available on many Unix systems.
|
program such as `script', which is available on many Unix systems.
|
Just run your GDB session inside `script' and then include the
|
Just run your GDB session inside `script' and then include the
|
`typescript' file with your bug report.
|
`typescript' file with your bug report.
|
|
|
Another way to record a GDB session is to run GDB inside Emacs and
|
Another way to record a GDB session is to run GDB inside Emacs and
|
then save the entire buffer to a file.
|
then save the entire buffer to a file.
|
|
|
* If you wish to suggest changes to the GDB source, send us context
|
* If you wish to suggest changes to the GDB source, send us context
|
diffs. If you even discuss something in the GDB source, refer to
|
diffs. If you even discuss something in the GDB source, refer to
|
it by context, not by line number.
|
it by context, not by line number.
|
|
|
The line numbers in our development sources will not match those
|
The line numbers in our development sources will not match those
|
in your sources. Your line numbers would convey no useful
|
in your sources. Your line numbers would convey no useful
|
information to us.
|
information to us.
|
|
|
|
|
Here are some things that are not necessary:
|
Here are some things that are not necessary:
|
|
|
* A description of the envelope of the bug.
|
* A description of the envelope of the bug.
|
|
|
Often people who encounter a bug spend a lot of time investigating
|
Often people who encounter a bug spend a lot of time investigating
|
which changes to the input file will make the bug go away and which
|
which changes to the input file will make the bug go away and which
|
changes will not affect it.
|
changes will not affect it.
|
|
|
This is often time consuming and not very useful, because the way
|
This is often time consuming and not very useful, because the way
|
we will find the bug is by running a single example under the
|
we will find the bug is by running a single example under the
|
debugger with breakpoints, not by pure deduction from a series of
|
debugger with breakpoints, not by pure deduction from a series of
|
examples. We recommend that you save your time for something else.
|
examples. We recommend that you save your time for something else.
|
|
|
Of course, if you can find a simpler example to report _instead_
|
Of course, if you can find a simpler example to report _instead_
|
of the original one, that is a convenience for us. Errors in the
|
of the original one, that is a convenience for us. Errors in the
|
output will be easier to spot, running under the debugger will take
|
output will be easier to spot, running under the debugger will take
|
less time, and so on.
|
less time, and so on.
|
|
|
However, simplification is not vital; if you do not want to do
|
However, simplification is not vital; if you do not want to do
|
this, report the bug anyway and send us the entire test case you
|
this, report the bug anyway and send us the entire test case you
|
used.
|
used.
|
|
|
* A patch for the bug.
|
* A patch for the bug.
|
|
|
A patch for the bug does help us if it is a good one. But do not
|
A patch for the bug does help us if it is a good one. But do not
|
omit the necessary information, such as the test case, on the
|
omit the necessary information, such as the test case, on the
|
assumption that a patch is all we need. We might see problems
|
assumption that a patch is all we need. We might see problems
|
with your patch and decide to fix the problem another way, or we
|
with your patch and decide to fix the problem another way, or we
|
might not understand it at all.
|
might not understand it at all.
|
|
|
Sometimes with a program as complicated as GDB it is very hard to
|
Sometimes with a program as complicated as GDB it is very hard to
|
construct an example that will make the program follow a certain
|
construct an example that will make the program follow a certain
|
path through the code. If you do not send us the example, we will
|
path through the code. If you do not send us the example, we will
|
not be able to construct one, so we will not be able to verify
|
not be able to construct one, so we will not be able to verify
|
that the bug is fixed.
|
that the bug is fixed.
|
|
|
And if we cannot understand what bug you are trying to fix, or why
|
And if we cannot understand what bug you are trying to fix, or why
|
your patch should be an improvement, we will not install it. A
|
your patch should be an improvement, we will not install it. A
|
test case will help us to understand.
|
test case will help us to understand.
|
|
|
* A guess about what the bug is or what it depends on.
|
* A guess about what the bug is or what it depends on.
|
|
|
Such guesses are usually wrong. Even we cannot guess right about
|
Such guesses are usually wrong. Even we cannot guess right about
|
such things without first using the debugger to find the facts.
|
such things without first using the debugger to find the facts.
|
|
|
|
|
File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top
|
File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top
|
|
|
27 Command Line Editing
|
27 Command Line Editing
|
***********************
|
***********************
|
|
|
This chapter describes the basic features of the GNU command line
|
This chapter describes the basic features of the GNU command line
|
editing interface.
|
editing interface.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Introduction and Notation:: Notation used in this text.
|
* Introduction and Notation:: Notation used in this text.
|
* Readline Interaction:: The minimum set of commands for editing a line.
|
* Readline Interaction:: The minimum set of commands for editing a line.
|
* Readline Init File:: Customizing Readline from a user's view.
|
* Readline Init File:: Customizing Readline from a user's view.
|
* Bindable Readline Commands:: A description of most of the Readline commands
|
* Bindable Readline Commands:: A description of most of the Readline commands
|
available for binding
|
available for binding
|
* Readline vi Mode:: A short description of how to make Readline
|
* Readline vi Mode:: A short description of how to make Readline
|
behave like the vi editor.
|
behave like the vi editor.
|
|
|
|
|
File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
|
File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
|
|
|
27.1 Introduction to Line Editing
|
27.1 Introduction to Line Editing
|
=================================
|
=================================
|
|
|
The following paragraphs describe the notation used to represent
|
The following paragraphs describe the notation used to represent
|
keystrokes.
|
keystrokes.
|
|
|
The text `C-k' is read as `Control-K' and describes the character
|
The text `C-k' is read as `Control-K' and describes the character
|
produced when the key is pressed while the Control key is depressed.
|
produced when the key is pressed while the Control key is depressed.
|
|
|
The text `M-k' is read as `Meta-K' and describes the character
|
The text `M-k' is read as `Meta-K' and describes the character
|
produced when the Meta key (if you have one) is depressed, and the
|
produced when the Meta key (if you have one) is depressed, and the
|
key is pressed. The Meta key is labeled on many keyboards. On
|
key is pressed. The Meta key is labeled on many keyboards. On
|
keyboards with two keys labeled (usually to either side of the
|
keyboards with two keys labeled (usually to either side of the
|
space bar), the on the left side is generally set to work as a
|
space bar), the on the left side is generally set to work as a
|
Meta key. The key on the right may also be configured to work as
|
Meta key. The key on the right may also be configured to work as
|
a Meta key or may be configured as some other modifier, such as a
|
a Meta key or may be configured as some other modifier, such as a
|
Compose key for typing accented characters.
|
Compose key for typing accented characters.
|
|
|
If you do not have a Meta or key, or another key working as a
|
If you do not have a Meta or key, or another key working as a
|
Meta key, the identical keystroke can be generated by typing
|
Meta key, the identical keystroke can be generated by typing
|
_first_, and then typing . Either process is known as "metafying"
|
_first_, and then typing . Either process is known as "metafying"
|
the key.
|
the key.
|
|
|
The text `M-C-k' is read as `Meta-Control-k' and describes the
|
The text `M-C-k' is read as `Meta-Control-k' and describes the
|
character produced by "metafying" `C-k'.
|
character produced by "metafying" `C-k'.
|
|
|
In addition, several keys have their own names. Specifically,
|
In addition, several keys have their own names. Specifically,
|
, , , , , and all stand for themselves
|
, , , , , and all stand for themselves
|
when seen in this text, or in an init file (*note Readline Init File::).
|
when seen in this text, or in an init file (*note Readline Init File::).
|
If your keyboard lacks a key, typing will produce the
|
If your keyboard lacks a key, typing will produce the
|
desired character. The key may be labeled or on
|
desired character. The key may be labeled or on
|
some keyboards.
|
some keyboards.
|
|
|
|
|
File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
|
File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
|
|
|
27.2 Readline Interaction
|
27.2 Readline Interaction
|
=========================
|
=========================
|
|
|
Often during an interactive session you type in a long line of text,
|
Often during an interactive session you type in a long line of text,
|
only to notice that the first word on the line is misspelled. The
|
only to notice that the first word on the line is misspelled. The
|
Readline library gives you a set of commands for manipulating the text
|
Readline library gives you a set of commands for manipulating the text
|
as you type it in, allowing you to just fix your typo, and not forcing
|
as you type it in, allowing you to just fix your typo, and not forcing
|
you to retype the majority of the line. Using these editing commands,
|
you to retype the majority of the line. Using these editing commands,
|
you move the cursor to the place that needs correction, and delete or
|
you move the cursor to the place that needs correction, and delete or
|
insert the text of the corrections. Then, when you are satisfied with
|
insert the text of the corrections. Then, when you are satisfied with
|
the line, you simply press . You do not have to be at the end of
|
the line, you simply press . You do not have to be at the end of
|
the line to press ; the entire line is accepted regardless of the
|
the line to press ; the entire line is accepted regardless of the
|
location of the cursor within the line.
|
location of the cursor within the line.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Readline Bare Essentials:: The least you need to know about Readline.
|
* Readline Bare Essentials:: The least you need to know about Readline.
|
* Readline Movement Commands:: Moving about the input line.
|
* Readline Movement Commands:: Moving about the input line.
|
* Readline Killing Commands:: How to delete text, and how to get it back!
|
* Readline Killing Commands:: How to delete text, and how to get it back!
|
* Readline Arguments:: Giving numeric arguments to commands.
|
* Readline Arguments:: Giving numeric arguments to commands.
|
* Searching:: Searching through previous lines.
|
* Searching:: Searching through previous lines.
|
|
|
|
|
File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
|
File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
|
|
|
27.2.1 Readline Bare Essentials
|
27.2.1 Readline Bare Essentials
|
-------------------------------
|
-------------------------------
|
|
|
In order to enter characters into the line, simply type them. The typed
|
In order to enter characters into the line, simply type them. The typed
|
character appears where the cursor was, and then the cursor moves one
|
character appears where the cursor was, and then the cursor moves one
|
space to the right. If you mistype a character, you can use your erase
|
space to the right. If you mistype a character, you can use your erase
|
character to back up and delete the mistyped character.
|
character to back up and delete the mistyped character.
|
|
|
Sometimes you may mistype a character, and not notice the error
|
Sometimes you may mistype a character, and not notice the error
|
until you have typed several other characters. In that case, you can
|
until you have typed several other characters. In that case, you can
|
type `C-b' to move the cursor to the left, and then correct your
|
type `C-b' to move the cursor to the left, and then correct your
|
mistake. Afterwards, you can move the cursor to the right with `C-f'.
|
mistake. Afterwards, you can move the cursor to the right with `C-f'.
|
|
|
When you add text in the middle of a line, you will notice that
|
When you add text in the middle of a line, you will notice that
|
characters to the right of the cursor are `pushed over' to make room
|
characters to the right of the cursor are `pushed over' to make room
|
for the text that you have inserted. Likewise, when you delete text
|
for the text that you have inserted. Likewise, when you delete text
|
behind the cursor, characters to the right of the cursor are `pulled
|
behind the cursor, characters to the right of the cursor are `pulled
|
back' to fill in the blank space created by the removal of the text. A
|
back' to fill in the blank space created by the removal of the text. A
|
list of the bare essentials for editing the text of an input line
|
list of the bare essentials for editing the text of an input line
|
follows.
|
follows.
|
|
|
`C-b'
|
`C-b'
|
Move back one character.
|
Move back one character.
|
|
|
`C-f'
|
`C-f'
|
Move forward one character.
|
Move forward one character.
|
|
|
or
|
or
|
Delete the character to the left of the cursor.
|
Delete the character to the left of the cursor.
|
|
|
`C-d'
|
`C-d'
|
Delete the character underneath the cursor.
|
Delete the character underneath the cursor.
|
|
|
Printing characters
|
Printing characters
|
Insert the character into the line at the cursor.
|
Insert the character into the line at the cursor.
|
|
|
`C-_' or `C-x C-u'
|
`C-_' or `C-x C-u'
|
Undo the last editing command. You can undo all the way back to an
|
Undo the last editing command. You can undo all the way back to an
|
empty line.
|
empty line.
|
|
|
(Depending on your configuration, the key be set to delete
|
(Depending on your configuration, the key be set to delete
|
the character to the left of the cursor and the key set to delete
|
the character to the left of the cursor and the key set to delete
|
the character underneath the cursor, like `C-d', rather than the
|
the character underneath the cursor, like `C-d', rather than the
|
character to the left of the cursor.)
|
character to the left of the cursor.)
|
|
|
|
|
File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
|
File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
|
|
|
27.2.2 Readline Movement Commands
|
27.2.2 Readline Movement Commands
|
---------------------------------
|
---------------------------------
|
|
|
The above table describes the most basic keystrokes that you need in
|
The above table describes the most basic keystrokes that you need in
|
order to do editing of the input line. For your convenience, many
|
order to do editing of the input line. For your convenience, many
|
other commands have been added in addition to `C-b', `C-f', `C-d', and
|
other commands have been added in addition to `C-b', `C-f', `C-d', and
|
. Here are some commands for moving more rapidly about the line.
|
. Here are some commands for moving more rapidly about the line.
|
|
|
`C-a'
|
`C-a'
|
Move to the start of the line.
|
Move to the start of the line.
|
|
|
`C-e'
|
`C-e'
|
Move to the end of the line.
|
Move to the end of the line.
|
|
|
`M-f'
|
`M-f'
|
Move forward a word, where a word is composed of letters and
|
Move forward a word, where a word is composed of letters and
|
digits.
|
digits.
|
|
|
`M-b'
|
`M-b'
|
Move backward a word.
|
Move backward a word.
|
|
|
`C-l'
|
`C-l'
|
Clear the screen, reprinting the current line at the top.
|
Clear the screen, reprinting the current line at the top.
|
|
|
Notice how `C-f' moves forward a character, while `M-f' moves
|
Notice how `C-f' moves forward a character, while `M-f' moves
|
forward a word. It is a loose convention that control keystrokes
|
forward a word. It is a loose convention that control keystrokes
|
operate on characters while meta keystrokes operate on words.
|
operate on characters while meta keystrokes operate on words.
|
|
|
|
|
File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
|
File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
|
|
|
27.2.3 Readline Killing Commands
|
27.2.3 Readline Killing Commands
|
--------------------------------
|
--------------------------------
|
|
|
"Killing" text means to delete the text from the line, but to save it
|
"Killing" text means to delete the text from the line, but to save it
|
away for later use, usually by "yanking" (re-inserting) it back into
|
away for later use, usually by "yanking" (re-inserting) it back into
|
the line. (`Cut' and `paste' are more recent jargon for `kill' and
|
the line. (`Cut' and `paste' are more recent jargon for `kill' and
|
`yank'.)
|
`yank'.)
|
|
|
If the description for a command says that it `kills' text, then you
|
If the description for a command says that it `kills' text, then you
|
can be sure that you can get the text back in a different (or the same)
|
can be sure that you can get the text back in a different (or the same)
|
place later.
|
place later.
|
|
|
When you use a kill command, the text is saved in a "kill-ring".
|
When you use a kill command, the text is saved in a "kill-ring".
|
Any number of consecutive kills save all of the killed text together, so
|
Any number of consecutive kills save all of the killed text together, so
|
that when you yank it back, you get it all. The kill ring is not line
|
that when you yank it back, you get it all. The kill ring is not line
|
specific; the text that you killed on a previously typed line is
|
specific; the text that you killed on a previously typed line is
|
available to be yanked back later, when you are typing another line.
|
available to be yanked back later, when you are typing another line.
|
|
|
Here is the list of commands for killing text.
|
Here is the list of commands for killing text.
|
|
|
`C-k'
|
`C-k'
|
Kill the text from the current cursor position to the end of the
|
Kill the text from the current cursor position to the end of the
|
line.
|
line.
|
|
|
`M-d'
|
`M-d'
|
Kill from the cursor to the end of the current word, or, if between
|
Kill from the cursor to the end of the current word, or, if between
|
words, to the end of the next word. Word boundaries are the same
|
words, to the end of the next word. Word boundaries are the same
|
as those used by `M-f'.
|
as those used by `M-f'.
|
|
|
`M-'
|
`M-'
|
Kill from the cursor the start of the current word, or, if between
|
Kill from the cursor the start of the current word, or, if between
|
words, to the start of the previous word. Word boundaries are the
|
words, to the start of the previous word. Word boundaries are the
|
same as those used by `M-b'.
|
same as those used by `M-b'.
|
|
|
`C-w'
|
`C-w'
|
Kill from the cursor to the previous whitespace. This is
|
Kill from the cursor to the previous whitespace. This is
|
different than `M-' because the word boundaries differ.
|
different than `M-' because the word boundaries differ.
|
|
|
|
|
Here is how to "yank" the text back into the line. Yanking means to
|
Here is how to "yank" the text back into the line. Yanking means to
|
copy the most-recently-killed text from the kill buffer.
|
copy the most-recently-killed text from the kill buffer.
|
|
|
`C-y'
|
`C-y'
|
Yank the most recently killed text back into the buffer at the
|
Yank the most recently killed text back into the buffer at the
|
cursor.
|
cursor.
|
|
|
`M-y'
|
`M-y'
|
Rotate the kill-ring, and yank the new top. You can only do this
|
Rotate the kill-ring, and yank the new top. You can only do this
|
if the prior command is `C-y' or `M-y'.
|
if the prior command is `C-y' or `M-y'.
|
|
|
|
|
File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
|
File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
|
|
|
27.2.4 Readline Arguments
|
27.2.4 Readline Arguments
|
-------------------------
|
-------------------------
|
|
|
You can pass numeric arguments to Readline commands. Sometimes the
|
You can pass numeric arguments to Readline commands. Sometimes the
|
argument acts as a repeat count, other times it is the sign of the
|
argument acts as a repeat count, other times it is the sign of the
|
argument that is significant. If you pass a negative argument to a
|
argument that is significant. If you pass a negative argument to a
|
command which normally acts in a forward direction, that command will
|
command which normally acts in a forward direction, that command will
|
act in a backward direction. For example, to kill text back to the
|
act in a backward direction. For example, to kill text back to the
|
start of the line, you might type `M-- C-k'.
|
start of the line, you might type `M-- C-k'.
|
|
|
The general way to pass numeric arguments to a command is to type
|
The general way to pass numeric arguments to a command is to type
|
meta digits before the command. If the first `digit' typed is a minus
|
meta digits before the command. If the first `digit' typed is a minus
|
sign (`-'), then the sign of the argument will be negative. Once you
|
sign (`-'), then the sign of the argument will be negative. Once you
|
have typed one meta digit to get the argument started, you can type the
|
have typed one meta digit to get the argument started, you can type the
|
remainder of the digits, and then the command. For example, to give
|
remainder of the digits, and then the command. For example, to give
|
the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
|
the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
|
will delete the next ten characters on the input line.
|
will delete the next ten characters on the input line.
|
|
|
|
|
File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
|
File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
|
|
|
27.2.5 Searching for Commands in the History
|
27.2.5 Searching for Commands in the History
|
--------------------------------------------
|
--------------------------------------------
|
|
|
Readline provides commands for searching through the command history
|
Readline provides commands for searching through the command history
|
for lines containing a specified string. There are two search modes:
|
for lines containing a specified string. There are two search modes:
|
"incremental" and "non-incremental".
|
"incremental" and "non-incremental".
|
|
|
Incremental searches begin before the user has finished typing the
|
Incremental searches begin before the user has finished typing the
|
search string. As each character of the search string is typed,
|
search string. As each character of the search string is typed,
|
Readline displays the next entry from the history matching the string
|
Readline displays the next entry from the history matching the string
|
typed so far. An incremental search requires only as many characters
|
typed so far. An incremental search requires only as many characters
|
as needed to find the desired history entry. To search backward in the
|
as needed to find the desired history entry. To search backward in the
|
history for a particular string, type `C-r'. Typing `C-s' searches
|
history for a particular string, type `C-r'. Typing `C-s' searches
|
forward through the history. The characters present in the value of
|
forward through the history. The characters present in the value of
|
the `isearch-terminators' variable are used to terminate an incremental
|
the `isearch-terminators' variable are used to terminate an incremental
|
search. If that variable has not been assigned a value, the and
|
search. If that variable has not been assigned a value, the and
|
`C-J' characters will terminate an incremental search. `C-g' will
|
`C-J' characters will terminate an incremental search. `C-g' will
|
abort an incremental search and restore the original line. When the
|
abort an incremental search and restore the original line. When the
|
search is terminated, the history entry containing the search string
|
search is terminated, the history entry containing the search string
|
becomes the current line.
|
becomes the current line.
|
|
|
To find other matching entries in the history list, type `C-r' or
|
To find other matching entries in the history list, type `C-r' or
|
`C-s' as appropriate. This will search backward or forward in the
|
`C-s' as appropriate. This will search backward or forward in the
|
history for the next entry matching the search string typed so far.
|
history for the next entry matching the search string typed so far.
|
Any other key sequence bound to a Readline command will terminate the
|
Any other key sequence bound to a Readline command will terminate the
|
search and execute that command. For instance, a will terminate
|
search and execute that command. For instance, a will terminate
|
the search and accept the line, thereby executing the command from the
|
the search and accept the line, thereby executing the command from the
|
history list. A movement command will terminate the search, make the
|
history list. A movement command will terminate the search, make the
|
last line found the current line, and begin editing.
|
last line found the current line, and begin editing.
|
|
|
Readline remembers the last incremental search string. If two
|
Readline remembers the last incremental search string. If two
|
`C-r's are typed without any intervening characters defining a new
|
`C-r's are typed without any intervening characters defining a new
|
search string, any remembered search string is used.
|
search string, any remembered search string is used.
|
|
|
Non-incremental searches read the entire search string before
|
Non-incremental searches read the entire search string before
|
starting to search for matching history lines. The search string may be
|
starting to search for matching history lines. The search string may be
|
typed by the user or be part of the contents of the current line.
|
typed by the user or be part of the contents of the current line.
|
|
|
|
|
File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
|
File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
|
|
|
27.3 Readline Init File
|
27.3 Readline Init File
|
=======================
|
=======================
|
|
|
Although the Readline library comes with a set of Emacs-like
|
Although the Readline library comes with a set of Emacs-like
|
keybindings installed by default, it is possible to use a different set
|
keybindings installed by default, it is possible to use a different set
|
of keybindings. Any user can customize programs that use Readline by
|
of keybindings. Any user can customize programs that use Readline by
|
putting commands in an "inputrc" file, conventionally in his home
|
putting commands in an "inputrc" file, conventionally in his home
|
directory. The name of this file is taken from the value of the
|
directory. The name of this file is taken from the value of the
|
environment variable `INPUTRC'. If that variable is unset, the default
|
environment variable `INPUTRC'. If that variable is unset, the default
|
is `~/.inputrc'.
|
is `~/.inputrc'.
|
|
|
When a program which uses the Readline library starts up, the init
|
When a program which uses the Readline library starts up, the init
|
file is read, and the key bindings are set.
|
file is read, and the key bindings are set.
|
|
|
In addition, the `C-x C-r' command re-reads this init file, thus
|
In addition, the `C-x C-r' command re-reads this init file, thus
|
incorporating any changes that you might have made to it.
|
incorporating any changes that you might have made to it.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Readline Init File Syntax:: Syntax for the commands in the inputrc file.
|
* Readline Init File Syntax:: Syntax for the commands in the inputrc file.
|
|
|
* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
|
* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
|
|
|
* Sample Init File:: An example inputrc file.
|
* Sample Init File:: An example inputrc file.
|
|
|
|
|
File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
|
File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
|
|
|
27.3.1 Readline Init File Syntax
|
27.3.1 Readline Init File Syntax
|
--------------------------------
|
--------------------------------
|
|
|
There are only a few basic constructs allowed in the Readline init
|
There are only a few basic constructs allowed in the Readline init
|
file. Blank lines are ignored. Lines beginning with a `#' are
|
file. Blank lines are ignored. Lines beginning with a `#' are
|
comments. Lines beginning with a `$' indicate conditional constructs
|
comments. Lines beginning with a `$' indicate conditional constructs
|
(*note Conditional Init Constructs::). Other lines denote variable
|
(*note Conditional Init Constructs::). Other lines denote variable
|
settings and key bindings.
|
settings and key bindings.
|
|
|
Variable Settings
|
Variable Settings
|
You can modify the run-time behavior of Readline by altering the
|
You can modify the run-time behavior of Readline by altering the
|
values of variables in Readline using the `set' command within the
|
values of variables in Readline using the `set' command within the
|
init file. The syntax is simple:
|
init file. The syntax is simple:
|
|
|
set VARIABLE VALUE
|
set VARIABLE VALUE
|
|
|
Here, for example, is how to change from the default Emacs-like
|
Here, for example, is how to change from the default Emacs-like
|
key binding to use `vi' line editing commands:
|
key binding to use `vi' line editing commands:
|
|
|
set editing-mode vi
|
set editing-mode vi
|
|
|
Variable names and values, where appropriate, are recognized
|
Variable names and values, where appropriate, are recognized
|
without regard to case. Unrecognized variable names are ignored.
|
without regard to case. Unrecognized variable names are ignored.
|
|
|
Boolean variables (those that can be set to on or off) are set to
|
Boolean variables (those that can be set to on or off) are set to
|
on if the value is null or empty, ON (case-insensitive), or 1.
|
on if the value is null or empty, ON (case-insensitive), or 1.
|
Any other value results in the variable being set to off.
|
Any other value results in the variable being set to off.
|
|
|
A great deal of run-time behavior is changeable with the following
|
A great deal of run-time behavior is changeable with the following
|
variables.
|
variables.
|
|
|
`bell-style'
|
`bell-style'
|
Controls what happens when Readline wants to ring the
|
Controls what happens when Readline wants to ring the
|
terminal bell. If set to `none', Readline never rings the
|
terminal bell. If set to `none', Readline never rings the
|
bell. If set to `visible', Readline uses a visible bell if
|
bell. If set to `visible', Readline uses a visible bell if
|
one is available. If set to `audible' (the default),
|
one is available. If set to `audible' (the default),
|
Readline attempts to ring the terminal's bell.
|
Readline attempts to ring the terminal's bell.
|
|
|
`bind-tty-special-chars'
|
`bind-tty-special-chars'
|
If set to `on', Readline attempts to bind the control
|
If set to `on', Readline attempts to bind the control
|
characters treated specially by the kernel's terminal driver
|
characters treated specially by the kernel's terminal driver
|
to their Readline equivalents.
|
to their Readline equivalents.
|
|
|
`comment-begin'
|
`comment-begin'
|
The string to insert at the beginning of the line when the
|
The string to insert at the beginning of the line when the
|
`insert-comment' command is executed. The default value is
|
`insert-comment' command is executed. The default value is
|
`"#"'.
|
`"#"'.
|
|
|
`completion-ignore-case'
|
`completion-ignore-case'
|
If set to `on', Readline performs filename matching and
|
If set to `on', Readline performs filename matching and
|
completion in a case-insensitive fashion. The default value
|
completion in a case-insensitive fashion. The default value
|
is `off'.
|
is `off'.
|
|
|
`completion-query-items'
|
`completion-query-items'
|
The number of possible completions that determines when the
|
The number of possible completions that determines when the
|
user is asked whether the list of possibilities should be
|
user is asked whether the list of possibilities should be
|
displayed. If the number of possible completions is greater
|
displayed. If the number of possible completions is greater
|
than this value, Readline will ask the user whether or not he
|
than this value, Readline will ask the user whether or not he
|
wishes to view them; otherwise, they are simply listed. This
|
wishes to view them; otherwise, they are simply listed. This
|
variable must be set to an integer value greater than or
|
variable must be set to an integer value greater than or
|
equal to 0. A negative value means Readline should never ask.
|
equal to 0. A negative value means Readline should never ask.
|
The default limit is `100'.
|
The default limit is `100'.
|
|
|
`convert-meta'
|
`convert-meta'
|
If set to `on', Readline will convert characters with the
|
If set to `on', Readline will convert characters with the
|
eighth bit set to an ASCII key sequence by stripping the
|
eighth bit set to an ASCII key sequence by stripping the
|
eighth bit and prefixing an character, converting them
|
eighth bit and prefixing an character, converting them
|
to a meta-prefixed key sequence. The default value is `on'.
|
to a meta-prefixed key sequence. The default value is `on'.
|
|
|
`disable-completion'
|
`disable-completion'
|
If set to `On', Readline will inhibit word completion.
|
If set to `On', Readline will inhibit word completion.
|
Completion characters will be inserted into the line as if
|
Completion characters will be inserted into the line as if
|
they had been mapped to `self-insert'. The default is `off'.
|
they had been mapped to `self-insert'. The default is `off'.
|
|
|
`editing-mode'
|
`editing-mode'
|
The `editing-mode' variable controls which default set of key
|
The `editing-mode' variable controls which default set of key
|
bindings is used. By default, Readline starts up in Emacs
|
bindings is used. By default, Readline starts up in Emacs
|
editing mode, where the keystrokes are most similar to Emacs.
|
editing mode, where the keystrokes are most similar to Emacs.
|
This variable can be set to either `emacs' or `vi'.
|
This variable can be set to either `emacs' or `vi'.
|
|
|
`enable-keypad'
|
`enable-keypad'
|
When set to `on', Readline will try to enable the application
|
When set to `on', Readline will try to enable the application
|
keypad when it is called. Some systems need this to enable
|
keypad when it is called. Some systems need this to enable
|
the arrow keys. The default is `off'.
|
the arrow keys. The default is `off'.
|
|
|
`expand-tilde'
|
`expand-tilde'
|
If set to `on', tilde expansion is performed when Readline
|
If set to `on', tilde expansion is performed when Readline
|
attempts word completion. The default is `off'.
|
attempts word completion. The default is `off'.
|
|
|
`history-preserve-point'
|
`history-preserve-point'
|
If set to `on', the history code attempts to place point at
|
If set to `on', the history code attempts to place point at
|
the same location on each history line retrieved with
|
the same location on each history line retrieved with
|
`previous-history' or `next-history'. The default is `off'.
|
`previous-history' or `next-history'. The default is `off'.
|
|
|
`horizontal-scroll-mode'
|
`horizontal-scroll-mode'
|
This variable can be set to either `on' or `off'. Setting it
|
This variable can be set to either `on' or `off'. Setting it
|
to `on' means that the text of the lines being edited will
|
to `on' means that the text of the lines being edited will
|
scroll horizontally on a single screen line when they are
|
scroll horizontally on a single screen line when they are
|
longer than the width of the screen, instead of wrapping onto
|
longer than the width of the screen, instead of wrapping onto
|
a new screen line. By default, this variable is set to `off'.
|
a new screen line. By default, this variable is set to `off'.
|
|
|
`input-meta'
|
`input-meta'
|
If set to `on', Readline will enable eight-bit input (it will
|
If set to `on', Readline will enable eight-bit input (it will
|
not clear the eighth bit in the characters it reads),
|
not clear the eighth bit in the characters it reads),
|
regardless of what the terminal claims it can support. The
|
regardless of what the terminal claims it can support. The
|
default value is `off'. The name `meta-flag' is a synonym
|
default value is `off'. The name `meta-flag' is a synonym
|
for this variable.
|
for this variable.
|
|
|
`isearch-terminators'
|
`isearch-terminators'
|
The string of characters that should terminate an incremental
|
The string of characters that should terminate an incremental
|
search without subsequently executing the character as a
|
search without subsequently executing the character as a
|
command (*note Searching::). If this variable has not been
|
command (*note Searching::). If this variable has not been
|
given a value, the characters and `C-J' will terminate
|
given a value, the characters and `C-J' will terminate
|
an incremental search.
|
an incremental search.
|
|
|
`keymap'
|
`keymap'
|
Sets Readline's idea of the current keymap for key binding
|
Sets Readline's idea of the current keymap for key binding
|
commands. Acceptable `keymap' names are `emacs',
|
commands. Acceptable `keymap' names are `emacs',
|
`emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
|
`emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
|
`vi-command', and `vi-insert'. `vi' is equivalent to
|
`vi-command', and `vi-insert'. `vi' is equivalent to
|
`vi-command'; `emacs' is equivalent to `emacs-standard'. The
|
`vi-command'; `emacs' is equivalent to `emacs-standard'. The
|
default value is `emacs'. The value of the `editing-mode'
|
default value is `emacs'. The value of the `editing-mode'
|
variable also affects the default keymap.
|
variable also affects the default keymap.
|
|
|
`mark-directories'
|
`mark-directories'
|
If set to `on', completed directory names have a slash
|
If set to `on', completed directory names have a slash
|
appended. The default is `on'.
|
appended. The default is `on'.
|
|
|
`mark-modified-lines'
|
`mark-modified-lines'
|
This variable, when set to `on', causes Readline to display an
|
This variable, when set to `on', causes Readline to display an
|
asterisk (`*') at the start of history lines which have been
|
asterisk (`*') at the start of history lines which have been
|
modified. This variable is `off' by default.
|
modified. This variable is `off' by default.
|
|
|
`mark-symlinked-directories'
|
`mark-symlinked-directories'
|
If set to `on', completed names which are symbolic links to
|
If set to `on', completed names which are symbolic links to
|
directories have a slash appended (subject to the value of
|
directories have a slash appended (subject to the value of
|
`mark-directories'). The default is `off'.
|
`mark-directories'). The default is `off'.
|
|
|
`match-hidden-files'
|
`match-hidden-files'
|
This variable, when set to `on', causes Readline to match
|
This variable, when set to `on', causes Readline to match
|
files whose names begin with a `.' (hidden files) when
|
files whose names begin with a `.' (hidden files) when
|
performing filename completion, unless the leading `.' is
|
performing filename completion, unless the leading `.' is
|
supplied by the user in the filename to be completed. This
|
supplied by the user in the filename to be completed. This
|
variable is `on' by default.
|
variable is `on' by default.
|
|
|
`output-meta'
|
`output-meta'
|
If set to `on', Readline will display characters with the
|
If set to `on', Readline will display characters with the
|
eighth bit set directly rather than as a meta-prefixed escape
|
eighth bit set directly rather than as a meta-prefixed escape
|
sequence. The default is `off'.
|
sequence. The default is `off'.
|
|
|
`page-completions'
|
`page-completions'
|
If set to `on', Readline uses an internal `more'-like pager
|
If set to `on', Readline uses an internal `more'-like pager
|
to display a screenful of possible completions at a time.
|
to display a screenful of possible completions at a time.
|
This variable is `on' by default.
|
This variable is `on' by default.
|
|
|
`print-completions-horizontally'
|
`print-completions-horizontally'
|
If set to `on', Readline will display completions with matches
|
If set to `on', Readline will display completions with matches
|
sorted horizontally in alphabetical order, rather than down
|
sorted horizontally in alphabetical order, rather than down
|
the screen. The default is `off'.
|
the screen. The default is `off'.
|
|
|
`show-all-if-ambiguous'
|
`show-all-if-ambiguous'
|
This alters the default behavior of the completion functions.
|
This alters the default behavior of the completion functions.
|
If set to `on', words which have more than one possible
|
If set to `on', words which have more than one possible
|
completion cause the matches to be listed immediately instead
|
completion cause the matches to be listed immediately instead
|
of ringing the bell. The default value is `off'.
|
of ringing the bell. The default value is `off'.
|
|
|
`show-all-if-unmodified'
|
`show-all-if-unmodified'
|
This alters the default behavior of the completion functions
|
This alters the default behavior of the completion functions
|
in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
|
in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
|
`on', words which have more than one possible completion
|
`on', words which have more than one possible completion
|
without any possible partial completion (the possible
|
without any possible partial completion (the possible
|
completions don't share a common prefix) cause the matches to
|
completions don't share a common prefix) cause the matches to
|
be listed immediately instead of ringing the bell. The
|
be listed immediately instead of ringing the bell. The
|
default value is `off'.
|
default value is `off'.
|
|
|
`visible-stats'
|
`visible-stats'
|
If set to `on', a character denoting a file's type is
|
If set to `on', a character denoting a file's type is
|
appended to the filename when listing possible completions.
|
appended to the filename when listing possible completions.
|
The default is `off'.
|
The default is `off'.
|
|
|
|
|
Key Bindings
|
Key Bindings
|
The syntax for controlling key bindings in the init file is
|
The syntax for controlling key bindings in the init file is
|
simple. First you need to find the name of the command that you
|
simple. First you need to find the name of the command that you
|
want to change. The following sections contain tables of the
|
want to change. The following sections contain tables of the
|
command name, the default keybinding, if any, and a short
|
command name, the default keybinding, if any, and a short
|
description of what the command does.
|
description of what the command does.
|
|
|
Once you know the name of the command, simply place on a line in
|
Once you know the name of the command, simply place on a line in
|
the init file the name of the key you wish to bind the command to,
|
the init file the name of the key you wish to bind the command to,
|
a colon, and then the name of the command. The name of the key
|
a colon, and then the name of the command. The name of the key
|
can be expressed in different ways, depending on what you find most
|
can be expressed in different ways, depending on what you find most
|
comfortable.
|
comfortable.
|
|
|
In addition to command names, readline allows keys to be bound to
|
In addition to command names, readline allows keys to be bound to
|
a string that is inserted when the key is pressed (a MACRO).
|
a string that is inserted when the key is pressed (a MACRO).
|
|
|
KEYNAME: FUNCTION-NAME or MACRO
|
KEYNAME: FUNCTION-NAME or MACRO
|
KEYNAME is the name of a key spelled out in English. For
|
KEYNAME is the name of a key spelled out in English. For
|
example:
|
example:
|
Control-u: universal-argument
|
Control-u: universal-argument
|
Meta-Rubout: backward-kill-word
|
Meta-Rubout: backward-kill-word
|
Control-o: "> output"
|
Control-o: "> output"
|
|
|
In the above example, `C-u' is bound to the function
|
In the above example, `C-u' is bound to the function
|
`universal-argument', `M-DEL' is bound to the function
|
`universal-argument', `M-DEL' is bound to the function
|
`backward-kill-word', and `C-o' is bound to run the macro
|
`backward-kill-word', and `C-o' is bound to run the macro
|
expressed on the right hand side (that is, to insert the text
|
expressed on the right hand side (that is, to insert the text
|
`> output' into the line).
|
`> output' into the line).
|
|
|
A number of symbolic character names are recognized while
|
A number of symbolic character names are recognized while
|
processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
|
processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
|
NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
|
NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
|
|
|
"KEYSEQ": FUNCTION-NAME or MACRO
|
"KEYSEQ": FUNCTION-NAME or MACRO
|
KEYSEQ differs from KEYNAME above in that strings denoting an
|
KEYSEQ differs from KEYNAME above in that strings denoting an
|
entire key sequence can be specified, by placing the key
|
entire key sequence can be specified, by placing the key
|
sequence in double quotes. Some GNU Emacs style key escapes
|
sequence in double quotes. Some GNU Emacs style key escapes
|
can be used, as in the following example, but the special
|
can be used, as in the following example, but the special
|
character names are not recognized.
|
character names are not recognized.
|
|
|
"\C-u": universal-argument
|
"\C-u": universal-argument
|
"\C-x\C-r": re-read-init-file
|
"\C-x\C-r": re-read-init-file
|
"\e[11~": "Function Key 1"
|
"\e[11~": "Function Key 1"
|
|
|
In the above example, `C-u' is again bound to the function
|
In the above example, `C-u' is again bound to the function
|
`universal-argument' (just as it was in the first example),
|
`universal-argument' (just as it was in the first example),
|
`C-x C-r' is bound to the function `re-read-init-file', and
|
`C-x C-r' is bound to the function `re-read-init-file', and
|
` <[> <1> <1> <~>' is bound to insert the text `Function
|
` <[> <1> <1> <~>' is bound to insert the text `Function
|
Key 1'.
|
Key 1'.
|
|
|
|
|
The following GNU Emacs style escape sequences are available when
|
The following GNU Emacs style escape sequences are available when
|
specifying key sequences:
|
specifying key sequences:
|
|
|
`\C-'
|
`\C-'
|
control prefix
|
control prefix
|
|
|
`\M-'
|
`\M-'
|
meta prefix
|
meta prefix
|
|
|
`\e'
|
`\e'
|
an escape character
|
an escape character
|
|
|
`\\'
|
`\\'
|
backslash
|
backslash
|
|
|
`\"'
|
`\"'
|
<">, a double quotation mark
|
<">, a double quotation mark
|
|
|
`\''
|
`\''
|
<'>, a single quote or apostrophe
|
<'>, a single quote or apostrophe
|
|
|
In addition to the GNU Emacs style escape sequences, a second set
|
In addition to the GNU Emacs style escape sequences, a second set
|
of backslash escapes is available:
|
of backslash escapes is available:
|
|
|
`\a'
|
`\a'
|
alert (bell)
|
alert (bell)
|
|
|
`\b'
|
`\b'
|
backspace
|
backspace
|
|
|
`\d'
|
`\d'
|
delete
|
delete
|
|
|
`\f'
|
`\f'
|
form feed
|
form feed
|
|
|
`\n'
|
`\n'
|
newline
|
newline
|
|
|
`\r'
|
`\r'
|
carriage return
|
carriage return
|
|
|
`\t'
|
`\t'
|
horizontal tab
|
horizontal tab
|
|
|
`\v'
|
`\v'
|
vertical tab
|
vertical tab
|
|
|
`\NNN'
|
`\NNN'
|
the eight-bit character whose value is the octal value NNN
|
the eight-bit character whose value is the octal value NNN
|
(one to three digits)
|
(one to three digits)
|
|
|
`\xHH'
|
`\xHH'
|
the eight-bit character whose value is the hexadecimal value
|
the eight-bit character whose value is the hexadecimal value
|
HH (one or two hex digits)
|
HH (one or two hex digits)
|
|
|
When entering the text of a macro, single or double quotes must be
|
When entering the text of a macro, single or double quotes must be
|
used to indicate a macro definition. Unquoted text is assumed to
|
used to indicate a macro definition. Unquoted text is assumed to
|
be a function name. In the macro body, the backslash escapes
|
be a function name. In the macro body, the backslash escapes
|
described above are expanded. Backslash will quote any other
|
described above are expanded. Backslash will quote any other
|
character in the macro text, including `"' and `''. For example,
|
character in the macro text, including `"' and `''. For example,
|
the following binding will make `C-x \' insert a single `\' into
|
the following binding will make `C-x \' insert a single `\' into
|
the line:
|
the line:
|
"\C-x\\": "\\"
|
"\C-x\\": "\\"
|
|
|
|
|
|
|
File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
|
File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
|
|
|
27.3.2 Conditional Init Constructs
|
27.3.2 Conditional Init Constructs
|
----------------------------------
|
----------------------------------
|
|
|
Readline implements a facility similar in spirit to the conditional
|
Readline implements a facility similar in spirit to the conditional
|
compilation features of the C preprocessor which allows key bindings
|
compilation features of the C preprocessor which allows key bindings
|
and variable settings to be performed as the result of tests. There
|
and variable settings to be performed as the result of tests. There
|
are four parser directives used.
|
are four parser directives used.
|
|
|
`$if'
|
`$if'
|
The `$if' construct allows bindings to be made based on the
|
The `$if' construct allows bindings to be made based on the
|
editing mode, the terminal being used, or the application using
|
editing mode, the terminal being used, or the application using
|
Readline. The text of the test extends to the end of the line; no
|
Readline. The text of the test extends to the end of the line; no
|
characters are required to isolate it.
|
characters are required to isolate it.
|
|
|
`mode'
|
`mode'
|
The `mode=' form of the `$if' directive is used to test
|
The `mode=' form of the `$if' directive is used to test
|
whether Readline is in `emacs' or `vi' mode. This may be
|
whether Readline is in `emacs' or `vi' mode. This may be
|
used in conjunction with the `set keymap' command, for
|
used in conjunction with the `set keymap' command, for
|
instance, to set bindings in the `emacs-standard' and
|
instance, to set bindings in the `emacs-standard' and
|
`emacs-ctlx' keymaps only if Readline is starting out in
|
`emacs-ctlx' keymaps only if Readline is starting out in
|
`emacs' mode.
|
`emacs' mode.
|
|
|
`term'
|
`term'
|
The `term=' form may be used to include terminal-specific key
|
The `term=' form may be used to include terminal-specific key
|
bindings, perhaps to bind the key sequences output by the
|
bindings, perhaps to bind the key sequences output by the
|
terminal's function keys. The word on the right side of the
|
terminal's function keys. The word on the right side of the
|
`=' is tested against both the full name of the terminal and
|
`=' is tested against both the full name of the terminal and
|
the portion of the terminal name before the first `-'. This
|
the portion of the terminal name before the first `-'. This
|
allows `sun' to match both `sun' and `sun-cmd', for instance.
|
allows `sun' to match both `sun' and `sun-cmd', for instance.
|
|
|
`application'
|
`application'
|
The APPLICATION construct is used to include
|
The APPLICATION construct is used to include
|
application-specific settings. Each program using the
|
application-specific settings. Each program using the
|
Readline library sets the APPLICATION NAME, and you can test
|
Readline library sets the APPLICATION NAME, and you can test
|
for a particular value. This could be used to bind key
|
for a particular value. This could be used to bind key
|
sequences to functions useful for a specific program. For
|
sequences to functions useful for a specific program. For
|
instance, the following command adds a key sequence that
|
instance, the following command adds a key sequence that
|
quotes the current or previous word in Bash:
|
quotes the current or previous word in Bash:
|
$if Bash
|
$if Bash
|
# Quote the current or previous word
|
# Quote the current or previous word
|
"\C-xq": "\eb\"\ef\""
|
"\C-xq": "\eb\"\ef\""
|
$endif
|
$endif
|
|
|
`$endif'
|
`$endif'
|
This command, as seen in the previous example, terminates an `$if'
|
This command, as seen in the previous example, terminates an `$if'
|
command.
|
command.
|
|
|
`$else'
|
`$else'
|
Commands in this branch of the `$if' directive are executed if the
|
Commands in this branch of the `$if' directive are executed if the
|
test fails.
|
test fails.
|
|
|
`$include'
|
`$include'
|
This directive takes a single filename as an argument and reads
|
This directive takes a single filename as an argument and reads
|
commands and bindings from that file. For example, the following
|
commands and bindings from that file. For example, the following
|
directive reads from `/etc/inputrc':
|
directive reads from `/etc/inputrc':
|
$include /etc/inputrc
|
$include /etc/inputrc
|
|
|
|
|
File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
|
File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
|
|
|
27.3.3 Sample Init File
|
27.3.3 Sample Init File
|
-----------------------
|
-----------------------
|
|
|
Here is an example of an INPUTRC file. This illustrates key binding,
|
Here is an example of an INPUTRC file. This illustrates key binding,
|
variable assignment, and conditional syntax.
|
variable assignment, and conditional syntax.
|
|
|
|
|
# This file controls the behaviour of line input editing for
|
# This file controls the behaviour of line input editing for
|
# programs that use the GNU Readline library. Existing
|
# programs that use the GNU Readline library. Existing
|
# programs include FTP, Bash, and GDB.
|
# programs include FTP, Bash, and GDB.
|
#
|
#
|
# You can re-read the inputrc file with C-x C-r.
|
# You can re-read the inputrc file with C-x C-r.
|
# Lines beginning with '#' are comments.
|
# Lines beginning with '#' are comments.
|
#
|
#
|
# First, include any systemwide bindings and variable
|
# First, include any systemwide bindings and variable
|
# assignments from /etc/Inputrc
|
# assignments from /etc/Inputrc
|
$include /etc/Inputrc
|
$include /etc/Inputrc
|
|
|
#
|
#
|
# Set various bindings for emacs mode.
|
# Set various bindings for emacs mode.
|
|
|
set editing-mode emacs
|
set editing-mode emacs
|
|
|
$if mode=emacs
|
$if mode=emacs
|
|
|
Meta-Control-h: backward-kill-word Text after the function name is ignored
|
Meta-Control-h: backward-kill-word Text after the function name is ignored
|
|
|
#
|
#
|
# Arrow keys in keypad mode
|
# Arrow keys in keypad mode
|
#
|
#
|
#"\M-OD": backward-char
|
#"\M-OD": backward-char
|
#"\M-OC": forward-char
|
#"\M-OC": forward-char
|
#"\M-OA": previous-history
|
#"\M-OA": previous-history
|
#"\M-OB": next-history
|
#"\M-OB": next-history
|
#
|
#
|
# Arrow keys in ANSI mode
|
# Arrow keys in ANSI mode
|
#
|
#
|
"\M-[D": backward-char
|
"\M-[D": backward-char
|
"\M-[C": forward-char
|
"\M-[C": forward-char
|
"\M-[A": previous-history
|
"\M-[A": previous-history
|
"\M-[B": next-history
|
"\M-[B": next-history
|
#
|
#
|
# Arrow keys in 8 bit keypad mode
|
# Arrow keys in 8 bit keypad mode
|
#
|
#
|
#"\M-\C-OD": backward-char
|
#"\M-\C-OD": backward-char
|
#"\M-\C-OC": forward-char
|
#"\M-\C-OC": forward-char
|
#"\M-\C-OA": previous-history
|
#"\M-\C-OA": previous-history
|
#"\M-\C-OB": next-history
|
#"\M-\C-OB": next-history
|
#
|
#
|
# Arrow keys in 8 bit ANSI mode
|
# Arrow keys in 8 bit ANSI mode
|
#
|
#
|
#"\M-\C-[D": backward-char
|
#"\M-\C-[D": backward-char
|
#"\M-\C-[C": forward-char
|
#"\M-\C-[C": forward-char
|
#"\M-\C-[A": previous-history
|
#"\M-\C-[A": previous-history
|
#"\M-\C-[B": next-history
|
#"\M-\C-[B": next-history
|
|
|
C-q: quoted-insert
|
C-q: quoted-insert
|
|
|
$endif
|
$endif
|
|
|
# An old-style binding. This happens to be the default.
|
# An old-style binding. This happens to be the default.
|
TAB: complete
|
TAB: complete
|
|
|
# Macros that are convenient for shell interaction
|
# Macros that are convenient for shell interaction
|
$if Bash
|
$if Bash
|
# edit the path
|
# edit the path
|
"\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
|
"\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
|
# prepare to type a quoted word --
|
# prepare to type a quoted word --
|
# insert open and close double quotes
|
# insert open and close double quotes
|
# and move to just after the open quote
|
# and move to just after the open quote
|
"\C-x\"": "\"\"\C-b"
|
"\C-x\"": "\"\"\C-b"
|
# insert a backslash (testing backslash escapes
|
# insert a backslash (testing backslash escapes
|
# in sequences and macros)
|
# in sequences and macros)
|
"\C-x\\": "\\"
|
"\C-x\\": "\\"
|
# Quote the current or previous word
|
# Quote the current or previous word
|
"\C-xq": "\eb\"\ef\""
|
"\C-xq": "\eb\"\ef\""
|
# Add a binding to refresh the line, which is unbound
|
# Add a binding to refresh the line, which is unbound
|
"\C-xr": redraw-current-line
|
"\C-xr": redraw-current-line
|
# Edit variable on current line.
|
# Edit variable on current line.
|
"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
|
"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
|
$endif
|
$endif
|
|
|
# use a visible bell if one is available
|
# use a visible bell if one is available
|
set bell-style visible
|
set bell-style visible
|
|
|
# don't strip characters to 7 bits when reading
|
# don't strip characters to 7 bits when reading
|
set input-meta on
|
set input-meta on
|
|
|
# allow iso-latin1 characters to be inserted rather
|
# allow iso-latin1 characters to be inserted rather
|
# than converted to prefix-meta sequences
|
# than converted to prefix-meta sequences
|
set convert-meta off
|
set convert-meta off
|
|
|
# display characters with the eighth bit set directly
|
# display characters with the eighth bit set directly
|
# rather than as meta-prefixed characters
|
# rather than as meta-prefixed characters
|
set output-meta on
|
set output-meta on
|
|
|
# if there are more than 150 possible completions for
|
# if there are more than 150 possible completions for
|
# a word, ask the user if he wants to see all of them
|
# a word, ask the user if he wants to see all of them
|
set completion-query-items 150
|
set completion-query-items 150
|
|
|
# For FTP
|
# For FTP
|
$if Ftp
|
$if Ftp
|
"\C-xg": "get \M-?"
|
"\C-xg": "get \M-?"
|
"\C-xt": "put \M-?"
|
"\C-xt": "put \M-?"
|
"\M-.": yank-last-arg
|
"\M-.": yank-last-arg
|
$endif
|
$endif
|
|
|
|
|
File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
|
File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
|
|
|
27.4 Bindable Readline Commands
|
27.4 Bindable Readline Commands
|
===============================
|
===============================
|
|
|
* Menu:
|
* Menu:
|
|
|
* Commands For Moving:: Moving about the line.
|
* Commands For Moving:: Moving about the line.
|
* Commands For History:: Getting at previous lines.
|
* Commands For History:: Getting at previous lines.
|
* Commands For Text:: Commands for changing text.
|
* Commands For Text:: Commands for changing text.
|
* Commands For Killing:: Commands for killing and yanking.
|
* Commands For Killing:: Commands for killing and yanking.
|
* Numeric Arguments:: Specifying numeric arguments, repeat counts.
|
* Numeric Arguments:: Specifying numeric arguments, repeat counts.
|
* Commands For Completion:: Getting Readline to do the typing for you.
|
* Commands For Completion:: Getting Readline to do the typing for you.
|
* Keyboard Macros:: Saving and re-executing typed characters
|
* Keyboard Macros:: Saving and re-executing typed characters
|
* Miscellaneous Commands:: Other miscellaneous commands.
|
* Miscellaneous Commands:: Other miscellaneous commands.
|
|
|
This section describes Readline commands that may be bound to key
|
This section describes Readline commands that may be bound to key
|
sequences. Command names without an accompanying key sequence are
|
sequences. Command names without an accompanying key sequence are
|
unbound by default.
|
unbound by default.
|
|
|
In the following descriptions, "point" refers to the current cursor
|
In the following descriptions, "point" refers to the current cursor
|
position, and "mark" refers to a cursor position saved by the
|
position, and "mark" refers to a cursor position saved by the
|
`set-mark' command. The text between the point and mark is referred to
|
`set-mark' command. The text between the point and mark is referred to
|
as the "region".
|
as the "region".
|
|
|
|
|
File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
|
File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
|
|
|
27.4.1 Commands For Moving
|
27.4.1 Commands For Moving
|
--------------------------
|
--------------------------
|
|
|
`beginning-of-line (C-a)'
|
`beginning-of-line (C-a)'
|
Move to the start of the current line.
|
Move to the start of the current line.
|
|
|
`end-of-line (C-e)'
|
`end-of-line (C-e)'
|
Move to the end of the line.
|
Move to the end of the line.
|
|
|
`forward-char (C-f)'
|
`forward-char (C-f)'
|
Move forward a character.
|
Move forward a character.
|
|
|
`backward-char (C-b)'
|
`backward-char (C-b)'
|
Move back a character.
|
Move back a character.
|
|
|
`forward-word (M-f)'
|
`forward-word (M-f)'
|
Move forward to the end of the next word. Words are composed of
|
Move forward to the end of the next word. Words are composed of
|
letters and digits.
|
letters and digits.
|
|
|
`backward-word (M-b)'
|
`backward-word (M-b)'
|
Move back to the start of the current or previous word. Words are
|
Move back to the start of the current or previous word. Words are
|
composed of letters and digits.
|
composed of letters and digits.
|
|
|
`clear-screen (C-l)'
|
`clear-screen (C-l)'
|
Clear the screen and redraw the current line, leaving the current
|
Clear the screen and redraw the current line, leaving the current
|
line at the top of the screen.
|
line at the top of the screen.
|
|
|
`redraw-current-line ()'
|
`redraw-current-line ()'
|
Refresh the current line. By default, this is unbound.
|
Refresh the current line. By default, this is unbound.
|
|
|
|
|
|
|
File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
|
File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
|
|
|
27.4.2 Commands For Manipulating The History
|
27.4.2 Commands For Manipulating The History
|
--------------------------------------------
|
--------------------------------------------
|
|
|
`accept-line (Newline or Return)'
|
`accept-line (Newline or Return)'
|
Accept the line regardless of where the cursor is. If this line is
|
Accept the line regardless of where the cursor is. If this line is
|
non-empty, it may be added to the history list for future recall
|
non-empty, it may be added to the history list for future recall
|
with `add_history()'. If this line is a modified history line,
|
with `add_history()'. If this line is a modified history line,
|
the history line is restored to its original state.
|
the history line is restored to its original state.
|
|
|
`previous-history (C-p)'
|
`previous-history (C-p)'
|
Move `back' through the history list, fetching the previous
|
Move `back' through the history list, fetching the previous
|
command.
|
command.
|
|
|
`next-history (C-n)'
|
`next-history (C-n)'
|
Move `forward' through the history list, fetching the next command.
|
Move `forward' through the history list, fetching the next command.
|
|
|
`beginning-of-history (M-<)'
|
`beginning-of-history (M-<)'
|
Move to the first line in the history.
|
Move to the first line in the history.
|
|
|
`end-of-history (M->)'
|
`end-of-history (M->)'
|
Move to the end of the input history, i.e., the line currently
|
Move to the end of the input history, i.e., the line currently
|
being entered.
|
being entered.
|
|
|
`reverse-search-history (C-r)'
|
`reverse-search-history (C-r)'
|
Search backward starting at the current line and moving `up'
|
Search backward starting at the current line and moving `up'
|
through the history as necessary. This is an incremental search.
|
through the history as necessary. This is an incremental search.
|
|
|
`forward-search-history (C-s)'
|
`forward-search-history (C-s)'
|
Search forward starting at the current line and moving `down'
|
Search forward starting at the current line and moving `down'
|
through the the history as necessary. This is an incremental
|
through the the history as necessary. This is an incremental
|
search.
|
search.
|
|
|
`non-incremental-reverse-search-history (M-p)'
|
`non-incremental-reverse-search-history (M-p)'
|
Search backward starting at the current line and moving `up'
|
Search backward starting at the current line and moving `up'
|
through the history as necessary using a non-incremental search
|
through the history as necessary using a non-incremental search
|
for a string supplied by the user.
|
for a string supplied by the user.
|
|
|
`non-incremental-forward-search-history (M-n)'
|
`non-incremental-forward-search-history (M-n)'
|
Search forward starting at the current line and moving `down'
|
Search forward starting at the current line and moving `down'
|
through the the history as necessary using a non-incremental search
|
through the the history as necessary using a non-incremental search
|
for a string supplied by the user.
|
for a string supplied by the user.
|
|
|
`history-search-forward ()'
|
`history-search-forward ()'
|
Search forward through the history for the string of characters
|
Search forward through the history for the string of characters
|
between the start of the current line and the point. This is a
|
between the start of the current line and the point. This is a
|
non-incremental search. By default, this command is unbound.
|
non-incremental search. By default, this command is unbound.
|
|
|
`history-search-backward ()'
|
`history-search-backward ()'
|
Search backward through the history for the string of characters
|
Search backward through the history for the string of characters
|
between the start of the current line and the point. This is a
|
between the start of the current line and the point. This is a
|
non-incremental search. By default, this command is unbound.
|
non-incremental search. By default, this command is unbound.
|
|
|
`yank-nth-arg (M-C-y)'
|
`yank-nth-arg (M-C-y)'
|
Insert the first argument to the previous command (usually the
|
Insert the first argument to the previous command (usually the
|
second word on the previous line) at point. With an argument N,
|
second word on the previous line) at point. With an argument N,
|
insert the Nth word from the previous command (the words in the
|
insert the Nth word from the previous command (the words in the
|
previous command begin with word 0). A negative argument inserts
|
previous command begin with word 0). A negative argument inserts
|
the Nth word from the end of the previous command. Once the
|
the Nth word from the end of the previous command. Once the
|
argument N is computed, the argument is extracted as if the `!N'
|
argument N is computed, the argument is extracted as if the `!N'
|
history expansion had been specified.
|
history expansion had been specified.
|
|
|
`yank-last-arg (M-. or M-_)'
|
`yank-last-arg (M-. or M-_)'
|
Insert last argument to the previous command (the last word of the
|
Insert last argument to the previous command (the last word of the
|
previous history entry). With an argument, behave exactly like
|
previous history entry). With an argument, behave exactly like
|
`yank-nth-arg'. Successive calls to `yank-last-arg' move back
|
`yank-nth-arg'. Successive calls to `yank-last-arg' move back
|
through the history list, inserting the last argument of each line
|
through the history list, inserting the last argument of each line
|
in turn. The history expansion facilities are used to extract the
|
in turn. The history expansion facilities are used to extract the
|
last argument, as if the `!$' history expansion had been specified.
|
last argument, as if the `!$' history expansion had been specified.
|
|
|
|
|
|
|
File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
|
File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
|
|
|
27.4.3 Commands For Changing Text
|
27.4.3 Commands For Changing Text
|
---------------------------------
|
---------------------------------
|
|
|
`delete-char (C-d)'
|
`delete-char (C-d)'
|
Delete the character at point. If point is at the beginning of
|
Delete the character at point. If point is at the beginning of
|
the line, there are no characters in the line, and the last
|
the line, there are no characters in the line, and the last
|
character typed was not bound to `delete-char', then return EOF.
|
character typed was not bound to `delete-char', then return EOF.
|
|
|
`backward-delete-char (Rubout)'
|
`backward-delete-char (Rubout)'
|
Delete the character behind the cursor. A numeric argument means
|
Delete the character behind the cursor. A numeric argument means
|
to kill the characters instead of deleting them.
|
to kill the characters instead of deleting them.
|
|
|
`forward-backward-delete-char ()'
|
`forward-backward-delete-char ()'
|
Delete the character under the cursor, unless the cursor is at the
|
Delete the character under the cursor, unless the cursor is at the
|
end of the line, in which case the character behind the cursor is
|
end of the line, in which case the character behind the cursor is
|
deleted. By default, this is not bound to a key.
|
deleted. By default, this is not bound to a key.
|
|
|
`quoted-insert (C-q or C-v)'
|
`quoted-insert (C-q or C-v)'
|
Add the next character typed to the line verbatim. This is how to
|
Add the next character typed to the line verbatim. This is how to
|
insert key sequences like `C-q', for example.
|
insert key sequences like `C-q', for example.
|
|
|
`tab-insert (M-)'
|
`tab-insert (M-)'
|
Insert a tab character.
|
Insert a tab character.
|
|
|
`self-insert (a, b, A, 1, !, ...)'
|
`self-insert (a, b, A, 1, !, ...)'
|
Insert yourself.
|
Insert yourself.
|
|
|
`transpose-chars (C-t)'
|
`transpose-chars (C-t)'
|
Drag the character before the cursor forward over the character at
|
Drag the character before the cursor forward over the character at
|
the cursor, moving the cursor forward as well. If the insertion
|
the cursor, moving the cursor forward as well. If the insertion
|
point is at the end of the line, then this transposes the last two
|
point is at the end of the line, then this transposes the last two
|
characters of the line. Negative arguments have no effect.
|
characters of the line. Negative arguments have no effect.
|
|
|
`transpose-words (M-t)'
|
`transpose-words (M-t)'
|
Drag the word before point past the word after point, moving point
|
Drag the word before point past the word after point, moving point
|
past that word as well. If the insertion point is at the end of
|
past that word as well. If the insertion point is at the end of
|
the line, this transposes the last two words on the line.
|
the line, this transposes the last two words on the line.
|
|
|
`upcase-word (M-u)'
|
`upcase-word (M-u)'
|
Uppercase the current (or following) word. With a negative
|
Uppercase the current (or following) word. With a negative
|
argument, uppercase the previous word, but do not move the cursor.
|
argument, uppercase the previous word, but do not move the cursor.
|
|
|
`downcase-word (M-l)'
|
`downcase-word (M-l)'
|
Lowercase the current (or following) word. With a negative
|
Lowercase the current (or following) word. With a negative
|
argument, lowercase the previous word, but do not move the cursor.
|
argument, lowercase the previous word, but do not move the cursor.
|
|
|
`capitalize-word (M-c)'
|
`capitalize-word (M-c)'
|
Capitalize the current (or following) word. With a negative
|
Capitalize the current (or following) word. With a negative
|
argument, capitalize the previous word, but do not move the cursor.
|
argument, capitalize the previous word, but do not move the cursor.
|
|
|
`overwrite-mode ()'
|
`overwrite-mode ()'
|
Toggle overwrite mode. With an explicit positive numeric argument,
|
Toggle overwrite mode. With an explicit positive numeric argument,
|
switches to overwrite mode. With an explicit non-positive numeric
|
switches to overwrite mode. With an explicit non-positive numeric
|
argument, switches to insert mode. This command affects only
|
argument, switches to insert mode. This command affects only
|
`emacs' mode; `vi' mode does overwrite differently. Each call to
|
`emacs' mode; `vi' mode does overwrite differently. Each call to
|
`readline()' starts in insert mode.
|
`readline()' starts in insert mode.
|
|
|
In overwrite mode, characters bound to `self-insert' replace the
|
In overwrite mode, characters bound to `self-insert' replace the
|
text at point rather than pushing the text to the right.
|
text at point rather than pushing the text to the right.
|
Characters bound to `backward-delete-char' replace the character
|
Characters bound to `backward-delete-char' replace the character
|
before point with a space.
|
before point with a space.
|
|
|
By default, this command is unbound.
|
By default, this command is unbound.
|
|
|
|
|
|
|
File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
|
File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
|
|
|
27.4.4 Killing And Yanking
|
27.4.4 Killing And Yanking
|
--------------------------
|
--------------------------
|
|
|
`kill-line (C-k)'
|
`kill-line (C-k)'
|
Kill the text from point to the end of the line.
|
Kill the text from point to the end of the line.
|
|
|
`backward-kill-line (C-x Rubout)'
|
`backward-kill-line (C-x Rubout)'
|
Kill backward to the beginning of the line.
|
Kill backward to the beginning of the line.
|
|
|
`unix-line-discard (C-u)'
|
`unix-line-discard (C-u)'
|
Kill backward from the cursor to the beginning of the current line.
|
Kill backward from the cursor to the beginning of the current line.
|
|
|
`kill-whole-line ()'
|
`kill-whole-line ()'
|
Kill all characters on the current line, no matter where point is.
|
Kill all characters on the current line, no matter where point is.
|
By default, this is unbound.
|
By default, this is unbound.
|
|
|
`kill-word (M-d)'
|
`kill-word (M-d)'
|
Kill from point to the end of the current word, or if between
|
Kill from point to the end of the current word, or if between
|
words, to the end of the next word. Word boundaries are the same
|
words, to the end of the next word. Word boundaries are the same
|
as `forward-word'.
|
as `forward-word'.
|
|
|
`backward-kill-word (M-)'
|
`backward-kill-word (M-)'
|
Kill the word behind point. Word boundaries are the same as
|
Kill the word behind point. Word boundaries are the same as
|
`backward-word'.
|
`backward-word'.
|
|
|
`unix-word-rubout (C-w)'
|
`unix-word-rubout (C-w)'
|
Kill the word behind point, using white space as a word boundary.
|
Kill the word behind point, using white space as a word boundary.
|
The killed text is saved on the kill-ring.
|
The killed text is saved on the kill-ring.
|
|
|
`unix-filename-rubout ()'
|
`unix-filename-rubout ()'
|
Kill the word behind point, using white space and the slash
|
Kill the word behind point, using white space and the slash
|
character as the word boundaries. The killed text is saved on the
|
character as the word boundaries. The killed text is saved on the
|
kill-ring.
|
kill-ring.
|
|
|
`delete-horizontal-space ()'
|
`delete-horizontal-space ()'
|
Delete all spaces and tabs around point. By default, this is
|
Delete all spaces and tabs around point. By default, this is
|
unbound.
|
unbound.
|
|
|
`kill-region ()'
|
`kill-region ()'
|
Kill the text in the current region. By default, this command is
|
Kill the text in the current region. By default, this command is
|
unbound.
|
unbound.
|
|
|
`copy-region-as-kill ()'
|
`copy-region-as-kill ()'
|
Copy the text in the region to the kill buffer, so it can be yanked
|
Copy the text in the region to the kill buffer, so it can be yanked
|
right away. By default, this command is unbound.
|
right away. By default, this command is unbound.
|
|
|
`copy-backward-word ()'
|
`copy-backward-word ()'
|
Copy the word before point to the kill buffer. The word
|
Copy the word before point to the kill buffer. The word
|
boundaries are the same as `backward-word'. By default, this
|
boundaries are the same as `backward-word'. By default, this
|
command is unbound.
|
command is unbound.
|
|
|
`copy-forward-word ()'
|
`copy-forward-word ()'
|
Copy the word following point to the kill buffer. The word
|
Copy the word following point to the kill buffer. The word
|
boundaries are the same as `forward-word'. By default, this
|
boundaries are the same as `forward-word'. By default, this
|
command is unbound.
|
command is unbound.
|
|
|
`yank (C-y)'
|
`yank (C-y)'
|
Yank the top of the kill ring into the buffer at point.
|
Yank the top of the kill ring into the buffer at point.
|
|
|
`yank-pop (M-y)'
|
`yank-pop (M-y)'
|
Rotate the kill-ring, and yank the new top. You can only do this
|
Rotate the kill-ring, and yank the new top. You can only do this
|
if the prior command is `yank' or `yank-pop'.
|
if the prior command is `yank' or `yank-pop'.
|
|
|
|
|
File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
|
File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
|
|
|
27.4.5 Specifying Numeric Arguments
|
27.4.5 Specifying Numeric Arguments
|
-----------------------------------
|
-----------------------------------
|
|
|
`digit-argument (M-0, M-1, ... M--)'
|
`digit-argument (M-0, M-1, ... M--)'
|
Add this digit to the argument already accumulating, or start a new
|
Add this digit to the argument already accumulating, or start a new
|
argument. `M--' starts a negative argument.
|
argument. `M--' starts a negative argument.
|
|
|
`universal-argument ()'
|
`universal-argument ()'
|
This is another way to specify an argument. If this command is
|
This is another way to specify an argument. If this command is
|
followed by one or more digits, optionally with a leading minus
|
followed by one or more digits, optionally with a leading minus
|
sign, those digits define the argument. If the command is
|
sign, those digits define the argument. If the command is
|
followed by digits, executing `universal-argument' again ends the
|
followed by digits, executing `universal-argument' again ends the
|
numeric argument, but is otherwise ignored. As a special case, if
|
numeric argument, but is otherwise ignored. As a special case, if
|
this command is immediately followed by a character that is
|
this command is immediately followed by a character that is
|
neither a digit or minus sign, the argument count for the next
|
neither a digit or minus sign, the argument count for the next
|
command is multiplied by four. The argument count is initially
|
command is multiplied by four. The argument count is initially
|
one, so executing this function the first time makes the argument
|
one, so executing this function the first time makes the argument
|
count four, a second time makes the argument count sixteen, and so
|
count four, a second time makes the argument count sixteen, and so
|
on. By default, this is not bound to a key.
|
on. By default, this is not bound to a key.
|
|
|
|
|
File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
|
File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
|
|
|
27.4.6 Letting Readline Type For You
|
27.4.6 Letting Readline Type For You
|
------------------------------------
|
------------------------------------
|
|
|
`complete ()'
|
`complete ()'
|
Attempt to perform completion on the text before point. The
|
Attempt to perform completion on the text before point. The
|
actual completion performed is application-specific. The default
|
actual completion performed is application-specific. The default
|
is filename completion.
|
is filename completion.
|
|
|
`possible-completions (M-?)'
|
`possible-completions (M-?)'
|
List the possible completions of the text before point.
|
List the possible completions of the text before point.
|
|
|
`insert-completions (M-*)'
|
`insert-completions (M-*)'
|
Insert all completions of the text before point that would have
|
Insert all completions of the text before point that would have
|
been generated by `possible-completions'.
|
been generated by `possible-completions'.
|
|
|
`menu-complete ()'
|
`menu-complete ()'
|
Similar to `complete', but replaces the word to be completed with
|
Similar to `complete', but replaces the word to be completed with
|
a single match from the list of possible completions. Repeated
|
a single match from the list of possible completions. Repeated
|
execution of `menu-complete' steps through the list of possible
|
execution of `menu-complete' steps through the list of possible
|
completions, inserting each match in turn. At the end of the list
|
completions, inserting each match in turn. At the end of the list
|
of completions, the bell is rung (subject to the setting of
|
of completions, the bell is rung (subject to the setting of
|
`bell-style') and the original text is restored. An argument of N
|
`bell-style') and the original text is restored. An argument of N
|
moves N positions forward in the list of matches; a negative
|
moves N positions forward in the list of matches; a negative
|
argument may be used to move backward through the list. This
|
argument may be used to move backward through the list. This
|
command is intended to be bound to , but is unbound by
|
command is intended to be bound to , but is unbound by
|
default.
|
default.
|
|
|
`delete-char-or-list ()'
|
`delete-char-or-list ()'
|
Deletes the character under the cursor if not at the beginning or
|
Deletes the character under the cursor if not at the beginning or
|
end of the line (like `delete-char'). If at the end of the line,
|
end of the line (like `delete-char'). If at the end of the line,
|
behaves identically to `possible-completions'. This command is
|
behaves identically to `possible-completions'. This command is
|
unbound by default.
|
unbound by default.
|
|
|
|
|
|
|
File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
|
File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
|
|
|
27.4.7 Keyboard Macros
|
27.4.7 Keyboard Macros
|
----------------------
|
----------------------
|
|
|
`start-kbd-macro (C-x ()'
|
`start-kbd-macro (C-x ()'
|
Begin saving the characters typed into the current keyboard macro.
|
Begin saving the characters typed into the current keyboard macro.
|
|
|
`end-kbd-macro (C-x ))'
|
`end-kbd-macro (C-x ))'
|
Stop saving the characters typed into the current keyboard macro
|
Stop saving the characters typed into the current keyboard macro
|
and save the definition.
|
and save the definition.
|
|
|
`call-last-kbd-macro (C-x e)'
|
`call-last-kbd-macro (C-x e)'
|
Re-execute the last keyboard macro defined, by making the
|
Re-execute the last keyboard macro defined, by making the
|
characters in the macro appear as if typed at the keyboard.
|
characters in the macro appear as if typed at the keyboard.
|
|
|
|
|
|
|
File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
|
File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
|
|
|
27.4.8 Some Miscellaneous Commands
|
27.4.8 Some Miscellaneous Commands
|
----------------------------------
|
----------------------------------
|
|
|
`re-read-init-file (C-x C-r)'
|
`re-read-init-file (C-x C-r)'
|
Read in the contents of the INPUTRC file, and incorporate any
|
Read in the contents of the INPUTRC file, and incorporate any
|
bindings or variable assignments found there.
|
bindings or variable assignments found there.
|
|
|
`abort (C-g)'
|
`abort (C-g)'
|
Abort the current editing command and ring the terminal's bell
|
Abort the current editing command and ring the terminal's bell
|
(subject to the setting of `bell-style').
|
(subject to the setting of `bell-style').
|
|
|
`do-uppercase-version (M-a, M-b, M-X, ...)'
|
`do-uppercase-version (M-a, M-b, M-X, ...)'
|
If the metafied character X is lowercase, run the command that is
|
If the metafied character X is lowercase, run the command that is
|
bound to the corresponding uppercase character.
|
bound to the corresponding uppercase character.
|
|
|
`prefix-meta ()'
|
`prefix-meta ()'
|
Metafy the next character typed. This is for keyboards without a
|
Metafy the next character typed. This is for keyboards without a
|
meta key. Typing ` f' is equivalent to typing `M-f'.
|
meta key. Typing ` f' is equivalent to typing `M-f'.
|
|
|
`undo (C-_ or C-x C-u)'
|
`undo (C-_ or C-x C-u)'
|
Incremental undo, separately remembered for each line.
|
Incremental undo, separately remembered for each line.
|
|
|
`revert-line (M-r)'
|
`revert-line (M-r)'
|
Undo all changes made to this line. This is like executing the
|
Undo all changes made to this line. This is like executing the
|
`undo' command enough times to get back to the beginning.
|
`undo' command enough times to get back to the beginning.
|
|
|
`tilde-expand (M-~)'
|
`tilde-expand (M-~)'
|
Perform tilde expansion on the current word.
|
Perform tilde expansion on the current word.
|
|
|
`set-mark (C-@)'
|
`set-mark (C-@)'
|
Set the mark to the point. If a numeric argument is supplied, the
|
Set the mark to the point. If a numeric argument is supplied, the
|
mark is set to that position.
|
mark is set to that position.
|
|
|
`exchange-point-and-mark (C-x C-x)'
|
`exchange-point-and-mark (C-x C-x)'
|
Swap the point with the mark. The current cursor position is set
|
Swap the point with the mark. The current cursor position is set
|
to the saved position, and the old cursor position is saved as the
|
to the saved position, and the old cursor position is saved as the
|
mark.
|
mark.
|
|
|
`character-search (C-])'
|
`character-search (C-])'
|
A character is read and point is moved to the next occurrence of
|
A character is read and point is moved to the next occurrence of
|
that character. A negative count searches for previous
|
that character. A negative count searches for previous
|
occurrences.
|
occurrences.
|
|
|
`character-search-backward (M-C-])'
|
`character-search-backward (M-C-])'
|
A character is read and point is moved to the previous occurrence
|
A character is read and point is moved to the previous occurrence
|
of that character. A negative count searches for subsequent
|
of that character. A negative count searches for subsequent
|
occurrences.
|
occurrences.
|
|
|
`insert-comment (M-#)'
|
`insert-comment (M-#)'
|
Without a numeric argument, the value of the `comment-begin'
|
Without a numeric argument, the value of the `comment-begin'
|
variable is inserted at the beginning of the current line. If a
|
variable is inserted at the beginning of the current line. If a
|
numeric argument is supplied, this command acts as a toggle: if
|
numeric argument is supplied, this command acts as a toggle: if
|
the characters at the beginning of the line do not match the value
|
the characters at the beginning of the line do not match the value
|
of `comment-begin', the value is inserted, otherwise the
|
of `comment-begin', the value is inserted, otherwise the
|
characters in `comment-begin' are deleted from the beginning of
|
characters in `comment-begin' are deleted from the beginning of
|
the line. In either case, the line is accepted as if a newline
|
the line. In either case, the line is accepted as if a newline
|
had been typed.
|
had been typed.
|
|
|
`dump-functions ()'
|
`dump-functions ()'
|
Print all of the functions and their key bindings to the Readline
|
Print all of the functions and their key bindings to the Readline
|
output stream. If a numeric argument is supplied, the output is
|
output stream. If a numeric argument is supplied, the output is
|
formatted in such a way that it can be made part of an INPUTRC
|
formatted in such a way that it can be made part of an INPUTRC
|
file. This command is unbound by default.
|
file. This command is unbound by default.
|
|
|
`dump-variables ()'
|
`dump-variables ()'
|
Print all of the settable variables and their values to the
|
Print all of the settable variables and their values to the
|
Readline output stream. If a numeric argument is supplied, the
|
Readline output stream. If a numeric argument is supplied, the
|
output is formatted in such a way that it can be made part of an
|
output is formatted in such a way that it can be made part of an
|
INPUTRC file. This command is unbound by default.
|
INPUTRC file. This command is unbound by default.
|
|
|
`dump-macros ()'
|
`dump-macros ()'
|
Print all of the Readline key sequences bound to macros and the
|
Print all of the Readline key sequences bound to macros and the
|
strings they output. If a numeric argument is supplied, the
|
strings they output. If a numeric argument is supplied, the
|
output is formatted in such a way that it can be made part of an
|
output is formatted in such a way that it can be made part of an
|
INPUTRC file. This command is unbound by default.
|
INPUTRC file. This command is unbound by default.
|
|
|
`emacs-editing-mode (C-e)'
|
`emacs-editing-mode (C-e)'
|
When in `vi' command mode, this causes a switch to `emacs' editing
|
When in `vi' command mode, this causes a switch to `emacs' editing
|
mode.
|
mode.
|
|
|
`vi-editing-mode (M-C-j)'
|
`vi-editing-mode (M-C-j)'
|
When in `emacs' editing mode, this causes a switch to `vi' editing
|
When in `emacs' editing mode, this causes a switch to `vi' editing
|
mode.
|
mode.
|
|
|
|
|
|
|
File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
|
File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
|
|
|
27.5 Readline vi Mode
|
27.5 Readline vi Mode
|
=====================
|
=====================
|
|
|
While the Readline library does not have a full set of `vi' editing
|
While the Readline library does not have a full set of `vi' editing
|
functions, it does contain enough to allow simple editing of the line.
|
functions, it does contain enough to allow simple editing of the line.
|
The Readline `vi' mode behaves as specified in the POSIX 1003.2
|
The Readline `vi' mode behaves as specified in the POSIX 1003.2
|
standard.
|
standard.
|
|
|
In order to switch interactively between `emacs' and `vi' editing
|
In order to switch interactively between `emacs' and `vi' editing
|
modes, use the command `M-C-j' (bound to emacs-editing-mode when in
|
modes, use the command `M-C-j' (bound to emacs-editing-mode when in
|
`vi' mode and to vi-editing-mode in `emacs' mode). The Readline
|
`vi' mode and to vi-editing-mode in `emacs' mode). The Readline
|
default is `emacs' mode.
|
default is `emacs' mode.
|
|
|
When you enter a line in `vi' mode, you are already placed in
|
When you enter a line in `vi' mode, you are already placed in
|
`insertion' mode, as if you had typed an `i'. Pressing switches
|
`insertion' mode, as if you had typed an `i'. Pressing switches
|
you into `command' mode, where you can edit the text of the line with
|
you into `command' mode, where you can edit the text of the line with
|
the standard `vi' movement keys, move to previous history lines with
|
the standard `vi' movement keys, move to previous history lines with
|
`k' and subsequent lines with `j', and so forth.
|
`k' and subsequent lines with `j', and so forth.
|
|
|
|
|
File: gdb.info, Node: Using History Interactively, Next: Formatting Documentation, Prev: Command Line Editing, Up: Top
|
File: gdb.info, Node: Using History Interactively, Next: Formatting Documentation, Prev: Command Line Editing, Up: Top
|
|
|
28 Using History Interactively
|
28 Using History Interactively
|
******************************
|
******************************
|
|
|
This chapter describes how to use the GNU History Library interactively,
|
This chapter describes how to use the GNU History Library interactively,
|
from a user's standpoint. It should be considered a user's guide. For
|
from a user's standpoint. It should be considered a user's guide. For
|
information on using the GNU History Library in other programs, see the
|
information on using the GNU History Library in other programs, see the
|
GNU Readline Library Manual.
|
GNU Readline Library Manual.
|
|
|
* Menu:
|
* Menu:
|
|
|
* History Interaction:: What it feels like using History as a user.
|
* History Interaction:: What it feels like using History as a user.
|
|
|
|
|
File: gdb.info, Node: History Interaction, Up: Using History Interactively
|
File: gdb.info, Node: History Interaction, Up: Using History Interactively
|
|
|
28.1 History Expansion
|
28.1 History Expansion
|
======================
|
======================
|
|
|
The History library provides a history expansion feature that is similar
|
The History library provides a history expansion feature that is similar
|
to the history expansion provided by `csh'. This section describes the
|
to the history expansion provided by `csh'. This section describes the
|
syntax used to manipulate the history information.
|
syntax used to manipulate the history information.
|
|
|
History expansions introduce words from the history list into the
|
History expansions introduce words from the history list into the
|
input stream, making it easy to repeat commands, insert the arguments
|
input stream, making it easy to repeat commands, insert the arguments
|
to a previous command into the current input line, or fix errors in
|
to a previous command into the current input line, or fix errors in
|
previous commands quickly.
|
previous commands quickly.
|
|
|
History expansion takes place in two parts. The first is to
|
History expansion takes place in two parts. The first is to
|
determine which line from the history list should be used during
|
determine which line from the history list should be used during
|
substitution. The second is to select portions of that line for
|
substitution. The second is to select portions of that line for
|
inclusion into the current one. The line selected from the history is
|
inclusion into the current one. The line selected from the history is
|
called the "event", and the portions of that line that are acted upon
|
called the "event", and the portions of that line that are acted upon
|
are called "words". Various "modifiers" are available to manipulate
|
are called "words". Various "modifiers" are available to manipulate
|
the selected words. The line is broken into words in the same fashion
|
the selected words. The line is broken into words in the same fashion
|
that Bash does, so that several words surrounded by quotes are
|
that Bash does, so that several words surrounded by quotes are
|
considered one word. History expansions are introduced by the
|
considered one word. History expansions are introduced by the
|
appearance of the history expansion character, which is `!' by default.
|
appearance of the history expansion character, which is `!' by default.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Event Designators:: How to specify which history line to use.
|
* Event Designators:: How to specify which history line to use.
|
* Word Designators:: Specifying which words are of interest.
|
* Word Designators:: Specifying which words are of interest.
|
* Modifiers:: Modifying the results of substitution.
|
* Modifiers:: Modifying the results of substitution.
|
|
|
|
|
File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
|
File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
|
|
|
28.1.1 Event Designators
|
28.1.1 Event Designators
|
------------------------
|
------------------------
|
|
|
An event designator is a reference to a command line entry in the
|
An event designator is a reference to a command line entry in the
|
history list.
|
history list.
|
|
|
`!'
|
`!'
|
Start a history substitution, except when followed by a space, tab,
|
Start a history substitution, except when followed by a space, tab,
|
the end of the line, or `='.
|
the end of the line, or `='.
|
|
|
`!N'
|
`!N'
|
Refer to command line N.
|
Refer to command line N.
|
|
|
`!-N'
|
`!-N'
|
Refer to the command N lines back.
|
Refer to the command N lines back.
|
|
|
`!!'
|
`!!'
|
Refer to the previous command. This is a synonym for `!-1'.
|
Refer to the previous command. This is a synonym for `!-1'.
|
|
|
`!STRING'
|
`!STRING'
|
Refer to the most recent command starting with STRING.
|
Refer to the most recent command starting with STRING.
|
|
|
`!?STRING[?]'
|
`!?STRING[?]'
|
Refer to the most recent command containing STRING. The trailing
|
Refer to the most recent command containing STRING. The trailing
|
`?' may be omitted if the STRING is followed immediately by a
|
`?' may be omitted if the STRING is followed immediately by a
|
newline.
|
newline.
|
|
|
`^STRING1^STRING2^'
|
`^STRING1^STRING2^'
|
Quick Substitution. Repeat the last command, replacing STRING1
|
Quick Substitution. Repeat the last command, replacing STRING1
|
with STRING2. Equivalent to `!!:s/STRING1/STRING2/'.
|
with STRING2. Equivalent to `!!:s/STRING1/STRING2/'.
|
|
|
`!#'
|
`!#'
|
The entire command line typed so far.
|
The entire command line typed so far.
|
|
|
|
|
|
|
File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
|
File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
|
|
|
28.1.2 Word Designators
|
28.1.2 Word Designators
|
-----------------------
|
-----------------------
|
|
|
Word designators are used to select desired words from the event. A
|
Word designators are used to select desired words from the event. A
|
`:' separates the event specification from the word designator. It may
|
`:' separates the event specification from the word designator. It may
|
be omitted if the word designator begins with a `^', `$', `*', `-', or
|
be omitted if the word designator begins with a `^', `$', `*', `-', or
|
`%'. Words are numbered from the beginning of the line, with the first
|
`%'. Words are numbered from the beginning of the line, with the first
|
word being denoted by 0 (zero). Words are inserted into the current
|
word being denoted by 0 (zero). Words are inserted into the current
|
line separated by single spaces.
|
line separated by single spaces.
|
|
|
For example,
|
For example,
|
|
|
`!!'
|
`!!'
|
designates the preceding command. When you type this, the
|
designates the preceding command. When you type this, the
|
preceding command is repeated in toto.
|
preceding command is repeated in toto.
|
|
|
`!!:$'
|
`!!:$'
|
designates the last argument of the preceding command. This may be
|
designates the last argument of the preceding command. This may be
|
shortened to `!$'.
|
shortened to `!$'.
|
|
|
`!fi:2'
|
`!fi:2'
|
designates the second argument of the most recent command starting
|
designates the second argument of the most recent command starting
|
with the letters `fi'.
|
with the letters `fi'.
|
|
|
Here are the word designators:
|
Here are the word designators:
|
|
|
`0 (zero)'
|
`0 (zero)'
|
The `0'th word. For many applications, this is the command word.
|
The `0'th word. For many applications, this is the command word.
|
|
|
`N'
|
`N'
|
The Nth word.
|
The Nth word.
|
|
|
`^'
|
`^'
|
The first argument; that is, word 1.
|
The first argument; that is, word 1.
|
|
|
`$'
|
`$'
|
The last argument.
|
The last argument.
|
|
|
`%'
|
`%'
|
The word matched by the most recent `?STRING?' search.
|
The word matched by the most recent `?STRING?' search.
|
|
|
`X-Y'
|
`X-Y'
|
A range of words; `-Y' abbreviates `0-Y'.
|
A range of words; `-Y' abbreviates `0-Y'.
|
|
|
`*'
|
`*'
|
All of the words, except the `0'th. This is a synonym for `1-$'.
|
All of the words, except the `0'th. This is a synonym for `1-$'.
|
It is not an error to use `*' if there is just one word in the
|
It is not an error to use `*' if there is just one word in the
|
event; the empty string is returned in that case.
|
event; the empty string is returned in that case.
|
|
|
`X*'
|
`X*'
|
Abbreviates `X-$'
|
Abbreviates `X-$'
|
|
|
`X-'
|
`X-'
|
Abbreviates `X-$' like `X*', but omits the last word.
|
Abbreviates `X-$' like `X*', but omits the last word.
|
|
|
|
|
If a word designator is supplied without an event specification, the
|
If a word designator is supplied without an event specification, the
|
previous command is used as the event.
|
previous command is used as the event.
|
|
|
|
|
File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
|
File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
|
|
|
28.1.3 Modifiers
|
28.1.3 Modifiers
|
----------------
|
----------------
|
|
|
After the optional word designator, you can add a sequence of one or
|
After the optional word designator, you can add a sequence of one or
|
more of the following modifiers, each preceded by a `:'.
|
more of the following modifiers, each preceded by a `:'.
|
|
|
`h'
|
`h'
|
Remove a trailing pathname component, leaving only the head.
|
Remove a trailing pathname component, leaving only the head.
|
|
|
`t'
|
`t'
|
Remove all leading pathname components, leaving the tail.
|
Remove all leading pathname components, leaving the tail.
|
|
|
`r'
|
`r'
|
Remove a trailing suffix of the form `.SUFFIX', leaving the
|
Remove a trailing suffix of the form `.SUFFIX', leaving the
|
basename.
|
basename.
|
|
|
`e'
|
`e'
|
Remove all but the trailing suffix.
|
Remove all but the trailing suffix.
|
|
|
`p'
|
`p'
|
Print the new command but do not execute it.
|
Print the new command but do not execute it.
|
|
|
`s/OLD/NEW/'
|
`s/OLD/NEW/'
|
Substitute NEW for the first occurrence of OLD in the event line.
|
Substitute NEW for the first occurrence of OLD in the event line.
|
Any delimiter may be used in place of `/'. The delimiter may be
|
Any delimiter may be used in place of `/'. The delimiter may be
|
quoted in OLD and NEW with a single backslash. If `&' appears in
|
quoted in OLD and NEW with a single backslash. If `&' appears in
|
NEW, it is replaced by OLD. A single backslash will quote the
|
NEW, it is replaced by OLD. A single backslash will quote the
|
`&'. The final delimiter is optional if it is the last character
|
`&'. The final delimiter is optional if it is the last character
|
on the input line.
|
on the input line.
|
|
|
`&'
|
`&'
|
Repeat the previous substitution.
|
Repeat the previous substitution.
|
|
|
`g'
|
`g'
|
`a'
|
`a'
|
Cause changes to be applied over the entire event line. Used in
|
Cause changes to be applied over the entire event line. Used in
|
conjunction with `s', as in `gs/OLD/NEW/', or with `&'.
|
conjunction with `s', as in `gs/OLD/NEW/', or with `&'.
|
|
|
`G'
|
`G'
|
Apply the following `s' modifier once to each word in the event.
|
Apply the following `s' modifier once to each word in the event.
|
|
|
|
|
|
|
File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: Using History Interactively, Up: Top
|
File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: Using History Interactively, Up: Top
|
|
|
Appendix A Formatting Documentation
|
Appendix A Formatting Documentation
|
***********************************
|
***********************************
|
|
|
The GDB 4 release includes an already-formatted reference card, ready
|
The GDB 4 release includes an already-formatted reference card, ready
|
for printing with PostScript or Ghostscript, in the `gdb' subdirectory
|
for printing with PostScript or Ghostscript, in the `gdb' subdirectory
|
of the main source directory(1). If you can use PostScript or
|
of the main source directory(1). If you can use PostScript or
|
Ghostscript with your printer, you can print the reference card
|
Ghostscript with your printer, you can print the reference card
|
immediately with `refcard.ps'.
|
immediately with `refcard.ps'.
|
|
|
The release also includes the source for the reference card. You
|
The release also includes the source for the reference card. You
|
can format it, using TeX, by typing:
|
can format it, using TeX, by typing:
|
|
|
make refcard.dvi
|
make refcard.dvi
|
|
|
The GDB reference card is designed to print in "landscape" mode on
|
The GDB reference card is designed to print in "landscape" mode on
|
US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
|
US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
|
high. You will need to specify this form of printing as an option to
|
high. You will need to specify this form of printing as an option to
|
your DVI output program.
|
your DVI output program.
|
|
|
All the documentation for GDB comes as part of the machine-readable
|
All the documentation for GDB comes as part of the machine-readable
|
distribution. The documentation is written in Texinfo format, which is
|
distribution. The documentation is written in Texinfo format, which is
|
a documentation system that uses a single source file to produce both
|
a documentation system that uses a single source file to produce both
|
on-line information and a printed manual. You can use one of the Info
|
on-line information and a printed manual. You can use one of the Info
|
formatting commands to create the on-line version of the documentation
|
formatting commands to create the on-line version of the documentation
|
and TeX (or `texi2roff') to typeset the printed version.
|
and TeX (or `texi2roff') to typeset the printed version.
|
|
|
GDB includes an already formatted copy of the on-line Info version
|
GDB includes an already formatted copy of the on-line Info version
|
of this manual in the `gdb' subdirectory. The main Info file is
|
of this manual in the `gdb' subdirectory. The main Info file is
|
`gdb-6.8/gdb/gdb.info', and it refers to subordinate files matching
|
`gdb-6.8/gdb/gdb.info', and it refers to subordinate files matching
|
`gdb.info*' in the same directory. If necessary, you can print out
|
`gdb.info*' in the same directory. If necessary, you can print out
|
these files, or read them with any editor; but they are easier to read
|
these files, or read them with any editor; but they are easier to read
|
using the `info' subsystem in GNU Emacs or the standalone `info'
|
using the `info' subsystem in GNU Emacs or the standalone `info'
|
program, available as part of the GNU Texinfo distribution.
|
program, available as part of the GNU Texinfo distribution.
|
|
|
If you want to format these Info files yourself, you need one of the
|
If you want to format these Info files yourself, you need one of the
|
Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
|
Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
|
|
|
If you have `makeinfo' installed, and are in the top level GDB
|
If you have `makeinfo' installed, and are in the top level GDB
|
source directory (`gdb-6.8', in the case of version 6.8), you can make
|
source directory (`gdb-6.8', in the case of version 6.8), you can make
|
the Info file by typing:
|
the Info file by typing:
|
|
|
cd gdb
|
cd gdb
|
make gdb.info
|
make gdb.info
|
|
|
If you want to typeset and print copies of this manual, you need TeX,
|
If you want to typeset and print copies of this manual, you need TeX,
|
a program to print its DVI output files, and `texinfo.tex', the Texinfo
|
a program to print its DVI output files, and `texinfo.tex', the Texinfo
|
definitions file.
|
definitions file.
|
|
|
TeX is a typesetting program; it does not print files directly, but
|
TeX is a typesetting program; it does not print files directly, but
|
produces output files called DVI files. To print a typeset document,
|
produces output files called DVI files. To print a typeset document,
|
you need a program to print DVI files. If your system has TeX
|
you need a program to print DVI files. If your system has TeX
|
installed, chances are it has such a program. The precise command to
|
installed, chances are it has such a program. The precise command to
|
use depends on your system; `lpr -d' is common; another (for PostScript
|
use depends on your system; `lpr -d' is common; another (for PostScript
|
devices) is `dvips'. The DVI print command may require a file name
|
devices) is `dvips'. The DVI print command may require a file name
|
without any extension or a `.dvi' extension.
|
without any extension or a `.dvi' extension.
|
|
|
TeX also requires a macro definitions file called `texinfo.tex'.
|
TeX also requires a macro definitions file called `texinfo.tex'.
|
This file tells TeX how to typeset a document written in Texinfo
|
This file tells TeX how to typeset a document written in Texinfo
|
format. On its own, TeX cannot either read or typeset a Texinfo file.
|
format. On its own, TeX cannot either read or typeset a Texinfo file.
|
`texinfo.tex' is distributed with GDB and is located in the
|
`texinfo.tex' is distributed with GDB and is located in the
|
`gdb-VERSION-NUMBER/texinfo' directory.
|
`gdb-VERSION-NUMBER/texinfo' directory.
|
|
|
If you have TeX and a DVI printer program installed, you can typeset
|
If you have TeX and a DVI printer program installed, you can typeset
|
and print this manual. First switch to the `gdb' subdirectory of the
|
and print this manual. First switch to the `gdb' subdirectory of the
|
main source directory (for example, to `gdb-6.8/gdb') and type:
|
main source directory (for example, to `gdb-6.8/gdb') and type:
|
|
|
make gdb.dvi
|
make gdb.dvi
|
|
|
Then give `gdb.dvi' to your DVI printing program.
|
Then give `gdb.dvi' to your DVI printing program.
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) In `gdb-6.8/gdb/refcard.ps' of the version 6.8 release.
|
(1) In `gdb-6.8/gdb/refcard.ps' of the version 6.8 release.
|
|
|
|
|
File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top
|
File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top
|
|
|
Appendix B Installing GDB
|
Appendix B Installing GDB
|
*************************
|
*************************
|
|
|
* Menu:
|
* Menu:
|
|
|
* Requirements:: Requirements for building GDB
|
* Requirements:: Requirements for building GDB
|
* Running Configure:: Invoking the GDB `configure' script
|
* Running Configure:: Invoking the GDB `configure' script
|
* Separate Objdir:: Compiling GDB in another directory
|
* Separate Objdir:: Compiling GDB in another directory
|
* Config Names:: Specifying names for hosts and targets
|
* Config Names:: Specifying names for hosts and targets
|
* Configure Options:: Summary of options for configure
|
* Configure Options:: Summary of options for configure
|
|
|
|
|
File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB
|
File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB
|
|
|
B.1 Requirements for Building GDB
|
B.1 Requirements for Building GDB
|
=================================
|
=================================
|
|
|
Building GDB requires various tools and packages to be available.
|
Building GDB requires various tools and packages to be available.
|
Other packages will be used only if they are found.
|
Other packages will be used only if they are found.
|
|
|
Tools/Packages Necessary for Building GDB
|
Tools/Packages Necessary for Building GDB
|
=========================================
|
=========================================
|
|
|
ISO C90 compiler
|
ISO C90 compiler
|
GDB is written in ISO C90. It should be buildable with any
|
GDB is written in ISO C90. It should be buildable with any
|
working C90 compiler, e.g. GCC.
|
working C90 compiler, e.g. GCC.
|
|
|
|
|
Tools/Packages Optional for Building GDB
|
Tools/Packages Optional for Building GDB
|
========================================
|
========================================
|
|
|
Expat
|
Expat
|
GDB can use the Expat XML parsing library. This library may be
|
GDB can use the Expat XML parsing library. This library may be
|
included with your operating system distribution; if it is not, you
|
included with your operating system distribution; if it is not, you
|
can get the latest version from `http://expat.sourceforge.net'.
|
can get the latest version from `http://expat.sourceforge.net'.
|
The `configure' script will search for this library in several
|
The `configure' script will search for this library in several
|
standard locations; if it is installed in an unusual path, you can
|
standard locations; if it is installed in an unusual path, you can
|
use the `--with-libexpat-prefix' option to specify its location.
|
use the `--with-libexpat-prefix' option to specify its location.
|
|
|
Expat is used for:
|
Expat is used for:
|
|
|
* Remote protocol memory maps (*note Memory Map Format::)
|
* Remote protocol memory maps (*note Memory Map Format::)
|
|
|
* Target descriptions (*note Target Descriptions::)
|
* Target descriptions (*note Target Descriptions::)
|
|
|
* Remote shared library lists (*note Library List Format::)
|
* Remote shared library lists (*note Library List Format::)
|
|
|
* MS-Windows shared libraries (*note Shared Libraries::)
|
* MS-Windows shared libraries (*note Shared Libraries::)
|
|
|
|
|
|
|
File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB
|
File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB
|
|
|
B.2 Invoking the GDB `configure' Script
|
B.2 Invoking the GDB `configure' Script
|
=======================================
|
=======================================
|
|
|
GDB comes with a `configure' script that automates the process of
|
GDB comes with a `configure' script that automates the process of
|
preparing GDB for installation; you can then use `make' to build the
|
preparing GDB for installation; you can then use `make' to build the
|
`gdb' program.
|
`gdb' program.
|
|
|
The GDB distribution includes all the source code you need for GDB
|
The GDB distribution includes all the source code you need for GDB
|
in a single directory, whose name is usually composed by appending the
|
in a single directory, whose name is usually composed by appending the
|
version number to `gdb'.
|
version number to `gdb'.
|
|
|
For example, the GDB version 6.8 distribution is in the `gdb-6.8'
|
For example, the GDB version 6.8 distribution is in the `gdb-6.8'
|
directory. That directory contains:
|
directory. That directory contains:
|
|
|
`gdb-6.8/configure (and supporting files)'
|
`gdb-6.8/configure (and supporting files)'
|
script for configuring GDB and all its supporting libraries
|
script for configuring GDB and all its supporting libraries
|
|
|
`gdb-6.8/gdb'
|
`gdb-6.8/gdb'
|
the source specific to GDB itself
|
the source specific to GDB itself
|
|
|
`gdb-6.8/bfd'
|
`gdb-6.8/bfd'
|
source for the Binary File Descriptor library
|
source for the Binary File Descriptor library
|
|
|
`gdb-6.8/include'
|
`gdb-6.8/include'
|
GNU include files
|
GNU include files
|
|
|
`gdb-6.8/libiberty'
|
`gdb-6.8/libiberty'
|
source for the `-liberty' free software library
|
source for the `-liberty' free software library
|
|
|
`gdb-6.8/opcodes'
|
`gdb-6.8/opcodes'
|
source for the library of opcode tables and disassemblers
|
source for the library of opcode tables and disassemblers
|
|
|
`gdb-6.8/readline'
|
`gdb-6.8/readline'
|
source for the GNU command-line interface
|
source for the GNU command-line interface
|
|
|
`gdb-6.8/glob'
|
`gdb-6.8/glob'
|
source for the GNU filename pattern-matching subroutine
|
source for the GNU filename pattern-matching subroutine
|
|
|
`gdb-6.8/mmalloc'
|
`gdb-6.8/mmalloc'
|
source for the GNU memory-mapped malloc package
|
source for the GNU memory-mapped malloc package
|
|
|
The simplest way to configure and build GDB is to run `configure'
|
The simplest way to configure and build GDB is to run `configure'
|
from the `gdb-VERSION-NUMBER' source directory, which in this example
|
from the `gdb-VERSION-NUMBER' source directory, which in this example
|
is the `gdb-6.8' directory.
|
is the `gdb-6.8' directory.
|
|
|
First switch to the `gdb-VERSION-NUMBER' source directory if you are
|
First switch to the `gdb-VERSION-NUMBER' source directory if you are
|
not already in it; then run `configure'. Pass the identifier for the
|
not already in it; then run `configure'. Pass the identifier for the
|
platform on which GDB will run as an argument.
|
platform on which GDB will run as an argument.
|
|
|
For example:
|
For example:
|
|
|
cd gdb-6.8
|
cd gdb-6.8
|
./configure HOST
|
./configure HOST
|
make
|
make
|
|
|
where HOST is an identifier such as `sun4' or `decstation', that
|
where HOST is an identifier such as `sun4' or `decstation', that
|
identifies the platform where GDB will run. (You can often leave off
|
identifies the platform where GDB will run. (You can often leave off
|
HOST; `configure' tries to guess the correct value by examining your
|
HOST; `configure' tries to guess the correct value by examining your
|
system.)
|
system.)
|
|
|
Running `configure HOST' and then running `make' builds the `bfd',
|
Running `configure HOST' and then running `make' builds the `bfd',
|
`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
|
`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
|
The configured source files, and the binaries, are left in the
|
The configured source files, and the binaries, are left in the
|
corresponding source directories.
|
corresponding source directories.
|
|
|
`configure' is a Bourne-shell (`/bin/sh') script; if your system
|
`configure' is a Bourne-shell (`/bin/sh') script; if your system
|
does not recognize this automatically when you run a different shell,
|
does not recognize this automatically when you run a different shell,
|
you may need to run `sh' on it explicitly:
|
you may need to run `sh' on it explicitly:
|
|
|
sh configure HOST
|
sh configure HOST
|
|
|
If you run `configure' from a directory that contains source
|
If you run `configure' from a directory that contains source
|
directories for multiple libraries or programs, such as the `gdb-6.8'
|
directories for multiple libraries or programs, such as the `gdb-6.8'
|
source directory for version 6.8, `configure' creates configuration
|
source directory for version 6.8, `configure' creates configuration
|
files for every directory level underneath (unless you tell it not to,
|
files for every directory level underneath (unless you tell it not to,
|
with the `--norecursion' option).
|
with the `--norecursion' option).
|
|
|
You should run the `configure' script from the top directory in the
|
You should run the `configure' script from the top directory in the
|
source tree, the `gdb-VERSION-NUMBER' directory. If you run
|
source tree, the `gdb-VERSION-NUMBER' directory. If you run
|
`configure' from one of the subdirectories, you will configure only
|
`configure' from one of the subdirectories, you will configure only
|
that subdirectory. That is usually not what you want. In particular,
|
that subdirectory. That is usually not what you want. In particular,
|
if you run the first `configure' from the `gdb' subdirectory of the
|
if you run the first `configure' from the `gdb' subdirectory of the
|
`gdb-VERSION-NUMBER' directory, you will omit the configuration of
|
`gdb-VERSION-NUMBER' directory, you will omit the configuration of
|
`bfd', `readline', and other sibling directories of the `gdb'
|
`bfd', `readline', and other sibling directories of the `gdb'
|
subdirectory. This leads to build errors about missing include files
|
subdirectory. This leads to build errors about missing include files
|
such as `bfd/bfd.h'.
|
such as `bfd/bfd.h'.
|
|
|
You can install `gdb' anywhere; it has no hardwired paths. However,
|
You can install `gdb' anywhere; it has no hardwired paths. However,
|
you should make sure that the shell on your path (named by the `SHELL'
|
you should make sure that the shell on your path (named by the `SHELL'
|
environment variable) is publicly readable. Remember that GDB uses the
|
environment variable) is publicly readable. Remember that GDB uses the
|
shell to start your program--some systems refuse to let GDB debug child
|
shell to start your program--some systems refuse to let GDB debug child
|
processes whose programs are not readable.
|
processes whose programs are not readable.
|
|
|
|
|
File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB
|
File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB
|
|
|
B.3 Compiling GDB in Another Directory
|
B.3 Compiling GDB in Another Directory
|
======================================
|
======================================
|
|
|
If you want to run GDB versions for several host or target machines,
|
If you want to run GDB versions for several host or target machines,
|
you need a different `gdb' compiled for each combination of host and
|
you need a different `gdb' compiled for each combination of host and
|
target. `configure' is designed to make this easy by allowing you to
|
target. `configure' is designed to make this easy by allowing you to
|
generate each configuration in a separate subdirectory, rather than in
|
generate each configuration in a separate subdirectory, rather than in
|
the source directory. If your `make' program handles the `VPATH'
|
the source directory. If your `make' program handles the `VPATH'
|
feature (GNU `make' does), running `make' in each of these directories
|
feature (GNU `make' does), running `make' in each of these directories
|
builds the `gdb' program specified there.
|
builds the `gdb' program specified there.
|
|
|
To build `gdb' in a separate directory, run `configure' with the
|
To build `gdb' in a separate directory, run `configure' with the
|
`--srcdir' option to specify where to find the source. (You also need
|
`--srcdir' option to specify where to find the source. (You also need
|
to specify a path to find `configure' itself from your working
|
to specify a path to find `configure' itself from your working
|
directory. If the path to `configure' would be the same as the
|
directory. If the path to `configure' would be the same as the
|
argument to `--srcdir', you can leave out the `--srcdir' option; it is
|
argument to `--srcdir', you can leave out the `--srcdir' option; it is
|
assumed.)
|
assumed.)
|
|
|
For example, with version 6.8, you can build GDB in a separate
|
For example, with version 6.8, you can build GDB in a separate
|
directory for a Sun 4 like this:
|
directory for a Sun 4 like this:
|
|
|
cd gdb-6.8
|
cd gdb-6.8
|
mkdir ../gdb-sun4
|
mkdir ../gdb-sun4
|
cd ../gdb-sun4
|
cd ../gdb-sun4
|
../gdb-6.8/configure sun4
|
../gdb-6.8/configure sun4
|
make
|
make
|
|
|
When `configure' builds a configuration using a remote source
|
When `configure' builds a configuration using a remote source
|
directory, it creates a tree for the binaries with the same structure
|
directory, it creates a tree for the binaries with the same structure
|
(and using the same names) as the tree under the source directory. In
|
(and using the same names) as the tree under the source directory. In
|
the example, you'd find the Sun 4 library `libiberty.a' in the
|
the example, you'd find the Sun 4 library `libiberty.a' in the
|
directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
|
directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
|
|
|
Make sure that your path to the `configure' script has just one
|
Make sure that your path to the `configure' script has just one
|
instance of `gdb' in it. If your path to `configure' looks like
|
instance of `gdb' in it. If your path to `configure' looks like
|
`../gdb-6.8/gdb/configure', you are configuring only one subdirectory
|
`../gdb-6.8/gdb/configure', you are configuring only one subdirectory
|
of GDB, not the whole package. This leads to build errors about
|
of GDB, not the whole package. This leads to build errors about
|
missing include files such as `bfd/bfd.h'.
|
missing include files such as `bfd/bfd.h'.
|
|
|
One popular reason to build several GDB configurations in separate
|
One popular reason to build several GDB configurations in separate
|
directories is to configure GDB for cross-compiling (where GDB runs on
|
directories is to configure GDB for cross-compiling (where GDB runs on
|
one machine--the "host"--while debugging programs that run on another
|
one machine--the "host"--while debugging programs that run on another
|
machine--the "target"). You specify a cross-debugging target by giving
|
machine--the "target"). You specify a cross-debugging target by giving
|
the `--target=TARGET' option to `configure'.
|
the `--target=TARGET' option to `configure'.
|
|
|
When you run `make' to build a program or library, you must run it
|
When you run `make' to build a program or library, you must run it
|
in a configured directory--whatever directory you were in when you
|
in a configured directory--whatever directory you were in when you
|
called `configure' (or one of its subdirectories).
|
called `configure' (or one of its subdirectories).
|
|
|
The `Makefile' that `configure' generates in each source directory
|
The `Makefile' that `configure' generates in each source directory
|
also runs recursively. If you type `make' in a source directory such
|
also runs recursively. If you type `make' in a source directory such
|
as `gdb-6.8' (or in a separate configured directory configured with
|
as `gdb-6.8' (or in a separate configured directory configured with
|
`--srcdir=DIRNAME/gdb-6.8'), you will build all the required libraries,
|
`--srcdir=DIRNAME/gdb-6.8'), you will build all the required libraries,
|
and then build GDB.
|
and then build GDB.
|
|
|
When you have multiple hosts or targets configured in separate
|
When you have multiple hosts or targets configured in separate
|
directories, you can run `make' on them in parallel (for example, if
|
directories, you can run `make' on them in parallel (for example, if
|
they are NFS-mounted on each of the hosts); they will not interfere
|
they are NFS-mounted on each of the hosts); they will not interfere
|
with each other.
|
with each other.
|
|
|
|
|
File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB
|
File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB
|
|
|
B.4 Specifying Names for Hosts and Targets
|
B.4 Specifying Names for Hosts and Targets
|
==========================================
|
==========================================
|
|
|
The specifications used for hosts and targets in the `configure' script
|
The specifications used for hosts and targets in the `configure' script
|
are based on a three-part naming scheme, but some short predefined
|
are based on a three-part naming scheme, but some short predefined
|
aliases are also supported. The full naming scheme encodes three pieces
|
aliases are also supported. The full naming scheme encodes three pieces
|
of information in the following pattern:
|
of information in the following pattern:
|
|
|
ARCHITECTURE-VENDOR-OS
|
ARCHITECTURE-VENDOR-OS
|
|
|
For example, you can use the alias `sun4' as a HOST argument, or as
|
For example, you can use the alias `sun4' as a HOST argument, or as
|
the value for TARGET in a `--target=TARGET' option. The equivalent
|
the value for TARGET in a `--target=TARGET' option. The equivalent
|
full name is `sparc-sun-sunos4'.
|
full name is `sparc-sun-sunos4'.
|
|
|
The `configure' script accompanying GDB does not provide any query
|
The `configure' script accompanying GDB does not provide any query
|
facility to list all supported host and target names or aliases.
|
facility to list all supported host and target names or aliases.
|
`configure' calls the Bourne shell script `config.sub' to map
|
`configure' calls the Bourne shell script `config.sub' to map
|
abbreviations to full names; you can read the script, if you wish, or
|
abbreviations to full names; you can read the script, if you wish, or
|
you can use it to test your guesses on abbreviations--for example:
|
you can use it to test your guesses on abbreviations--for example:
|
|
|
% sh config.sub i386-linux
|
% sh config.sub i386-linux
|
i386-pc-linux-gnu
|
i386-pc-linux-gnu
|
% sh config.sub alpha-linux
|
% sh config.sub alpha-linux
|
alpha-unknown-linux-gnu
|
alpha-unknown-linux-gnu
|
% sh config.sub hp9k700
|
% sh config.sub hp9k700
|
hppa1.1-hp-hpux
|
hppa1.1-hp-hpux
|
% sh config.sub sun4
|
% sh config.sub sun4
|
sparc-sun-sunos4.1.1
|
sparc-sun-sunos4.1.1
|
% sh config.sub sun3
|
% sh config.sub sun3
|
m68k-sun-sunos4.1.1
|
m68k-sun-sunos4.1.1
|
% sh config.sub i986v
|
% sh config.sub i986v
|
Invalid configuration `i986v': machine `i986v' not recognized
|
Invalid configuration `i986v': machine `i986v' not recognized
|
|
|
`config.sub' is also distributed in the GDB source directory
|
`config.sub' is also distributed in the GDB source directory
|
(`gdb-6.8', for version 6.8).
|
(`gdb-6.8', for version 6.8).
|
|
|
|
|
File: gdb.info, Node: Configure Options, Prev: Config Names, Up: Installing GDB
|
File: gdb.info, Node: Configure Options, Prev: Config Names, Up: Installing GDB
|
|
|
B.5 `configure' Options
|
B.5 `configure' Options
|
=======================
|
=======================
|
|
|
Here is a summary of the `configure' options and arguments that are
|
Here is a summary of the `configure' options and arguments that are
|
most often useful for building GDB. `configure' also has several other
|
most often useful for building GDB. `configure' also has several other
|
options not listed here. *note (configure.info)What Configure Does::,
|
options not listed here. *note (configure.info)What Configure Does::,
|
for a full explanation of `configure'.
|
for a full explanation of `configure'.
|
|
|
configure [--help]
|
configure [--help]
|
[--prefix=DIR]
|
[--prefix=DIR]
|
[--exec-prefix=DIR]
|
[--exec-prefix=DIR]
|
[--srcdir=DIRNAME]
|
[--srcdir=DIRNAME]
|
[--norecursion] [--rm]
|
[--norecursion] [--rm]
|
[--target=TARGET]
|
[--target=TARGET]
|
HOST
|
HOST
|
|
|
You may introduce options with a single `-' rather than `--' if you
|
You may introduce options with a single `-' rather than `--' if you
|
prefer; but you may abbreviate option names if you use `--'.
|
prefer; but you may abbreviate option names if you use `--'.
|
|
|
`--help'
|
`--help'
|
Display a quick summary of how to invoke `configure'.
|
Display a quick summary of how to invoke `configure'.
|
|
|
`--prefix=DIR'
|
`--prefix=DIR'
|
Configure the source to install programs and files under directory
|
Configure the source to install programs and files under directory
|
`DIR'.
|
`DIR'.
|
|
|
`--exec-prefix=DIR'
|
`--exec-prefix=DIR'
|
Configure the source to install programs under directory `DIR'.
|
Configure the source to install programs under directory `DIR'.
|
|
|
`--srcdir=DIRNAME'
|
`--srcdir=DIRNAME'
|
*Warning: using this option requires GNU `make', or another `make'
|
*Warning: using this option requires GNU `make', or another `make'
|
that implements the `VPATH' feature.*
|
that implements the `VPATH' feature.*
|
Use this option to make configurations in directories separate
|
Use this option to make configurations in directories separate
|
from the GDB source directories. Among other things, you can use
|
from the GDB source directories. Among other things, you can use
|
this to build (or maintain) several configurations simultaneously,
|
this to build (or maintain) several configurations simultaneously,
|
in separate directories. `configure' writes
|
in separate directories. `configure' writes
|
configuration-specific files in the current directory, but
|
configuration-specific files in the current directory, but
|
arranges for them to use the source in the directory DIRNAME.
|
arranges for them to use the source in the directory DIRNAME.
|
`configure' creates directories under the working directory in
|
`configure' creates directories under the working directory in
|
parallel to the source directories below DIRNAME.
|
parallel to the source directories below DIRNAME.
|
|
|
`--norecursion'
|
`--norecursion'
|
Configure only the directory level where `configure' is executed;
|
Configure only the directory level where `configure' is executed;
|
do not propagate configuration to subdirectories.
|
do not propagate configuration to subdirectories.
|
|
|
`--target=TARGET'
|
`--target=TARGET'
|
Configure GDB for cross-debugging programs running on the specified
|
Configure GDB for cross-debugging programs running on the specified
|
TARGET. Without this option, GDB is configured to debug programs
|
TARGET. Without this option, GDB is configured to debug programs
|
that run on the same machine (HOST) as GDB itself.
|
that run on the same machine (HOST) as GDB itself.
|
|
|
There is no convenient way to generate a list of all available
|
There is no convenient way to generate a list of all available
|
targets.
|
targets.
|
|
|
`HOST ...'
|
`HOST ...'
|
Configure GDB to run on the specified HOST.
|
Configure GDB to run on the specified HOST.
|
|
|
There is no convenient way to generate a list of all available
|
There is no convenient way to generate a list of all available
|
hosts.
|
hosts.
|
|
|
There are many other options available as well, but they are
|
There are many other options available as well, but they are
|
generally needed for special purposes only.
|
generally needed for special purposes only.
|
|
|
|
|
File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top
|
File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top
|
|
|
Appendix C Maintenance Commands
|
Appendix C Maintenance Commands
|
*******************************
|
*******************************
|
|
|
In addition to commands intended for GDB users, GDB includes a number
|
In addition to commands intended for GDB users, GDB includes a number
|
of commands intended for GDB developers, that are not documented
|
of commands intended for GDB developers, that are not documented
|
elsewhere in this manual. These commands are provided here for
|
elsewhere in this manual. These commands are provided here for
|
reference. (For commands that turn on debugging messages, see *Note
|
reference. (For commands that turn on debugging messages, see *Note
|
Debugging Output::.)
|
Debugging Output::.)
|
|
|
`maint agent EXPRESSION'
|
`maint agent EXPRESSION'
|
Translate the given EXPRESSION into remote agent bytecodes. This
|
Translate the given EXPRESSION into remote agent bytecodes. This
|
command is useful for debugging the Agent Expression mechanism
|
command is useful for debugging the Agent Expression mechanism
|
(*note Agent Expressions::).
|
(*note Agent Expressions::).
|
|
|
`maint info breakpoints'
|
`maint info breakpoints'
|
Using the same format as `info breakpoints', display both the
|
Using the same format as `info breakpoints', display both the
|
breakpoints you've set explicitly, and those GDB is using for
|
breakpoints you've set explicitly, and those GDB is using for
|
internal purposes. Internal breakpoints are shown with negative
|
internal purposes. Internal breakpoints are shown with negative
|
breakpoint numbers. The type column identifies what kind of
|
breakpoint numbers. The type column identifies what kind of
|
breakpoint is shown:
|
breakpoint is shown:
|
|
|
`breakpoint'
|
`breakpoint'
|
Normal, explicitly set breakpoint.
|
Normal, explicitly set breakpoint.
|
|
|
`watchpoint'
|
`watchpoint'
|
Normal, explicitly set watchpoint.
|
Normal, explicitly set watchpoint.
|
|
|
`longjmp'
|
`longjmp'
|
Internal breakpoint, used to handle correctly stepping through
|
Internal breakpoint, used to handle correctly stepping through
|
`longjmp' calls.
|
`longjmp' calls.
|
|
|
`longjmp resume'
|
`longjmp resume'
|
Internal breakpoint at the target of a `longjmp'.
|
Internal breakpoint at the target of a `longjmp'.
|
|
|
`until'
|
`until'
|
Temporary internal breakpoint used by the GDB `until' command.
|
Temporary internal breakpoint used by the GDB `until' command.
|
|
|
`finish'
|
`finish'
|
Temporary internal breakpoint used by the GDB `finish'
|
Temporary internal breakpoint used by the GDB `finish'
|
command.
|
command.
|
|
|
`shlib events'
|
`shlib events'
|
Shared library events.
|
Shared library events.
|
|
|
|
|
`maint check-symtabs'
|
`maint check-symtabs'
|
Check the consistency of psymtabs and symtabs.
|
Check the consistency of psymtabs and symtabs.
|
|
|
`maint cplus first_component NAME'
|
`maint cplus first_component NAME'
|
Print the first C++ class/namespace component of NAME.
|
Print the first C++ class/namespace component of NAME.
|
|
|
`maint cplus namespace'
|
`maint cplus namespace'
|
Print the list of possible C++ namespaces.
|
Print the list of possible C++ namespaces.
|
|
|
`maint demangle NAME'
|
`maint demangle NAME'
|
Demangle a C++ or Objective-C mangled NAME.
|
Demangle a C++ or Objective-C mangled NAME.
|
|
|
`maint deprecate COMMAND [REPLACEMENT]'
|
`maint deprecate COMMAND [REPLACEMENT]'
|
`maint undeprecate COMMAND'
|
`maint undeprecate COMMAND'
|
Deprecate or undeprecate the named COMMAND. Deprecated commands
|
Deprecate or undeprecate the named COMMAND. Deprecated commands
|
cause GDB to issue a warning when you use them. The optional
|
cause GDB to issue a warning when you use them. The optional
|
argument REPLACEMENT says which newer command should be used in
|
argument REPLACEMENT says which newer command should be used in
|
favor of the deprecated one; if it is given, GDB will mention the
|
favor of the deprecated one; if it is given, GDB will mention the
|
replacement as part of the warning.
|
replacement as part of the warning.
|
|
|
`maint dump-me'
|
`maint dump-me'
|
Cause a fatal signal in the debugger and force it to dump its core.
|
Cause a fatal signal in the debugger and force it to dump its core.
|
This is supported only on systems which support aborting a program
|
This is supported only on systems which support aborting a program
|
with the `SIGQUIT' signal.
|
with the `SIGQUIT' signal.
|
|
|
`maint internal-error [MESSAGE-TEXT]'
|
`maint internal-error [MESSAGE-TEXT]'
|
`maint internal-warning [MESSAGE-TEXT]'
|
`maint internal-warning [MESSAGE-TEXT]'
|
Cause GDB to call the internal function `internal_error' or
|
Cause GDB to call the internal function `internal_error' or
|
`internal_warning' and hence behave as though an internal error or
|
`internal_warning' and hence behave as though an internal error or
|
internal warning has been detected. In addition to reporting the
|
internal warning has been detected. In addition to reporting the
|
internal problem, these functions give the user the opportunity to
|
internal problem, these functions give the user the opportunity to
|
either quit GDB or create a core file of the current GDB session.
|
either quit GDB or create a core file of the current GDB session.
|
|
|
These commands take an optional parameter MESSAGE-TEXT that is
|
These commands take an optional parameter MESSAGE-TEXT that is
|
used as the text of the error or warning message.
|
used as the text of the error or warning message.
|
|
|
Here's an example of using `internal-error':
|
Here's an example of using `internal-error':
|
|
|
(gdb) maint internal-error testing, 1, 2
|
(gdb) maint internal-error testing, 1, 2
|
.../maint.c:121: internal-error: testing, 1, 2
|
.../maint.c:121: internal-error: testing, 1, 2
|
A problem internal to GDB has been detected. Further
|
A problem internal to GDB has been detected. Further
|
debugging may prove unreliable.
|
debugging may prove unreliable.
|
Quit this debugging session? (y or n) n
|
Quit this debugging session? (y or n) n
|
Create a core file? (y or n) n
|
Create a core file? (y or n) n
|
(gdb)
|
(gdb)
|
|
|
`maint packet TEXT'
|
`maint packet TEXT'
|
If GDB is talking to an inferior via the serial protocol, then
|
If GDB is talking to an inferior via the serial protocol, then
|
this command sends the string TEXT to the inferior, and displays
|
this command sends the string TEXT to the inferior, and displays
|
the response packet. GDB supplies the initial `$' character, the
|
the response packet. GDB supplies the initial `$' character, the
|
terminating `#' character, and the checksum.
|
terminating `#' character, and the checksum.
|
|
|
`maint print architecture [FILE]'
|
`maint print architecture [FILE]'
|
Print the entire architecture configuration. The optional argument
|
Print the entire architecture configuration. The optional argument
|
FILE names the file where the output goes.
|
FILE names the file where the output goes.
|
|
|
`maint print c-tdesc'
|
`maint print c-tdesc'
|
Print the current target description (*note Target Descriptions::)
|
Print the current target description (*note Target Descriptions::)
|
as a C source file. The created source file can be used in GDB
|
as a C source file. The created source file can be used in GDB
|
when an XML parser is not available to parse the description.
|
when an XML parser is not available to parse the description.
|
|
|
`maint print dummy-frames'
|
`maint print dummy-frames'
|
Prints the contents of GDB's internal dummy-frame stack.
|
Prints the contents of GDB's internal dummy-frame stack.
|
|
|
(gdb) b add
|
(gdb) b add
|
...
|
...
|
(gdb) print add(2,3)
|
(gdb) print add(2,3)
|
Breakpoint 2, add (a=2, b=3) at ...
|
Breakpoint 2, add (a=2, b=3) at ...
|
58 return (a + b);
|
58 return (a + b);
|
The program being debugged stopped while in a function called from GDB.
|
The program being debugged stopped while in a function called from GDB.
|
...
|
...
|
(gdb) maint print dummy-frames
|
(gdb) maint print dummy-frames
|
0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
|
0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
|
top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c}
|
top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c}
|
call_lo=0x01014000 call_hi=0x01014001
|
call_lo=0x01014000 call_hi=0x01014001
|
(gdb)
|
(gdb)
|
|
|
Takes an optional file parameter.
|
Takes an optional file parameter.
|
|
|
`maint print registers [FILE]'
|
`maint print registers [FILE]'
|
`maint print raw-registers [FILE]'
|
`maint print raw-registers [FILE]'
|
`maint print cooked-registers [FILE]'
|
`maint print cooked-registers [FILE]'
|
`maint print register-groups [FILE]'
|
`maint print register-groups [FILE]'
|
Print GDB's internal register data structures.
|
Print GDB's internal register data structures.
|
|
|
The command `maint print raw-registers' includes the contents of
|
The command `maint print raw-registers' includes the contents of
|
the raw register cache; the command `maint print cooked-registers'
|
the raw register cache; the command `maint print cooked-registers'
|
includes the (cooked) value of all registers; and the command
|
includes the (cooked) value of all registers; and the command
|
`maint print register-groups' includes the groups that each
|
`maint print register-groups' includes the groups that each
|
register is a member of. *Note Registers: (gdbint)Registers.
|
register is a member of. *Note Registers: (gdbint)Registers.
|
|
|
These commands take an optional parameter, a file name to which to
|
These commands take an optional parameter, a file name to which to
|
write the information.
|
write the information.
|
|
|
`maint print reggroups [FILE]'
|
`maint print reggroups [FILE]'
|
Print GDB's internal register group data structures. The optional
|
Print GDB's internal register group data structures. The optional
|
argument FILE tells to what file to write the information.
|
argument FILE tells to what file to write the information.
|
|
|
The register groups info looks like this:
|
The register groups info looks like this:
|
|
|
(gdb) maint print reggroups
|
(gdb) maint print reggroups
|
Group Type
|
Group Type
|
general user
|
general user
|
float user
|
float user
|
all user
|
all user
|
vector user
|
vector user
|
system user
|
system user
|
save internal
|
save internal
|
restore internal
|
restore internal
|
|
|
`flushregs'
|
`flushregs'
|
This command forces GDB to flush its internal register cache.
|
This command forces GDB to flush its internal register cache.
|
|
|
`maint print objfiles'
|
`maint print objfiles'
|
Print a dump of all known object files. For each object file, this
|
Print a dump of all known object files. For each object file, this
|
command prints its name, address in memory, and all of its psymtabs
|
command prints its name, address in memory, and all of its psymtabs
|
and symtabs.
|
and symtabs.
|
|
|
`maint print statistics'
|
`maint print statistics'
|
This command prints, for each object file in the program, various
|
This command prints, for each object file in the program, various
|
data about that object file followed by the byte cache ("bcache")
|
data about that object file followed by the byte cache ("bcache")
|
statistics for the object file. The objfile data includes the
|
statistics for the object file. The objfile data includes the
|
number of minimal, partial, full, and stabs symbols, the number of
|
number of minimal, partial, full, and stabs symbols, the number of
|
types defined by the objfile, the number of as yet unexpanded psym
|
types defined by the objfile, the number of as yet unexpanded psym
|
tables, the number of line tables and string tables, and the
|
tables, the number of line tables and string tables, and the
|
amount of memory used by the various tables. The bcache
|
amount of memory used by the various tables. The bcache
|
statistics include the counts, sizes, and counts of duplicates of
|
statistics include the counts, sizes, and counts of duplicates of
|
all and unique objects, max, average, and median entry size, total
|
all and unique objects, max, average, and median entry size, total
|
memory used and its overhead and savings, and various measures of
|
memory used and its overhead and savings, and various measures of
|
the hash table size and chain lengths.
|
the hash table size and chain lengths.
|
|
|
`maint print target-stack'
|
`maint print target-stack'
|
A "target" is an interface between the debugger and a particular
|
A "target" is an interface between the debugger and a particular
|
kind of file or process. Targets can be stacked in "strata", so
|
kind of file or process. Targets can be stacked in "strata", so
|
that more than one target can potentially respond to a request.
|
that more than one target can potentially respond to a request.
|
In particular, memory accesses will walk down the stack of targets
|
In particular, memory accesses will walk down the stack of targets
|
until they find a target that is interested in handling that
|
until they find a target that is interested in handling that
|
particular address.
|
particular address.
|
|
|
This command prints a short description of each layer that was
|
This command prints a short description of each layer that was
|
pushed on the "target stack", starting from the top layer down to
|
pushed on the "target stack", starting from the top layer down to
|
the bottom one.
|
the bottom one.
|
|
|
`maint print type EXPR'
|
`maint print type EXPR'
|
Print the type chain for a type specified by EXPR. The argument
|
Print the type chain for a type specified by EXPR. The argument
|
can be either a type name or a symbol. If it is a symbol, the
|
can be either a type name or a symbol. If it is a symbol, the
|
type of that symbol is described. The type chain produced by this
|
type of that symbol is described. The type chain produced by this
|
command is a recursive definition of the data type as stored in
|
command is a recursive definition of the data type as stored in
|
GDB's data structures, including its flags and contained types.
|
GDB's data structures, including its flags and contained types.
|
|
|
`maint set dwarf2 max-cache-age'
|
`maint set dwarf2 max-cache-age'
|
`maint show dwarf2 max-cache-age'
|
`maint show dwarf2 max-cache-age'
|
Control the DWARF 2 compilation unit cache.
|
Control the DWARF 2 compilation unit cache.
|
|
|
In object files with inter-compilation-unit references, such as
|
In object files with inter-compilation-unit references, such as
|
those produced by the GCC option `-feliminate-dwarf2-dups', the
|
those produced by the GCC option `-feliminate-dwarf2-dups', the
|
DWARF 2 reader needs to frequently refer to previously read
|
DWARF 2 reader needs to frequently refer to previously read
|
compilation units. This setting controls how long a compilation
|
compilation units. This setting controls how long a compilation
|
unit will remain in the cache if it is not referenced. A higher
|
unit will remain in the cache if it is not referenced. A higher
|
limit means that cached compilation units will be stored in memory
|
limit means that cached compilation units will be stored in memory
|
longer, and more total memory will be used. Setting it to zero
|
longer, and more total memory will be used. Setting it to zero
|
disables caching, which will slow down GDB startup, but reduce
|
disables caching, which will slow down GDB startup, but reduce
|
memory consumption.
|
memory consumption.
|
|
|
`maint set profile'
|
`maint set profile'
|
`maint show profile'
|
`maint show profile'
|
Control profiling of GDB.
|
Control profiling of GDB.
|
|
|
Profiling will be disabled until you use the `maint set profile'
|
Profiling will be disabled until you use the `maint set profile'
|
command to enable it. When you enable profiling, the system will
|
command to enable it. When you enable profiling, the system will
|
begin collecting timing and execution count data; when you disable
|
begin collecting timing and execution count data; when you disable
|
profiling or exit GDB, the results will be written to a log file.
|
profiling or exit GDB, the results will be written to a log file.
|
Remember that if you use profiling, GDB will overwrite the
|
Remember that if you use profiling, GDB will overwrite the
|
profiling log file (often called `gmon.out'). If you have a
|
profiling log file (often called `gmon.out'). If you have a
|
record of important profiling data in a `gmon.out' file, be sure
|
record of important profiling data in a `gmon.out' file, be sure
|
to move it to a safe location.
|
to move it to a safe location.
|
|
|
Configuring with `--enable-profiling' arranges for GDB to be
|
Configuring with `--enable-profiling' arranges for GDB to be
|
compiled with the `-pg' compiler option.
|
compiled with the `-pg' compiler option.
|
|
|
`maint show-debug-regs'
|
`maint show-debug-regs'
|
Control whether to show variables that mirror the x86 hardware
|
Control whether to show variables that mirror the x86 hardware
|
debug registers. Use `ON' to enable, `OFF' to disable. If
|
debug registers. Use `ON' to enable, `OFF' to disable. If
|
enabled, the debug registers values are shown when GDB inserts or
|
enabled, the debug registers values are shown when GDB inserts or
|
removes a hardware breakpoint or watchpoint, and when the inferior
|
removes a hardware breakpoint or watchpoint, and when the inferior
|
triggers a hardware-assisted breakpoint or watchpoint.
|
triggers a hardware-assisted breakpoint or watchpoint.
|
|
|
`maint space'
|
`maint space'
|
Control whether to display memory usage for each command. If set
|
Control whether to display memory usage for each command. If set
|
to a nonzero value, GDB will display how much memory each command
|
to a nonzero value, GDB will display how much memory each command
|
took, following the command's own output. This can also be
|
took, following the command's own output. This can also be
|
requested by invoking GDB with the `--statistics' command-line
|
requested by invoking GDB with the `--statistics' command-line
|
switch (*note Mode Options::).
|
switch (*note Mode Options::).
|
|
|
`maint time'
|
`maint time'
|
Control whether to display the execution time for each command. If
|
Control whether to display the execution time for each command. If
|
set to a nonzero value, GDB will display how much time it took to
|
set to a nonzero value, GDB will display how much time it took to
|
execute each command, following the command's own output. This
|
execute each command, following the command's own output. This
|
can also be requested by invoking GDB with the `--statistics'
|
can also be requested by invoking GDB with the `--statistics'
|
command-line switch (*note Mode Options::).
|
command-line switch (*note Mode Options::).
|
|
|
`maint translate-address [SECTION] ADDR'
|
`maint translate-address [SECTION] ADDR'
|
Find the symbol stored at the location specified by the address
|
Find the symbol stored at the location specified by the address
|
ADDR and an optional section name SECTION. If found, GDB prints
|
ADDR and an optional section name SECTION. If found, GDB prints
|
the name of the closest symbol and an offset from the symbol's
|
the name of the closest symbol and an offset from the symbol's
|
location to the specified address. This is similar to the `info
|
location to the specified address. This is similar to the `info
|
address' command (*note Symbols::), except that this command also
|
address' command (*note Symbols::), except that this command also
|
allows to find symbols in other sections.
|
allows to find symbols in other sections.
|
|
|
|
|
The following command is useful for non-interactive invocations of
|
The following command is useful for non-interactive invocations of
|
GDB, such as in the test suite.
|
GDB, such as in the test suite.
|
|
|
`set watchdog NSEC'
|
`set watchdog NSEC'
|
Set the maximum number of seconds GDB will wait for the target
|
Set the maximum number of seconds GDB will wait for the target
|
operation to finish. If this time expires, GDB reports and error
|
operation to finish. If this time expires, GDB reports and error
|
and the command is aborted.
|
and the command is aborted.
|
|
|
`show watchdog'
|
`show watchdog'
|
Show the current setting of the target wait timeout.
|
Show the current setting of the target wait timeout.
|
|
|
|
|
File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top
|
File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top
|
|
|
Appendix D GDB Remote Serial Protocol
|
Appendix D GDB Remote Serial Protocol
|
*************************************
|
*************************************
|
|
|
* Menu:
|
* Menu:
|
|
|
* Overview::
|
* Overview::
|
* Packets::
|
* Packets::
|
* Stop Reply Packets::
|
* Stop Reply Packets::
|
* General Query Packets::
|
* General Query Packets::
|
* Register Packet Format::
|
* Register Packet Format::
|
* Tracepoint Packets::
|
* Tracepoint Packets::
|
* Host I/O Packets::
|
* Host I/O Packets::
|
* Interrupts::
|
* Interrupts::
|
* Examples::
|
* Examples::
|
* File-I/O Remote Protocol Extension::
|
* File-I/O Remote Protocol Extension::
|
* Library List Format::
|
* Library List Format::
|
* Memory Map Format::
|
* Memory Map Format::
|
|
|
|
|
File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol
|
File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol
|
|
|
D.1 Overview
|
D.1 Overview
|
============
|
============
|
|
|
There may be occasions when you need to know something about the
|
There may be occasions when you need to know something about the
|
protocol--for example, if there is only one serial port to your target
|
protocol--for example, if there is only one serial port to your target
|
machine, you might want your program to do something special if it
|
machine, you might want your program to do something special if it
|
recognizes a packet meant for GDB.
|
recognizes a packet meant for GDB.
|
|
|
In the examples below, `->' and `<-' are used to indicate
|
In the examples below, `->' and `<-' are used to indicate
|
transmitted and received data, respectively.
|
transmitted and received data, respectively.
|
|
|
All GDB commands and responses (other than acknowledgments) are sent
|
All GDB commands and responses (other than acknowledgments) are sent
|
as a PACKET. A PACKET is introduced with the character `$', the actual
|
as a PACKET. A PACKET is introduced with the character `$', the actual
|
PACKET-DATA, and the terminating character `#' followed by a two-digit
|
PACKET-DATA, and the terminating character `#' followed by a two-digit
|
CHECKSUM:
|
CHECKSUM:
|
|
|
`$'PACKET-DATA`#'CHECKSUM
|
`$'PACKET-DATA`#'CHECKSUM
|
The two-digit CHECKSUM is computed as the modulo 256 sum of all
|
The two-digit CHECKSUM is computed as the modulo 256 sum of all
|
characters between the leading `$' and the trailing `#' (an eight bit
|
characters between the leading `$' and the trailing `#' (an eight bit
|
unsigned checksum).
|
unsigned checksum).
|
|
|
Implementors should note that prior to GDB 5.0 the protocol
|
Implementors should note that prior to GDB 5.0 the protocol
|
specification also included an optional two-digit SEQUENCE-ID:
|
specification also included an optional two-digit SEQUENCE-ID:
|
|
|
`$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM
|
`$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM
|
|
|
That SEQUENCE-ID was appended to the acknowledgment. GDB has never
|
That SEQUENCE-ID was appended to the acknowledgment. GDB has never
|
output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0
|
output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0
|
must not accept SEQUENCE-ID.
|
must not accept SEQUENCE-ID.
|
|
|
When either the host or the target machine receives a packet, the
|
When either the host or the target machine receives a packet, the
|
first response expected is an acknowledgment: either `+' (to indicate
|
first response expected is an acknowledgment: either `+' (to indicate
|
the package was received correctly) or `-' (to request retransmission):
|
the package was received correctly) or `-' (to request retransmission):
|
|
|
-> `$'PACKET-DATA`#'CHECKSUM
|
-> `$'PACKET-DATA`#'CHECKSUM
|
<- `+'
|
<- `+'
|
The host (GDB) sends COMMANDs, and the target (the debugging stub
|
The host (GDB) sends COMMANDs, and the target (the debugging stub
|
incorporated in your program) sends a RESPONSE. In the case of step
|
incorporated in your program) sends a RESPONSE. In the case of step
|
and continue COMMANDs, the response is only sent when the operation has
|
and continue COMMANDs, the response is only sent when the operation has
|
completed (the target has again stopped).
|
completed (the target has again stopped).
|
|
|
PACKET-DATA consists of a sequence of characters with the exception
|
PACKET-DATA consists of a sequence of characters with the exception
|
of `#' and `$' (see `X' packet for additional exceptions).
|
of `#' and `$' (see `X' packet for additional exceptions).
|
|
|
Fields within the packet should be separated using `,' `;' or `:'.
|
Fields within the packet should be separated using `,' `;' or `:'.
|
Except where otherwise noted all numbers are represented in HEX with
|
Except where otherwise noted all numbers are represented in HEX with
|
leading zeros suppressed.
|
leading zeros suppressed.
|
|
|
Implementors should note that prior to GDB 5.0, the character `:'
|
Implementors should note that prior to GDB 5.0, the character `:'
|
could not appear as the third character in a packet (as it would
|
could not appear as the third character in a packet (as it would
|
potentially conflict with the SEQUENCE-ID).
|
potentially conflict with the SEQUENCE-ID).
|
|
|
Binary data in most packets is encoded either as two hexadecimal
|
Binary data in most packets is encoded either as two hexadecimal
|
digits per byte of binary data. This allowed the traditional remote
|
digits per byte of binary data. This allowed the traditional remote
|
protocol to work over connections which were only seven-bit clean.
|
protocol to work over connections which were only seven-bit clean.
|
Some packets designed more recently assume an eight-bit clean
|
Some packets designed more recently assume an eight-bit clean
|
connection, and use a more efficient encoding to send and receive
|
connection, and use a more efficient encoding to send and receive
|
binary data.
|
binary data.
|
|
|
The binary data representation uses `7d' (ASCII `}') as an escape
|
The binary data representation uses `7d' (ASCII `}') as an escape
|
character. Any escaped byte is transmitted as the escape character
|
character. Any escaped byte is transmitted as the escape character
|
followed by the original character XORed with `0x20'. For example, the
|
followed by the original character XORed with `0x20'. For example, the
|
byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The
|
byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The
|
bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}')
|
bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}')
|
must always be escaped. Responses sent by the stub must also escape
|
must always be escaped. Responses sent by the stub must also escape
|
`0x2a' (ASCII `*'), so that it is not interpreted as the start of a
|
`0x2a' (ASCII `*'), so that it is not interpreted as the start of a
|
run-length encoded sequence (described next).
|
run-length encoded sequence (described next).
|
|
|
Response DATA can be run-length encoded to save space. Run-length
|
Response DATA can be run-length encoded to save space. Run-length
|
encoding replaces runs of identical characters with one instance of the
|
encoding replaces runs of identical characters with one instance of the
|
repeated character, followed by a `*' and a repeat count. The repeat
|
repeated character, followed by a `*' and a repeat count. The repeat
|
count is itself sent encoded, to avoid binary characters in DATA: a
|
count is itself sent encoded, to avoid binary characters in DATA: a
|
value of N is sent as `N+29'. For a repeat count greater or equal to
|
value of N is sent as `N+29'. For a repeat count greater or equal to
|
3, this produces a printable ASCII character, e.g. a space (ASCII code
|
3, this produces a printable ASCII character, e.g. a space (ASCII code
|
32) for a repeat count of 3. (This is because run-length encoding
|
32) for a repeat count of 3. (This is because run-length encoding
|
starts to win for counts 3 or more.) Thus, for example, `0* ' is a
|
starts to win for counts 3 or more.) Thus, for example, `0* ' is a
|
run-length encoding of "0000": the space character after `*' means
|
run-length encoding of "0000": the space character after `*' means
|
repeat the leading `0' `32 - 29 = 3' more times.
|
repeat the leading `0' `32 - 29 = 3' more times.
|
|
|
The printable characters `#' and `$' or with a numeric value greater
|
The printable characters `#' and `$' or with a numeric value greater
|
than 126 must not be used. Runs of six repeats (`#') or seven repeats
|
than 126 must not be used. Runs of six repeats (`#') or seven repeats
|
(`$') can be expanded using a repeat count of only five (`"'). For
|
(`$') can be expanded using a repeat count of only five (`"'). For
|
example, `00000000' can be encoded as `0*"00'.
|
example, `00000000' can be encoded as `0*"00'.
|
|
|
The error response returned for some packets includes a two character
|
The error response returned for some packets includes a two character
|
error number. That number is not well defined.
|
error number. That number is not well defined.
|
|
|
For any COMMAND not supported by the stub, an empty response
|
For any COMMAND not supported by the stub, an empty response
|
(`$#00') should be returned. That way it is possible to extend the
|
(`$#00') should be returned. That way it is possible to extend the
|
protocol. A newer GDB can tell if a packet is supported based on that
|
protocol. A newer GDB can tell if a packet is supported based on that
|
response.
|
response.
|
|
|
A stub is required to support the `g', `G', `m', `M', `c', and `s'
|
A stub is required to support the `g', `G', `m', `M', `c', and `s'
|
COMMANDs. All other COMMANDs are optional.
|
COMMANDs. All other COMMANDs are optional.
|
|
|
|
|
File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol
|
File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol
|
|
|
D.2 Packets
|
D.2 Packets
|
===========
|
===========
|
|
|
The following table provides a complete list of all currently defined
|
The following table provides a complete list of all currently defined
|
COMMANDs and their corresponding response DATA. *Note File-I/O Remote
|
COMMANDs and their corresponding response DATA. *Note File-I/O Remote
|
Protocol Extension::, for details about the File I/O extension of the
|
Protocol Extension::, for details about the File I/O extension of the
|
remote protocol.
|
remote protocol.
|
|
|
Each packet's description has a template showing the packet's overall
|
Each packet's description has a template showing the packet's overall
|
syntax, followed by an explanation of the packet's meaning. We include
|
syntax, followed by an explanation of the packet's meaning. We include
|
spaces in some of the templates for clarity; these are not part of the
|
spaces in some of the templates for clarity; these are not part of the
|
packet's syntax. No GDB packet uses spaces to separate its components.
|
packet's syntax. No GDB packet uses spaces to separate its components.
|
For example, a template like `foo BAR BAZ' describes a packet
|
For example, a template like `foo BAR BAZ' describes a packet
|
beginning with the three ASCII bytes `foo', followed by a BAR, followed
|
beginning with the three ASCII bytes `foo', followed by a BAR, followed
|
directly by a BAZ. GDB does not transmit a space character between the
|
directly by a BAZ. GDB does not transmit a space character between the
|
`foo' and the BAR, or between the BAR and the BAZ.
|
`foo' and the BAR, or between the BAR and the BAZ.
|
|
|
Note that all packet forms beginning with an upper- or lower-case
|
Note that all packet forms beginning with an upper- or lower-case
|
letter, other than those described here, are reserved for future use.
|
letter, other than those described here, are reserved for future use.
|
|
|
Here are the packet descriptions.
|
Here are the packet descriptions.
|
|
|
`!'
|
`!'
|
Enable extended mode. In extended mode, the remote server is made
|
Enable extended mode. In extended mode, the remote server is made
|
persistent. The `R' packet is used to restart the program being
|
persistent. The `R' packet is used to restart the program being
|
debugged.
|
debugged.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
The remote target both supports and has enabled extended mode.
|
The remote target both supports and has enabled extended mode.
|
|
|
`?'
|
`?'
|
Indicate the reason the target halted. The reply is the same as
|
Indicate the reason the target halted. The reply is the same as
|
for step and continue.
|
for step and continue.
|
|
|
Reply: *Note Stop Reply Packets::, for the reply specifications.
|
Reply: *Note Stop Reply Packets::, for the reply specifications.
|
|
|
`A ARGLEN,ARGNUM,ARG,...'
|
`A ARGLEN,ARGNUM,ARG,...'
|
Initialized `argv[]' array passed into program. ARGLEN specifies
|
Initialized `argv[]' array passed into program. ARGLEN specifies
|
the number of bytes in the hex encoded byte stream ARG. See
|
the number of bytes in the hex encoded byte stream ARG. See
|
`gdbserver' for more details.
|
`gdbserver' for more details.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
The arguments were set.
|
The arguments were set.
|
|
|
`E NN'
|
`E NN'
|
An error occurred.
|
An error occurred.
|
|
|
`b BAUD'
|
`b BAUD'
|
(Don't use this packet; its behavior is not well-defined.) Change
|
(Don't use this packet; its behavior is not well-defined.) Change
|
the serial line speed to BAUD.
|
the serial line speed to BAUD.
|
|
|
JTC: _When does the transport layer state change? When it's
|
JTC: _When does the transport layer state change? When it's
|
received, or after the ACK is transmitted. In either case, there
|
received, or after the ACK is transmitted. In either case, there
|
are problems if the command or the acknowledgment packet is
|
are problems if the command or the acknowledgment packet is
|
dropped._
|
dropped._
|
|
|
Stan: _If people really wanted to add something like this, and get
|
Stan: _If people really wanted to add something like this, and get
|
it working for the first time, they ought to modify ser-unix.c to
|
it working for the first time, they ought to modify ser-unix.c to
|
send some kind of out-of-band message to a specially-setup stub
|
send some kind of out-of-band message to a specially-setup stub
|
and have the switch happen "in between" packets, so that from
|
and have the switch happen "in between" packets, so that from
|
remote protocol's point of view, nothing actually happened._
|
remote protocol's point of view, nothing actually happened._
|
|
|
`B ADDR,MODE'
|
`B ADDR,MODE'
|
Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR.
|
Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR.
|
|
|
Don't use this packet. Use the `Z' and `z' packets instead (*note
|
Don't use this packet. Use the `Z' and `z' packets instead (*note
|
insert breakpoint or watchpoint packet::).
|
insert breakpoint or watchpoint packet::).
|
|
|
`c [ADDR]'
|
`c [ADDR]'
|
Continue. ADDR is address to resume. If ADDR is omitted, resume
|
Continue. ADDR is address to resume. If ADDR is omitted, resume
|
at current address.
|
at current address.
|
|
|
Reply: *Note Stop Reply Packets::, for the reply specifications.
|
Reply: *Note Stop Reply Packets::, for the reply specifications.
|
|
|
`C SIG[;ADDR]'
|
`C SIG[;ADDR]'
|
Continue with signal SIG (hex signal number). If `;ADDR' is
|
Continue with signal SIG (hex signal number). If `;ADDR' is
|
omitted, resume at same address.
|
omitted, resume at same address.
|
|
|
Reply: *Note Stop Reply Packets::, for the reply specifications.
|
Reply: *Note Stop Reply Packets::, for the reply specifications.
|
|
|
`d'
|
`d'
|
Toggle debug flag.
|
Toggle debug flag.
|
|
|
Don't use this packet; instead, define a general set packet (*note
|
Don't use this packet; instead, define a general set packet (*note
|
General Query Packets::).
|
General Query Packets::).
|
|
|
`D'
|
`D'
|
Detach GDB from the remote system. Sent to the remote target
|
Detach GDB from the remote system. Sent to the remote target
|
before GDB disconnects via the `detach' command.
|
before GDB disconnects via the `detach' command.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
for success
|
for success
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`F RC,EE,CF;XX'
|
`F RC,EE,CF;XX'
|
A reply from GDB to an `F' packet sent by the target. This is
|
A reply from GDB to an `F' packet sent by the target. This is
|
part of the File-I/O protocol extension. *Note File-I/O Remote
|
part of the File-I/O protocol extension. *Note File-I/O Remote
|
Protocol Extension::, for the specification.
|
Protocol Extension::, for the specification.
|
|
|
`g'
|
`g'
|
Read general registers.
|
Read general registers.
|
|
|
Reply:
|
Reply:
|
`XX...'
|
`XX...'
|
Each byte of register data is described by two hex digits.
|
Each byte of register data is described by two hex digits.
|
The bytes with the register are transmitted in target byte
|
The bytes with the register are transmitted in target byte
|
order. The size of each register and their position within
|
order. The size of each register and their position within
|
the `g' packet are determined by the GDB internal gdbarch
|
the `g' packet are determined by the GDB internal gdbarch
|
functions `DEPRECATED_REGISTER_RAW_SIZE' and
|
functions `DEPRECATED_REGISTER_RAW_SIZE' and
|
`gdbarch_register_name'. The specification of several
|
`gdbarch_register_name'. The specification of several
|
standard `g' packets is specified below.
|
standard `g' packets is specified below.
|
|
|
`E NN'
|
`E NN'
|
for an error.
|
for an error.
|
|
|
`G XX...'
|
`G XX...'
|
Write general registers. *Note read registers packet::, for a
|
Write general registers. *Note read registers packet::, for a
|
description of the XX... data.
|
description of the XX... data.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
for success
|
for success
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`H C T'
|
`H C T'
|
Set thread for subsequent operations (`m', `M', `g', `G', et.al.).
|
Set thread for subsequent operations (`m', `M', `g', `G', et.al.).
|
C depends on the operation to be performed: it should be `c' for
|
C depends on the operation to be performed: it should be `c' for
|
step and continue operations, `g' for other operations. The
|
step and continue operations, `g' for other operations. The
|
thread designator T may be `-1', meaning all the threads, a thread
|
thread designator T may be `-1', meaning all the threads, a thread
|
number, or `0' which means pick any thread.
|
number, or `0' which means pick any thread.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
for success
|
for success
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`i [ADDR[,NNN]]'
|
`i [ADDR[,NNN]]'
|
Step the remote target by a single clock cycle. If `,NNN' is
|
Step the remote target by a single clock cycle. If `,NNN' is
|
present, cycle step NNN cycles. If ADDR is present, cycle step
|
present, cycle step NNN cycles. If ADDR is present, cycle step
|
starting at that address.
|
starting at that address.
|
|
|
`I'
|
`I'
|
Signal, then cycle step. *Note step with signal packet::. *Note
|
Signal, then cycle step. *Note step with signal packet::. *Note
|
cycle step packet::.
|
cycle step packet::.
|
|
|
`k'
|
`k'
|
Kill request.
|
Kill request.
|
|
|
FIXME: _There is no description of how to operate when a specific
|
FIXME: _There is no description of how to operate when a specific
|
thread context has been selected (i.e. does 'k' kill only that
|
thread context has been selected (i.e. does 'k' kill only that
|
thread?)_.
|
thread?)_.
|
|
|
`m ADDR,LENGTH'
|
`m ADDR,LENGTH'
|
Read LENGTH bytes of memory starting at address ADDR. Note that
|
Read LENGTH bytes of memory starting at address ADDR. Note that
|
ADDR may not be aligned to any particular boundary.
|
ADDR may not be aligned to any particular boundary.
|
|
|
The stub need not use any particular size or alignment when
|
The stub need not use any particular size or alignment when
|
gathering data from memory for the response; even if ADDR is
|
gathering data from memory for the response; even if ADDR is
|
word-aligned and LENGTH is a multiple of the word size, the stub
|
word-aligned and LENGTH is a multiple of the word size, the stub
|
is free to use byte accesses, or not. For this reason, this
|
is free to use byte accesses, or not. For this reason, this
|
packet may not be suitable for accessing memory-mapped I/O devices.
|
packet may not be suitable for accessing memory-mapped I/O devices.
|
|
|
Reply:
|
Reply:
|
`XX...'
|
`XX...'
|
Memory contents; each byte is transmitted as a two-digit
|
Memory contents; each byte is transmitted as a two-digit
|
hexadecimal number. The reply may contain fewer bytes than
|
hexadecimal number. The reply may contain fewer bytes than
|
requested if the server was able to read only part of the
|
requested if the server was able to read only part of the
|
region of memory.
|
region of memory.
|
|
|
`E NN'
|
`E NN'
|
NN is errno
|
NN is errno
|
|
|
`M ADDR,LENGTH:XX...'
|
`M ADDR,LENGTH:XX...'
|
Write LENGTH bytes of memory starting at address ADDR. XX... is
|
Write LENGTH bytes of memory starting at address ADDR. XX... is
|
the data; each byte is transmitted as a two-digit hexadecimal
|
the data; each byte is transmitted as a two-digit hexadecimal
|
number.
|
number.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
for success
|
for success
|
|
|
`E NN'
|
`E NN'
|
for an error (this includes the case where only part of the
|
for an error (this includes the case where only part of the
|
data was written).
|
data was written).
|
|
|
`p N'
|
`p N'
|
Read the value of register N; N is in hex. *Note read registers
|
Read the value of register N; N is in hex. *Note read registers
|
packet::, for a description of how the returned register value is
|
packet::, for a description of how the returned register value is
|
encoded.
|
encoded.
|
|
|
Reply:
|
Reply:
|
`XX...'
|
`XX...'
|
the register's value
|
the register's value
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`'
|
`'
|
Indicating an unrecognized QUERY.
|
Indicating an unrecognized QUERY.
|
|
|
`P N...=R...'
|
`P N...=R...'
|
Write register N... with value R.... The register number N is in
|
Write register N... with value R.... The register number N is in
|
hexadecimal, and R... contains two hex digits for each byte in the
|
hexadecimal, and R... contains two hex digits for each byte in the
|
register (target byte order).
|
register (target byte order).
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
for success
|
for success
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`q NAME PARAMS...'
|
`q NAME PARAMS...'
|
`Q NAME PARAMS...'
|
`Q NAME PARAMS...'
|
General query (`q') and set (`Q'). These packets are described
|
General query (`q') and set (`Q'). These packets are described
|
fully in *Note General Query Packets::.
|
fully in *Note General Query Packets::.
|
|
|
`r'
|
`r'
|
Reset the entire system.
|
Reset the entire system.
|
|
|
Don't use this packet; use the `R' packet instead.
|
Don't use this packet; use the `R' packet instead.
|
|
|
`R XX'
|
`R XX'
|
Restart the program being debugged. XX, while needed, is ignored.
|
Restart the program being debugged. XX, while needed, is ignored.
|
This packet is only available in extended mode (*note extended
|
This packet is only available in extended mode (*note extended
|
mode::).
|
mode::).
|
|
|
The `R' packet has no reply.
|
The `R' packet has no reply.
|
|
|
`s [ADDR]'
|
`s [ADDR]'
|
Single step. ADDR is the address at which to resume. If ADDR is
|
Single step. ADDR is the address at which to resume. If ADDR is
|
omitted, resume at same address.
|
omitted, resume at same address.
|
|
|
Reply: *Note Stop Reply Packets::, for the reply specifications.
|
Reply: *Note Stop Reply Packets::, for the reply specifications.
|
|
|
`S SIG[;ADDR]'
|
`S SIG[;ADDR]'
|
Step with signal. This is analogous to the `C' packet, but
|
Step with signal. This is analogous to the `C' packet, but
|
requests a single-step, rather than a normal resumption of
|
requests a single-step, rather than a normal resumption of
|
execution.
|
execution.
|
|
|
Reply: *Note Stop Reply Packets::, for the reply specifications.
|
Reply: *Note Stop Reply Packets::, for the reply specifications.
|
|
|
`t ADDR:PP,MM'
|
`t ADDR:PP,MM'
|
Search backwards starting at address ADDR for a match with pattern
|
Search backwards starting at address ADDR for a match with pattern
|
PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3
|
PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3
|
digits.
|
digits.
|
|
|
`T XX'
|
`T XX'
|
Find out if the thread XX is alive.
|
Find out if the thread XX is alive.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
thread is still alive
|
thread is still alive
|
|
|
`E NN'
|
`E NN'
|
thread is dead
|
thread is dead
|
|
|
`v'
|
`v'
|
Packets starting with `v' are identified by a multi-letter name,
|
Packets starting with `v' are identified by a multi-letter name,
|
up to the first `;' or `?' (or the end of the packet).
|
up to the first `;' or `?' (or the end of the packet).
|
|
|
`vAttach;PID'
|
`vAttach;PID'
|
Attach to a new process with the specified process ID. PID is a
|
Attach to a new process with the specified process ID. PID is a
|
hexadecimal integer identifying the process. The attached process
|
hexadecimal integer identifying the process. The attached process
|
is stopped.
|
is stopped.
|
|
|
This packet is only available in extended mode (*note extended
|
This packet is only available in extended mode (*note extended
|
mode::).
|
mode::).
|
|
|
Reply:
|
Reply:
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`Any stop packet'
|
`Any stop packet'
|
for success (*note Stop Reply Packets::)
|
for success (*note Stop Reply Packets::)
|
|
|
`vCont[;ACTION[:TID]]...'
|
`vCont[;ACTION[:TID]]...'
|
Resume the inferior, specifying different actions for each thread.
|
Resume the inferior, specifying different actions for each thread.
|
If an action is specified with no TID, then it is applied to any
|
If an action is specified with no TID, then it is applied to any
|
threads that don't have a specific action specified; if no default
|
threads that don't have a specific action specified; if no default
|
action is specified then other threads should remain stopped.
|
action is specified then other threads should remain stopped.
|
Specifying multiple default actions is an error; specifying no
|
Specifying multiple default actions is an error; specifying no
|
actions is also an error. Thread IDs are specified in
|
actions is also an error. Thread IDs are specified in
|
hexadecimal. Currently supported actions are:
|
hexadecimal. Currently supported actions are:
|
|
|
`c'
|
`c'
|
Continue.
|
Continue.
|
|
|
`C SIG'
|
`C SIG'
|
Continue with signal SIG. SIG should be two hex digits.
|
Continue with signal SIG. SIG should be two hex digits.
|
|
|
`s'
|
`s'
|
Step.
|
Step.
|
|
|
`S SIG'
|
`S SIG'
|
Step with signal SIG. SIG should be two hex digits.
|
Step with signal SIG. SIG should be two hex digits.
|
|
|
The optional ADDR argument normally associated with these packets
|
The optional ADDR argument normally associated with these packets
|
is not supported in `vCont'.
|
is not supported in `vCont'.
|
|
|
Reply: *Note Stop Reply Packets::, for the reply specifications.
|
Reply: *Note Stop Reply Packets::, for the reply specifications.
|
|
|
`vCont?'
|
`vCont?'
|
Request a list of actions supported by the `vCont' packet.
|
Request a list of actions supported by the `vCont' packet.
|
|
|
Reply:
|
Reply:
|
`vCont[;ACTION...]'
|
`vCont[;ACTION...]'
|
The `vCont' packet is supported. Each ACTION is a supported
|
The `vCont' packet is supported. Each ACTION is a supported
|
command in the `vCont' packet.
|
command in the `vCont' packet.
|
|
|
`'
|
`'
|
The `vCont' packet is not supported.
|
The `vCont' packet is not supported.
|
|
|
`vFile:OPERATION:PARAMETER...'
|
`vFile:OPERATION:PARAMETER...'
|
Perform a file operation on the target system. For details, see
|
Perform a file operation on the target system. For details, see
|
*Note Host I/O Packets::.
|
*Note Host I/O Packets::.
|
|
|
`vFlashErase:ADDR,LENGTH'
|
`vFlashErase:ADDR,LENGTH'
|
Direct the stub to erase LENGTH bytes of flash starting at ADDR.
|
Direct the stub to erase LENGTH bytes of flash starting at ADDR.
|
The region may enclose any number of flash blocks, but its start
|
The region may enclose any number of flash blocks, but its start
|
and end must fall on block boundaries, as indicated by the flash
|
and end must fall on block boundaries, as indicated by the flash
|
block size appearing in the memory map (*note Memory Map
|
block size appearing in the memory map (*note Memory Map
|
Format::). GDB groups flash memory programming operations
|
Format::). GDB groups flash memory programming operations
|
together, and sends a `vFlashDone' request after each group; the
|
together, and sends a `vFlashDone' request after each group; the
|
stub is allowed to delay erase operation until the `vFlashDone'
|
stub is allowed to delay erase operation until the `vFlashDone'
|
packet is received.
|
packet is received.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
for success
|
for success
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`vFlashWrite:ADDR:XX...'
|
`vFlashWrite:ADDR:XX...'
|
Direct the stub to write data to flash address ADDR. The data is
|
Direct the stub to write data to flash address ADDR. The data is
|
passed in binary form using the same encoding as for the `X'
|
passed in binary form using the same encoding as for the `X'
|
packet (*note Binary Data::). The memory ranges specified by
|
packet (*note Binary Data::). The memory ranges specified by
|
`vFlashWrite' packets preceding a `vFlashDone' packet must not
|
`vFlashWrite' packets preceding a `vFlashDone' packet must not
|
overlap, and must appear in order of increasing addresses
|
overlap, and must appear in order of increasing addresses
|
(although `vFlashErase' packets for higher addresses may already
|
(although `vFlashErase' packets for higher addresses may already
|
have been received; the ordering is guaranteed only between
|
have been received; the ordering is guaranteed only between
|
`vFlashWrite' packets). If a packet writes to an address that was
|
`vFlashWrite' packets). If a packet writes to an address that was
|
neither erased by a preceding `vFlashErase' packet nor by some
|
neither erased by a preceding `vFlashErase' packet nor by some
|
other target-specific method, the results are unpredictable.
|
other target-specific method, the results are unpredictable.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
for success
|
for success
|
|
|
`E.memtype'
|
`E.memtype'
|
for vFlashWrite addressing non-flash memory
|
for vFlashWrite addressing non-flash memory
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`vFlashDone'
|
`vFlashDone'
|
Indicate to the stub that flash programming operation is finished.
|
Indicate to the stub that flash programming operation is finished.
|
The stub is permitted to delay or batch the effects of a group of
|
The stub is permitted to delay or batch the effects of a group of
|
`vFlashErase' and `vFlashWrite' packets until a `vFlashDone'
|
`vFlashErase' and `vFlashWrite' packets until a `vFlashDone'
|
packet is received. The contents of the affected regions of flash
|
packet is received. The contents of the affected regions of flash
|
memory are unpredictable until the `vFlashDone' request is
|
memory are unpredictable until the `vFlashDone' request is
|
completed.
|
completed.
|
|
|
`vRun;FILENAME[;ARGUMENT]...'
|
`vRun;FILENAME[;ARGUMENT]...'
|
Run the program FILENAME, passing it each ARGUMENT on its command
|
Run the program FILENAME, passing it each ARGUMENT on its command
|
line. The file and arguments are hex-encoded strings. If
|
line. The file and arguments are hex-encoded strings. If
|
FILENAME is an empty string, the stub may use a default program
|
FILENAME is an empty string, the stub may use a default program
|
(e.g. the last program run). The program is created in the stopped
|
(e.g. the last program run). The program is created in the stopped
|
state.
|
state.
|
|
|
This packet is only available in extended mode (*note extended
|
This packet is only available in extended mode (*note extended
|
mode::).
|
mode::).
|
|
|
Reply:
|
Reply:
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`Any stop packet'
|
`Any stop packet'
|
for success (*note Stop Reply Packets::)
|
for success (*note Stop Reply Packets::)
|
|
|
`X ADDR,LENGTH:XX...'
|
`X ADDR,LENGTH:XX...'
|
Write data to memory, where the data is transmitted in binary.
|
Write data to memory, where the data is transmitted in binary.
|
ADDR is address, LENGTH is number of bytes, `XX...' is binary data
|
ADDR is address, LENGTH is number of bytes, `XX...' is binary data
|
(*note Binary Data::).
|
(*note Binary Data::).
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
for success
|
for success
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`z TYPE,ADDR,LENGTH'
|
`z TYPE,ADDR,LENGTH'
|
`Z TYPE,ADDR,LENGTH'
|
`Z TYPE,ADDR,LENGTH'
|
Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint
|
Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint
|
starting at address ADDRESS and covering the next LENGTH bytes.
|
starting at address ADDRESS and covering the next LENGTH bytes.
|
|
|
Each breakpoint and watchpoint packet TYPE is documented
|
Each breakpoint and watchpoint packet TYPE is documented
|
separately.
|
separately.
|
|
|
_Implementation notes: A remote target shall return an empty string
|
_Implementation notes: A remote target shall return an empty string
|
for an unrecognized breakpoint or watchpoint packet TYPE. A
|
for an unrecognized breakpoint or watchpoint packet TYPE. A
|
remote target shall support either both or neither of a given
|
remote target shall support either both or neither of a given
|
`ZTYPE...' and `zTYPE...' packet pair. To avoid potential
|
`ZTYPE...' and `zTYPE...' packet pair. To avoid potential
|
problems with duplicate packets, the operations should be
|
problems with duplicate packets, the operations should be
|
implemented in an idempotent way._
|
implemented in an idempotent way._
|
|
|
`z0,ADDR,LENGTH'
|
`z0,ADDR,LENGTH'
|
`Z0,ADDR,LENGTH'
|
`Z0,ADDR,LENGTH'
|
Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR
|
Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR
|
of size LENGTH.
|
of size LENGTH.
|
|
|
A memory breakpoint is implemented by replacing the instruction at
|
A memory breakpoint is implemented by replacing the instruction at
|
ADDR with a software breakpoint or trap instruction. The LENGTH
|
ADDR with a software breakpoint or trap instruction. The LENGTH
|
is used by targets that indicates the size of the breakpoint (in
|
is used by targets that indicates the size of the breakpoint (in
|
bytes) that should be inserted (e.g., the ARM and MIPS can insert
|
bytes) that should be inserted (e.g., the ARM and MIPS can insert
|
either a 2 or 4 byte breakpoint).
|
either a 2 or 4 byte breakpoint).
|
|
|
_Implementation note: It is possible for a target to copy or move
|
_Implementation note: It is possible for a target to copy or move
|
code that contains memory breakpoints (e.g., when implementing
|
code that contains memory breakpoints (e.g., when implementing
|
overlays). The behavior of this packet, in the presence of such a
|
overlays). The behavior of this packet, in the presence of such a
|
target, is not defined._
|
target, is not defined._
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
success
|
success
|
|
|
`'
|
`'
|
not supported
|
not supported
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`z1,ADDR,LENGTH'
|
`z1,ADDR,LENGTH'
|
`Z1,ADDR,LENGTH'
|
`Z1,ADDR,LENGTH'
|
Insert (`Z1') or remove (`z1') a hardware breakpoint at address
|
Insert (`Z1') or remove (`z1') a hardware breakpoint at address
|
ADDR of size LENGTH.
|
ADDR of size LENGTH.
|
|
|
A hardware breakpoint is implemented using a mechanism that is not
|
A hardware breakpoint is implemented using a mechanism that is not
|
dependant on being able to modify the target's memory.
|
dependant on being able to modify the target's memory.
|
|
|
_Implementation note: A hardware breakpoint is not affected by code
|
_Implementation note: A hardware breakpoint is not affected by code
|
movement._
|
movement._
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
success
|
success
|
|
|
`'
|
`'
|
not supported
|
not supported
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`z2,ADDR,LENGTH'
|
`z2,ADDR,LENGTH'
|
`Z2,ADDR,LENGTH'
|
`Z2,ADDR,LENGTH'
|
Insert (`Z2') or remove (`z2') a write watchpoint.
|
Insert (`Z2') or remove (`z2') a write watchpoint.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
success
|
success
|
|
|
`'
|
`'
|
not supported
|
not supported
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`z3,ADDR,LENGTH'
|
`z3,ADDR,LENGTH'
|
`Z3,ADDR,LENGTH'
|
`Z3,ADDR,LENGTH'
|
Insert (`Z3') or remove (`z3') a read watchpoint.
|
Insert (`Z3') or remove (`z3') a read watchpoint.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
success
|
success
|
|
|
`'
|
`'
|
not supported
|
not supported
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
`z4,ADDR,LENGTH'
|
`z4,ADDR,LENGTH'
|
`Z4,ADDR,LENGTH'
|
`Z4,ADDR,LENGTH'
|
Insert (`Z4') or remove (`z4') an access watchpoint.
|
Insert (`Z4') or remove (`z4') an access watchpoint.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
success
|
success
|
|
|
`'
|
`'
|
not supported
|
not supported
|
|
|
`E NN'
|
`E NN'
|
for an error
|
for an error
|
|
|
|
|
|
|
File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol
|
File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol
|
|
|
D.3 Stop Reply Packets
|
D.3 Stop Reply Packets
|
======================
|
======================
|
|
|
The `C', `c', `S', `s' and `?' packets can receive any of the below as
|
The `C', `c', `S', `s' and `?' packets can receive any of the below as
|
a reply. In the case of the `C', `c', `S' and `s' packets, that reply
|
a reply. In the case of the `C', `c', `S' and `s' packets, that reply
|
is only returned when the target halts. In the below the exact meaning
|
is only returned when the target halts. In the below the exact meaning
|
of "signal number" is defined by the header `include/gdb/signals.h' in
|
of "signal number" is defined by the header `include/gdb/signals.h' in
|
the GDB source code.
|
the GDB source code.
|
|
|
As in the description of request packets, we include spaces in the
|
As in the description of request packets, we include spaces in the
|
reply templates for clarity; these are not part of the reply packet's
|
reply templates for clarity; these are not part of the reply packet's
|
syntax. No GDB stop reply packet uses spaces to separate its
|
syntax. No GDB stop reply packet uses spaces to separate its
|
components.
|
components.
|
|
|
`S AA'
|
`S AA'
|
The program received signal number AA (a two-digit hexadecimal
|
The program received signal number AA (a two-digit hexadecimal
|
number). This is equivalent to a `T' response with no N:R pairs.
|
number). This is equivalent to a `T' response with no N:R pairs.
|
|
|
`T AA N1:R1;N2:R2;...'
|
`T AA N1:R1;N2:R2;...'
|
The program received signal number AA (a two-digit hexadecimal
|
The program received signal number AA (a two-digit hexadecimal
|
number). This is equivalent to an `S' response, except that the
|
number). This is equivalent to an `S' response, except that the
|
`N:R' pairs can carry values of important registers and other
|
`N:R' pairs can carry values of important registers and other
|
information directly in the stop reply packet, reducing round-trip
|
information directly in the stop reply packet, reducing round-trip
|
latency. Single-step and breakpoint traps are reported this way.
|
latency. Single-step and breakpoint traps are reported this way.
|
Each `N:R' pair is interpreted as follows:
|
Each `N:R' pair is interpreted as follows:
|
|
|
* If N is a hexadecimal number, it is a register number, and the
|
* If N is a hexadecimal number, it is a register number, and the
|
corresponding R gives that register's value. R is a series
|
corresponding R gives that register's value. R is a series
|
of bytes in target byte order, with each byte given by a
|
of bytes in target byte order, with each byte given by a
|
two-digit hex number.
|
two-digit hex number.
|
|
|
* If N is `thread', then R is the thread process ID, in hex.
|
* If N is `thread', then R is the thread process ID, in hex.
|
|
|
* If N is a recognized "stop reason", it describes a more
|
* If N is a recognized "stop reason", it describes a more
|
specific event that stopped the target. The currently
|
specific event that stopped the target. The currently
|
defined stop reasons are listed below. AA should be `05',
|
defined stop reasons are listed below. AA should be `05',
|
the trap signal. At most one stop reason should be present.
|
the trap signal. At most one stop reason should be present.
|
|
|
* Otherwise, GDB should ignore this `N:R' pair and go on to the
|
* Otherwise, GDB should ignore this `N:R' pair and go on to the
|
next; this allows us to extend the protocol in the future.
|
next; this allows us to extend the protocol in the future.
|
|
|
The currently defined stop reasons are:
|
The currently defined stop reasons are:
|
|
|
`watch'
|
`watch'
|
`rwatch'
|
`rwatch'
|
`awatch'
|
`awatch'
|
The packet indicates a watchpoint hit, and R is the data
|
The packet indicates a watchpoint hit, and R is the data
|
address, in hex.
|
address, in hex.
|
|
|
`library'
|
`library'
|
The packet indicates that the loaded libraries have changed.
|
The packet indicates that the loaded libraries have changed.
|
GDB should use `qXfer:libraries:read' to fetch a new list of
|
GDB should use `qXfer:libraries:read' to fetch a new list of
|
loaded libraries. R is ignored.
|
loaded libraries. R is ignored.
|
|
|
`W AA'
|
`W AA'
|
The process exited, and AA is the exit status. This is only
|
The process exited, and AA is the exit status. This is only
|
applicable to certain targets.
|
applicable to certain targets.
|
|
|
`X AA'
|
`X AA'
|
The process terminated with signal AA.
|
The process terminated with signal AA.
|
|
|
`O XX...'
|
`O XX...'
|
`XX...' is hex encoding of ASCII data, to be written as the
|
`XX...' is hex encoding of ASCII data, to be written as the
|
program's console output. This can happen at any time while the
|
program's console output. This can happen at any time while the
|
program is running and the debugger should continue to wait for
|
program is running and the debugger should continue to wait for
|
`W', `T', etc.
|
`W', `T', etc.
|
|
|
`F CALL-ID,PARAMETER...'
|
`F CALL-ID,PARAMETER...'
|
CALL-ID is the identifier which says which host system call should
|
CALL-ID is the identifier which says which host system call should
|
be called. This is just the name of the function. Translation
|
be called. This is just the name of the function. Translation
|
into the correct system call is only applicable as it's defined in
|
into the correct system call is only applicable as it's defined in
|
GDB. *Note File-I/O Remote Protocol Extension::, for a list of
|
GDB. *Note File-I/O Remote Protocol Extension::, for a list of
|
implemented system calls.
|
implemented system calls.
|
|
|
`PARAMETER...' is a list of parameters as defined for this very
|
`PARAMETER...' is a list of parameters as defined for this very
|
system call.
|
system call.
|
|
|
The target replies with this packet when it expects GDB to call a
|
The target replies with this packet when it expects GDB to call a
|
host system call on behalf of the target. GDB replies with an
|
host system call on behalf of the target. GDB replies with an
|
appropriate `F' packet and keeps up waiting for the next reply
|
appropriate `F' packet and keeps up waiting for the next reply
|
packet from the target. The latest `C', `c', `S' or `s' action is
|
packet from the target. The latest `C', `c', `S' or `s' action is
|
expected to be continued. *Note File-I/O Remote Protocol
|
expected to be continued. *Note File-I/O Remote Protocol
|
Extension::, for more details.
|
Extension::, for more details.
|
|
|
|
|
|
|
File: gdb.info, Node: General Query Packets, Next: Register Packet Format, Prev: Stop Reply Packets, Up: Remote Protocol
|
File: gdb.info, Node: General Query Packets, Next: Register Packet Format, Prev: Stop Reply Packets, Up: Remote Protocol
|
|
|
D.4 General Query Packets
|
D.4 General Query Packets
|
=========================
|
=========================
|
|
|
Packets starting with `q' are "general query packets"; packets starting
|
Packets starting with `q' are "general query packets"; packets starting
|
with `Q' are "general set packets". General query and set packets are
|
with `Q' are "general set packets". General query and set packets are
|
a semi-unified form for retrieving and sending information to and from
|
a semi-unified form for retrieving and sending information to and from
|
the stub.
|
the stub.
|
|
|
The initial letter of a query or set packet is followed by a name
|
The initial letter of a query or set packet is followed by a name
|
indicating what sort of thing the packet applies to. For example, GDB
|
indicating what sort of thing the packet applies to. For example, GDB
|
may use a `qSymbol' packet to exchange symbol definitions with the
|
may use a `qSymbol' packet to exchange symbol definitions with the
|
stub. These packet names follow some conventions:
|
stub. These packet names follow some conventions:
|
|
|
* The name must not contain commas, colons or semicolons.
|
* The name must not contain commas, colons or semicolons.
|
|
|
* Most GDB query and set packets have a leading upper case letter.
|
* Most GDB query and set packets have a leading upper case letter.
|
|
|
* The names of custom vendor packets should use a company prefix, in
|
* The names of custom vendor packets should use a company prefix, in
|
lower case, followed by a period. For example, packets designed at
|
lower case, followed by a period. For example, packets designed at
|
the Acme Corporation might begin with `qacme.foo' (for querying
|
the Acme Corporation might begin with `qacme.foo' (for querying
|
foos) or `Qacme.bar' (for setting bars).
|
foos) or `Qacme.bar' (for setting bars).
|
|
|
The name of a query or set packet should be separated from any
|
The name of a query or set packet should be separated from any
|
parameters by a `:'; the parameters themselves should be separated by
|
parameters by a `:'; the parameters themselves should be separated by
|
`,' or `;'. Stubs must be careful to match the full packet name, and
|
`,' or `;'. Stubs must be careful to match the full packet name, and
|
check for a separator or the end of the packet, in case two packet
|
check for a separator or the end of the packet, in case two packet
|
names share a common prefix. New packets should not begin with `qC',
|
names share a common prefix. New packets should not begin with `qC',
|
`qP', or `qL'(1).
|
`qP', or `qL'(1).
|
|
|
Like the descriptions of the other packets, each description here
|
Like the descriptions of the other packets, each description here
|
has a template showing the packet's overall syntax, followed by an
|
has a template showing the packet's overall syntax, followed by an
|
explanation of the packet's meaning. We include spaces in some of the
|
explanation of the packet's meaning. We include spaces in some of the
|
templates for clarity; these are not part of the packet's syntax. No
|
templates for clarity; these are not part of the packet's syntax. No
|
GDB packet uses spaces to separate its components.
|
GDB packet uses spaces to separate its components.
|
|
|
Here are the currently defined query and set packets:
|
Here are the currently defined query and set packets:
|
|
|
`qC'
|
`qC'
|
Return the current thread id.
|
Return the current thread id.
|
|
|
Reply:
|
Reply:
|
`QC PID'
|
`QC PID'
|
Where PID is an unsigned hexadecimal process id.
|
Where PID is an unsigned hexadecimal process id.
|
|
|
`(anything else)'
|
`(anything else)'
|
Any other reply implies the old pid.
|
Any other reply implies the old pid.
|
|
|
`qCRC:ADDR,LENGTH'
|
`qCRC:ADDR,LENGTH'
|
Compute the CRC checksum of a block of memory. Reply:
|
Compute the CRC checksum of a block of memory. Reply:
|
`E NN'
|
`E NN'
|
An error (such as memory fault)
|
An error (such as memory fault)
|
|
|
`C CRC32'
|
`C CRC32'
|
The specified memory region's checksum is CRC32.
|
The specified memory region's checksum is CRC32.
|
|
|
`qfThreadInfo'
|
`qfThreadInfo'
|
`qsThreadInfo'
|
`qsThreadInfo'
|
Obtain a list of all active thread ids from the target (OS).
|
Obtain a list of all active thread ids from the target (OS).
|
Since there may be too many active threads to fit into one reply
|
Since there may be too many active threads to fit into one reply
|
packet, this query works iteratively: it may require more than one
|
packet, this query works iteratively: it may require more than one
|
query/reply sequence to obtain the entire list of threads. The
|
query/reply sequence to obtain the entire list of threads. The
|
first query of the sequence will be the `qfThreadInfo' query;
|
first query of the sequence will be the `qfThreadInfo' query;
|
subsequent queries in the sequence will be the `qsThreadInfo'
|
subsequent queries in the sequence will be the `qsThreadInfo'
|
query.
|
query.
|
|
|
NOTE: This packet replaces the `qL' query (see below).
|
NOTE: This packet replaces the `qL' query (see below).
|
|
|
Reply:
|
Reply:
|
`m ID'
|
`m ID'
|
A single thread id
|
A single thread id
|
|
|
`m ID,ID...'
|
`m ID,ID...'
|
a comma-separated list of thread ids
|
a comma-separated list of thread ids
|
|
|
`l'
|
`l'
|
(lower case letter `L') denotes end of list.
|
(lower case letter `L') denotes end of list.
|
|
|
In response to each query, the target will reply with a list of
|
In response to each query, the target will reply with a list of
|
one or more thread ids, in big-endian unsigned hex, separated by
|
one or more thread ids, in big-endian unsigned hex, separated by
|
commas. GDB will respond to each reply with a request for more
|
commas. GDB will respond to each reply with a request for more
|
thread ids (using the `qs' form of the query), until the target
|
thread ids (using the `qs' form of the query), until the target
|
responds with `l' (lower-case el, for "last").
|
responds with `l' (lower-case el, for "last").
|
|
|
`qGetTLSAddr:THREAD-ID,OFFSET,LM'
|
`qGetTLSAddr:THREAD-ID,OFFSET,LM'
|
Fetch the address associated with thread local storage specified
|
Fetch the address associated with thread local storage specified
|
by THREAD-ID, OFFSET, and LM.
|
by THREAD-ID, OFFSET, and LM.
|
|
|
THREAD-ID is the (big endian, hex encoded) thread id associated
|
THREAD-ID is the (big endian, hex encoded) thread id associated
|
with the thread for which to fetch the TLS address.
|
with the thread for which to fetch the TLS address.
|
|
|
OFFSET is the (big endian, hex encoded) offset associated with the
|
OFFSET is the (big endian, hex encoded) offset associated with the
|
thread local variable. (This offset is obtained from the debug
|
thread local variable. (This offset is obtained from the debug
|
information associated with the variable.)
|
information associated with the variable.)
|
|
|
LM is the (big endian, hex encoded) OS/ABI-specific encoding of the
|
LM is the (big endian, hex encoded) OS/ABI-specific encoding of the
|
the load module associated with the thread local storage. For
|
the load module associated with the thread local storage. For
|
example, a GNU/Linux system will pass the link map address of the
|
example, a GNU/Linux system will pass the link map address of the
|
shared object associated with the thread local storage under
|
shared object associated with the thread local storage under
|
consideration. Other operating environments may choose to
|
consideration. Other operating environments may choose to
|
represent the load module differently, so the precise meaning of
|
represent the load module differently, so the precise meaning of
|
this parameter will vary.
|
this parameter will vary.
|
|
|
Reply:
|
Reply:
|
`XX...'
|
`XX...'
|
Hex encoded (big endian) bytes representing the address of
|
Hex encoded (big endian) bytes representing the address of
|
the thread local storage requested.
|
the thread local storage requested.
|
|
|
`E NN'
|
`E NN'
|
An error occurred. NN are hex digits.
|
An error occurred. NN are hex digits.
|
|
|
`'
|
`'
|
An empty reply indicates that `qGetTLSAddr' is not supported
|
An empty reply indicates that `qGetTLSAddr' is not supported
|
by the stub.
|
by the stub.
|
|
|
`qL STARTFLAG THREADCOUNT NEXTTHREAD'
|
`qL STARTFLAG THREADCOUNT NEXTTHREAD'
|
Obtain thread information from RTOS. Where: STARTFLAG (one hex
|
Obtain thread information from RTOS. Where: STARTFLAG (one hex
|
digit) is one to indicate the first query and zero to indicate a
|
digit) is one to indicate the first query and zero to indicate a
|
subsequent query; THREADCOUNT (two hex digits) is the maximum
|
subsequent query; THREADCOUNT (two hex digits) is the maximum
|
number of threads the response packet can contain; and NEXTTHREAD
|
number of threads the response packet can contain; and NEXTTHREAD
|
(eight hex digits), for subsequent queries (STARTFLAG is zero), is
|
(eight hex digits), for subsequent queries (STARTFLAG is zero), is
|
returned in the response as ARGTHREAD.
|
returned in the response as ARGTHREAD.
|
|
|
Don't use this packet; use the `qfThreadInfo' query instead (see
|
Don't use this packet; use the `qfThreadInfo' query instead (see
|
above).
|
above).
|
|
|
Reply:
|
Reply:
|
`qM COUNT DONE ARGTHREAD THREAD...'
|
`qM COUNT DONE ARGTHREAD THREAD...'
|
Where: COUNT (two hex digits) is the number of threads being
|
Where: COUNT (two hex digits) is the number of threads being
|
returned; DONE (one hex digit) is zero to indicate more
|
returned; DONE (one hex digit) is zero to indicate more
|
threads and one indicates no further threads; ARGTHREADID
|
threads and one indicates no further threads; ARGTHREADID
|
(eight hex digits) is NEXTTHREAD from the request packet;
|
(eight hex digits) is NEXTTHREAD from the request packet;
|
THREAD... is a sequence of thread IDs from the target.
|
THREAD... is a sequence of thread IDs from the target.
|
THREADID (eight hex digits). See
|
THREADID (eight hex digits). See
|
`remote.c:parse_threadlist_response()'.
|
`remote.c:parse_threadlist_response()'.
|
|
|
`qOffsets'
|
`qOffsets'
|
Get section offsets that the target used when relocating the
|
Get section offsets that the target used when relocating the
|
downloaded image.
|
downloaded image.
|
|
|
Reply:
|
Reply:
|
`Text=XXX;Data=YYY[;Bss=ZZZ]'
|
`Text=XXX;Data=YYY[;Bss=ZZZ]'
|
Relocate the `Text' section by XXX from its original address.
|
Relocate the `Text' section by XXX from its original address.
|
Relocate the `Data' section by YYY from its original address.
|
Relocate the `Data' section by YYY from its original address.
|
If the object file format provides segment information (e.g.
|
If the object file format provides segment information (e.g.
|
ELF `PT_LOAD' program headers), GDB will relocate entire
|
ELF `PT_LOAD' program headers), GDB will relocate entire
|
segments by the supplied offsets.
|
segments by the supplied offsets.
|
|
|
_Note: while a `Bss' offset may be included in the response,
|
_Note: while a `Bss' offset may be included in the response,
|
GDB ignores this and instead applies the `Data' offset to the
|
GDB ignores this and instead applies the `Data' offset to the
|
`Bss' section._
|
`Bss' section._
|
|
|
`TextSeg=XXX[;DataSeg=YYY]'
|
`TextSeg=XXX[;DataSeg=YYY]'
|
Relocate the first segment of the object file, which
|
Relocate the first segment of the object file, which
|
conventionally contains program code, to a starting address
|
conventionally contains program code, to a starting address
|
of XXX. If `DataSeg' is specified, relocate the second
|
of XXX. If `DataSeg' is specified, relocate the second
|
segment, which conventionally contains modifiable data, to a
|
segment, which conventionally contains modifiable data, to a
|
starting address of YYY. GDB will report an error if the
|
starting address of YYY. GDB will report an error if the
|
object file does not contain segment information, or does not
|
object file does not contain segment information, or does not
|
contain at least as many segments as mentioned in the reply.
|
contain at least as many segments as mentioned in the reply.
|
Extra segments are kept at fixed offsets relative to the last
|
Extra segments are kept at fixed offsets relative to the last
|
relocated segment.
|
relocated segment.
|
|
|
`qP MODE THREADID'
|
`qP MODE THREADID'
|
Returns information on THREADID. Where: MODE is a hex encoded 32
|
Returns information on THREADID. Where: MODE is a hex encoded 32
|
bit mode; THREADID is a hex encoded 64 bit thread ID.
|
bit mode; THREADID is a hex encoded 64 bit thread ID.
|
|
|
Don't use this packet; use the `qThreadExtraInfo' query instead
|
Don't use this packet; use the `qThreadExtraInfo' query instead
|
(see below).
|
(see below).
|
|
|
Reply: see `remote.c:remote_unpack_thread_info_response()'.
|
Reply: see `remote.c:remote_unpack_thread_info_response()'.
|
|
|
`QPassSignals: SIGNAL [;SIGNAL]...'
|
`QPassSignals: SIGNAL [;SIGNAL]...'
|
Each listed SIGNAL should be passed directly to the inferior
|
Each listed SIGNAL should be passed directly to the inferior
|
process. Signals are numbered identically to continue packets and
|
process. Signals are numbered identically to continue packets and
|
stop replies (*note Stop Reply Packets::). Each SIGNAL list item
|
stop replies (*note Stop Reply Packets::). Each SIGNAL list item
|
should be strictly greater than the previous item. These signals
|
should be strictly greater than the previous item. These signals
|
do not need to stop the inferior, or be reported to GDB. All
|
do not need to stop the inferior, or be reported to GDB. All
|
other signals should be reported to GDB. Multiple `QPassSignals'
|
other signals should be reported to GDB. Multiple `QPassSignals'
|
packets do not combine; any earlier `QPassSignals' list is
|
packets do not combine; any earlier `QPassSignals' list is
|
completely replaced by the new list. This packet improves
|
completely replaced by the new list. This packet improves
|
performance when using `handle SIGNAL nostop noprint pass'.
|
performance when using `handle SIGNAL nostop noprint pass'.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
The request succeeded.
|
The request succeeded.
|
|
|
`E NN'
|
`E NN'
|
An error occurred. NN are hex digits.
|
An error occurred. NN are hex digits.
|
|
|
`'
|
`'
|
An empty reply indicates that `QPassSignals' is not supported
|
An empty reply indicates that `QPassSignals' is not supported
|
by the stub.
|
by the stub.
|
|
|
Use of this packet is controlled by the `set remote pass-signals'
|
Use of this packet is controlled by the `set remote pass-signals'
|
command (*note set remote pass-signals: Remote Configuration.).
|
command (*note set remote pass-signals: Remote Configuration.).
|
This packet is not probed by default; the remote stub must request
|
This packet is not probed by default; the remote stub must request
|
it, by supplying an appropriate `qSupported' response (*note
|
it, by supplying an appropriate `qSupported' response (*note
|
qSupported::).
|
qSupported::).
|
|
|
`qRcmd,COMMAND'
|
`qRcmd,COMMAND'
|
COMMAND (hex encoded) is passed to the local interpreter for
|
COMMAND (hex encoded) is passed to the local interpreter for
|
execution. Invalid commands should be reported using the output
|
execution. Invalid commands should be reported using the output
|
string. Before the final result packet, the target may also
|
string. Before the final result packet, the target may also
|
respond with a number of intermediate `OOUTPUT' console output
|
respond with a number of intermediate `OOUTPUT' console output
|
packets. _Implementors should note that providing access to a
|
packets. _Implementors should note that providing access to a
|
stubs's interpreter may have security implications_.
|
stubs's interpreter may have security implications_.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
A command response with no output.
|
A command response with no output.
|
|
|
`OUTPUT'
|
`OUTPUT'
|
A command response with the hex encoded output string OUTPUT.
|
A command response with the hex encoded output string OUTPUT.
|
|
|
`E NN'
|
`E NN'
|
Indicate a badly formed request.
|
Indicate a badly formed request.
|
|
|
`'
|
`'
|
An empty reply indicates that `qRcmd' is not recognized.
|
An empty reply indicates that `qRcmd' is not recognized.
|
|
|
(Note that the `qRcmd' packet's name is separated from the command
|
(Note that the `qRcmd' packet's name is separated from the command
|
by a `,', not a `:', contrary to the naming conventions above.
|
by a `,', not a `:', contrary to the naming conventions above.
|
Please don't use this packet as a model for new packets.)
|
Please don't use this packet as a model for new packets.)
|
|
|
`qSupported [:GDBFEATURE [;GDBFEATURE]... ]'
|
`qSupported [:GDBFEATURE [;GDBFEATURE]... ]'
|
Tell the remote stub about features supported by GDB, and query
|
Tell the remote stub about features supported by GDB, and query
|
the stub for features it supports. This packet allows GDB and the
|
the stub for features it supports. This packet allows GDB and the
|
remote stub to take advantage of each others' features.
|
remote stub to take advantage of each others' features.
|
`qSupported' also consolidates multiple feature probes at startup,
|
`qSupported' also consolidates multiple feature probes at startup,
|
to improve GDB performance--a single larger packet performs better
|
to improve GDB performance--a single larger packet performs better
|
than multiple smaller probe packets on high-latency links. Some
|
than multiple smaller probe packets on high-latency links. Some
|
features may enable behavior which must not be on by default, e.g.
|
features may enable behavior which must not be on by default, e.g.
|
because it would confuse older clients or stubs. Other features
|
because it would confuse older clients or stubs. Other features
|
may describe packets which could be automatically probed for, but
|
may describe packets which could be automatically probed for, but
|
are not. These features must be reported before GDB will use
|
are not. These features must be reported before GDB will use
|
them. This "default unsupported" behavior is not appropriate for
|
them. This "default unsupported" behavior is not appropriate for
|
all packets, but it helps to keep the initial connection time
|
all packets, but it helps to keep the initial connection time
|
under control with new versions of GDB which support increasing
|
under control with new versions of GDB which support increasing
|
numbers of packets.
|
numbers of packets.
|
|
|
Reply:
|
Reply:
|
`STUBFEATURE [;STUBFEATURE]...'
|
`STUBFEATURE [;STUBFEATURE]...'
|
The stub supports or does not support each returned
|
The stub supports or does not support each returned
|
STUBFEATURE, depending on the form of each STUBFEATURE (see
|
STUBFEATURE, depending on the form of each STUBFEATURE (see
|
below for the possible forms).
|
below for the possible forms).
|
|
|
`'
|
`'
|
An empty reply indicates that `qSupported' is not recognized,
|
An empty reply indicates that `qSupported' is not recognized,
|
or that no features needed to be reported to GDB.
|
or that no features needed to be reported to GDB.
|
|
|
The allowed forms for each feature (either a GDBFEATURE in the
|
The allowed forms for each feature (either a GDBFEATURE in the
|
`qSupported' packet, or a STUBFEATURE in the response) are:
|
`qSupported' packet, or a STUBFEATURE in the response) are:
|
|
|
`NAME=VALUE'
|
`NAME=VALUE'
|
The remote protocol feature NAME is supported, and associated
|
The remote protocol feature NAME is supported, and associated
|
with the specified VALUE. The format of VALUE depends on the
|
with the specified VALUE. The format of VALUE depends on the
|
feature, but it must not include a semicolon.
|
feature, but it must not include a semicolon.
|
|
|
`NAME+'
|
`NAME+'
|
The remote protocol feature NAME is supported, and does not
|
The remote protocol feature NAME is supported, and does not
|
need an associated value.
|
need an associated value.
|
|
|
`NAME-'
|
`NAME-'
|
The remote protocol feature NAME is not supported.
|
The remote protocol feature NAME is not supported.
|
|
|
`NAME?'
|
`NAME?'
|
The remote protocol feature NAME may be supported, and GDB
|
The remote protocol feature NAME may be supported, and GDB
|
should auto-detect support in some other way when it is
|
should auto-detect support in some other way when it is
|
needed. This form will not be used for GDBFEATURE
|
needed. This form will not be used for GDBFEATURE
|
notifications, but may be used for STUBFEATURE responses.
|
notifications, but may be used for STUBFEATURE responses.
|
|
|
Whenever the stub receives a `qSupported' request, the supplied
|
Whenever the stub receives a `qSupported' request, the supplied
|
set of GDB features should override any previous request. This
|
set of GDB features should override any previous request. This
|
allows GDB to put the stub in a known state, even if the stub had
|
allows GDB to put the stub in a known state, even if the stub had
|
previously been communicating with a different version of GDB.
|
previously been communicating with a different version of GDB.
|
|
|
No values of GDBFEATURE (for the packet sent by GDB) are defined
|
No values of GDBFEATURE (for the packet sent by GDB) are defined
|
yet. Stubs should ignore any unknown values for GDBFEATURE. Any
|
yet. Stubs should ignore any unknown values for GDBFEATURE. Any
|
GDB which sends a `qSupported' packet supports receiving packets
|
GDB which sends a `qSupported' packet supports receiving packets
|
of unlimited length (earlier versions of GDB may reject overly
|
of unlimited length (earlier versions of GDB may reject overly
|
long responses). Values for GDBFEATURE may be defined in the
|
long responses). Values for GDBFEATURE may be defined in the
|
future to let the stub take advantage of new features in GDB, e.g.
|
future to let the stub take advantage of new features in GDB, e.g.
|
incompatible improvements in the remote protocol--support for
|
incompatible improvements in the remote protocol--support for
|
unlimited length responses would be a GDBFEATURE example, if it
|
unlimited length responses would be a GDBFEATURE example, if it
|
were not implied by the `qSupported' query. The stub's reply
|
were not implied by the `qSupported' query. The stub's reply
|
should be independent of the GDBFEATURE entries sent by GDB; first
|
should be independent of the GDBFEATURE entries sent by GDB; first
|
GDB describes all the features it supports, and then the stub
|
GDB describes all the features it supports, and then the stub
|
replies with all the features it supports.
|
replies with all the features it supports.
|
|
|
Similarly, GDB will silently ignore unrecognized stub feature
|
Similarly, GDB will silently ignore unrecognized stub feature
|
responses, as long as each response uses one of the standard forms.
|
responses, as long as each response uses one of the standard forms.
|
|
|
Some features are flags. A stub which supports a flag feature
|
Some features are flags. A stub which supports a flag feature
|
should respond with a `+' form response. Other features require
|
should respond with a `+' form response. Other features require
|
values, and the stub should respond with an `=' form response.
|
values, and the stub should respond with an `=' form response.
|
|
|
Each feature has a default value, which GDB will use if
|
Each feature has a default value, which GDB will use if
|
`qSupported' is not available or if the feature is not mentioned
|
`qSupported' is not available or if the feature is not mentioned
|
in the `qSupported' response. The default values are fixed; a
|
in the `qSupported' response. The default values are fixed; a
|
stub is free to omit any feature responses that match the defaults.
|
stub is free to omit any feature responses that match the defaults.
|
|
|
Not all features can be probed, but for those which can, the
|
Not all features can be probed, but for those which can, the
|
probing mechanism is useful: in some cases, a stub's internal
|
probing mechanism is useful: in some cases, a stub's internal
|
architecture may not allow the protocol layer to know some
|
architecture may not allow the protocol layer to know some
|
information about the underlying target in advance. This is
|
information about the underlying target in advance. This is
|
especially common in stubs which may be configured for multiple
|
especially common in stubs which may be configured for multiple
|
targets.
|
targets.
|
|
|
These are the currently defined stub features and their properties:
|
These are the currently defined stub features and their properties:
|
|
|
Feature Name Value Default Probe Allowed
|
Feature Name Value Default Probe Allowed
|
Required
|
Required
|
`PacketSize' Yes `-' No
|
`PacketSize' Yes `-' No
|
`qXfer:auxv:read' No `-' Yes
|
`qXfer:auxv:read' No `-' Yes
|
`qXfer:features:read' No `-' Yes
|
`qXfer:features:read' No `-' Yes
|
`qXfer:libraries:read' No `-' Yes
|
`qXfer:libraries:read' No `-' Yes
|
`qXfer:memory-map:read' No `-' Yes
|
`qXfer:memory-map:read' No `-' Yes
|
`qXfer:spu:read' No `-' Yes
|
`qXfer:spu:read' No `-' Yes
|
`qXfer:spu:write' No `-' Yes
|
`qXfer:spu:write' No `-' Yes
|
`QPassSignals' No `-' Yes
|
`QPassSignals' No `-' Yes
|
|
|
These are the currently defined stub features, in more detail:
|
These are the currently defined stub features, in more detail:
|
|
|
`PacketSize=BYTES'
|
`PacketSize=BYTES'
|
The remote stub can accept packets up to at least BYTES in
|
The remote stub can accept packets up to at least BYTES in
|
length. GDB will send packets up to this size for bulk
|
length. GDB will send packets up to this size for bulk
|
transfers, and will never send larger packets. This is a
|
transfers, and will never send larger packets. This is a
|
limit on the data characters in the packet, including the
|
limit on the data characters in the packet, including the
|
frame and checksum. There is no trailing NUL byte in a
|
frame and checksum. There is no trailing NUL byte in a
|
remote protocol packet; if the stub stores packets in a
|
remote protocol packet; if the stub stores packets in a
|
NUL-terminated format, it should allow an extra byte in its
|
NUL-terminated format, it should allow an extra byte in its
|
buffer for the NUL. If this stub feature is not supported,
|
buffer for the NUL. If this stub feature is not supported,
|
GDB guesses based on the size of the `g' packet response.
|
GDB guesses based on the size of the `g' packet response.
|
|
|
`qXfer:auxv:read'
|
`qXfer:auxv:read'
|
The remote stub understands the `qXfer:auxv:read' packet
|
The remote stub understands the `qXfer:auxv:read' packet
|
(*note qXfer auxiliary vector read::).
|
(*note qXfer auxiliary vector read::).
|
|
|
`qXfer:features:read'
|
`qXfer:features:read'
|
The remote stub understands the `qXfer:features:read' packet
|
The remote stub understands the `qXfer:features:read' packet
|
(*note qXfer target description read::).
|
(*note qXfer target description read::).
|
|
|
`qXfer:libraries:read'
|
`qXfer:libraries:read'
|
The remote stub understands the `qXfer:libraries:read' packet
|
The remote stub understands the `qXfer:libraries:read' packet
|
(*note qXfer library list read::).
|
(*note qXfer library list read::).
|
|
|
`qXfer:memory-map:read'
|
`qXfer:memory-map:read'
|
The remote stub understands the `qXfer:memory-map:read' packet
|
The remote stub understands the `qXfer:memory-map:read' packet
|
(*note qXfer memory map read::).
|
(*note qXfer memory map read::).
|
|
|
`qXfer:spu:read'
|
`qXfer:spu:read'
|
The remote stub understands the `qXfer:spu:read' packet
|
The remote stub understands the `qXfer:spu:read' packet
|
(*note qXfer spu read::).
|
(*note qXfer spu read::).
|
|
|
`qXfer:spu:write'
|
`qXfer:spu:write'
|
The remote stub understands the `qXfer:spu:write' packet
|
The remote stub understands the `qXfer:spu:write' packet
|
(*note qXfer spu write::).
|
(*note qXfer spu write::).
|
|
|
`QPassSignals'
|
`QPassSignals'
|
The remote stub understands the `QPassSignals' packet (*note
|
The remote stub understands the `QPassSignals' packet (*note
|
QPassSignals::).
|
QPassSignals::).
|
|
|
|
|
`qSymbol::'
|
`qSymbol::'
|
Notify the target that GDB is prepared to serve symbol lookup
|
Notify the target that GDB is prepared to serve symbol lookup
|
requests. Accept requests from the target for the values of
|
requests. Accept requests from the target for the values of
|
symbols.
|
symbols.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
The target does not need to look up any (more) symbols.
|
The target does not need to look up any (more) symbols.
|
|
|
`qSymbol:SYM_NAME'
|
`qSymbol:SYM_NAME'
|
The target requests the value of symbol SYM_NAME (hex
|
The target requests the value of symbol SYM_NAME (hex
|
encoded). GDB may provide the value by using the
|
encoded). GDB may provide the value by using the
|
`qSymbol:SYM_VALUE:SYM_NAME' message, described below.
|
`qSymbol:SYM_VALUE:SYM_NAME' message, described below.
|
|
|
`qSymbol:SYM_VALUE:SYM_NAME'
|
`qSymbol:SYM_VALUE:SYM_NAME'
|
Set the value of SYM_NAME to SYM_VALUE.
|
Set the value of SYM_NAME to SYM_VALUE.
|
|
|
SYM_NAME (hex encoded) is the name of a symbol whose value the
|
SYM_NAME (hex encoded) is the name of a symbol whose value the
|
target has previously requested.
|
target has previously requested.
|
|
|
SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot
|
SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot
|
supply a value for SYM_NAME, then this field will be empty.
|
supply a value for SYM_NAME, then this field will be empty.
|
|
|
Reply:
|
Reply:
|
`OK'
|
`OK'
|
The target does not need to look up any (more) symbols.
|
The target does not need to look up any (more) symbols.
|
|
|
`qSymbol:SYM_NAME'
|
`qSymbol:SYM_NAME'
|
The target requests the value of a new symbol SYM_NAME (hex
|
The target requests the value of a new symbol SYM_NAME (hex
|
encoded). GDB will continue to supply the values of symbols
|
encoded). GDB will continue to supply the values of symbols
|
(if available), until the target ceases to request them.
|
(if available), until the target ceases to request them.
|
|
|
`QTDP'
|
`QTDP'
|
`QTFrame'
|
`QTFrame'
|
*Note Tracepoint Packets::.
|
*Note Tracepoint Packets::.
|
|
|
`qThreadExtraInfo,ID'
|
`qThreadExtraInfo,ID'
|
Obtain a printable string description of a thread's attributes from
|
Obtain a printable string description of a thread's attributes from
|
the target OS. ID is a thread-id in big-endian hex. This string
|
the target OS. ID is a thread-id in big-endian hex. This string
|
may contain anything that the target OS thinks is interesting for
|
may contain anything that the target OS thinks is interesting for
|
GDB to tell the user about the thread. The string is displayed in
|
GDB to tell the user about the thread. The string is displayed in
|
GDB's `info threads' display. Some examples of possible thread
|
GDB's `info threads' display. Some examples of possible thread
|
extra info strings are `Runnable', or `Blocked on Mutex'.
|
extra info strings are `Runnable', or `Blocked on Mutex'.
|
|
|
Reply:
|
Reply:
|
`XX...'
|
`XX...'
|
Where `XX...' is a hex encoding of ASCII data, comprising the
|
Where `XX...' is a hex encoding of ASCII data, comprising the
|
printable string containing the extra information about the
|
printable string containing the extra information about the
|
thread's attributes.
|
thread's attributes.
|
|
|
(Note that the `qThreadExtraInfo' packet's name is separated from
|
(Note that the `qThreadExtraInfo' packet's name is separated from
|
the command by a `,', not a `:', contrary to the naming
|
the command by a `,', not a `:', contrary to the naming
|
conventions above. Please don't use this packet as a model for new
|
conventions above. Please don't use this packet as a model for new
|
packets.)
|
packets.)
|
|
|
`QTStart'
|
`QTStart'
|
`QTStop'
|
`QTStop'
|
`QTinit'
|
`QTinit'
|
`QTro'
|
`QTro'
|
`qTStatus'
|
`qTStatus'
|
*Note Tracepoint Packets::.
|
*Note Tracepoint Packets::.
|
|
|
`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
|
`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
|
Read uninterpreted bytes from the target's special data area
|
Read uninterpreted bytes from the target's special data area
|
identified by the keyword OBJECT. Request LENGTH bytes starting
|
identified by the keyword OBJECT. Request LENGTH bytes starting
|
at OFFSET bytes into the data. The content and encoding of ANNEX
|
at OFFSET bytes into the data. The content and encoding of ANNEX
|
is specific to OBJECT; it can supply additional details about what
|
is specific to OBJECT; it can supply additional details about what
|
data to access.
|
data to access.
|
|
|
Here are the specific requests of this form defined so far. All
|
Here are the specific requests of this form defined so far. All
|
`qXfer:OBJECT:read:...' requests use the same reply formats,
|
`qXfer:OBJECT:read:...' requests use the same reply formats,
|
listed below.
|
listed below.
|
|
|
`qXfer:auxv:read::OFFSET,LENGTH'
|
`qXfer:auxv:read::OFFSET,LENGTH'
|
Access the target's "auxiliary vector". *Note auxiliary
|
Access the target's "auxiliary vector". *Note auxiliary
|
vector: OS Information. Note ANNEX must be empty.
|
vector: OS Information. Note ANNEX must be empty.
|
|
|
This packet is not probed by default; the remote stub must
|
This packet is not probed by default; the remote stub must
|
request it, by supplying an appropriate `qSupported' response
|
request it, by supplying an appropriate `qSupported' response
|
(*note qSupported::).
|
(*note qSupported::).
|
|
|
`qXfer:features:read:ANNEX:OFFSET,LENGTH'
|
`qXfer:features:read:ANNEX:OFFSET,LENGTH'
|
Access the "target description". *Note Target
|
Access the "target description". *Note Target
|
Descriptions::. The annex specifies which XML document to
|
Descriptions::. The annex specifies which XML document to
|
access. The main description is always loaded from the
|
access. The main description is always loaded from the
|
`target.xml' annex.
|
`target.xml' annex.
|
|
|
This packet is not probed by default; the remote stub must
|
This packet is not probed by default; the remote stub must
|
request it, by supplying an appropriate `qSupported' response
|
request it, by supplying an appropriate `qSupported' response
|
(*note qSupported::).
|
(*note qSupported::).
|
|
|
`qXfer:libraries:read:ANNEX:OFFSET,LENGTH'
|
`qXfer:libraries:read:ANNEX:OFFSET,LENGTH'
|
Access the target's list of loaded libraries. *Note Library
|
Access the target's list of loaded libraries. *Note Library
|
List Format::. The annex part of the generic `qXfer' packet
|
List Format::. The annex part of the generic `qXfer' packet
|
must be empty (*note qXfer read::).
|
must be empty (*note qXfer read::).
|
|
|
Targets which maintain a list of libraries in the program's
|
Targets which maintain a list of libraries in the program's
|
memory do not need to implement this packet; it is designed
|
memory do not need to implement this packet; it is designed
|
for platforms where the operating system manages the list of
|
for platforms where the operating system manages the list of
|
loaded libraries.
|
loaded libraries.
|
|
|
This packet is not probed by default; the remote stub must
|
This packet is not probed by default; the remote stub must
|
request it, by supplying an appropriate `qSupported' response
|
request it, by supplying an appropriate `qSupported' response
|
(*note qSupported::).
|
(*note qSupported::).
|
|
|
`qXfer:memory-map:read::OFFSET,LENGTH'
|
`qXfer:memory-map:read::OFFSET,LENGTH'
|
Access the target's "memory-map". *Note Memory Map Format::.
|
Access the target's "memory-map". *Note Memory Map Format::.
|
The annex part of the generic `qXfer' packet must be empty
|
The annex part of the generic `qXfer' packet must be empty
|
(*note qXfer read::).
|
(*note qXfer read::).
|
|
|
This packet is not probed by default; the remote stub must
|
This packet is not probed by default; the remote stub must
|
request it, by supplying an appropriate `qSupported' response
|
request it, by supplying an appropriate `qSupported' response
|
(*note qSupported::).
|
(*note qSupported::).
|
|
|
`qXfer:spu:read:ANNEX:OFFSET,LENGTH'
|
`qXfer:spu:read:ANNEX:OFFSET,LENGTH'
|
Read contents of an `spufs' file on the target system. The
|
Read contents of an `spufs' file on the target system. The
|
annex specifies which file to read; it must be of the form
|
annex specifies which file to read; it must be of the form
|
`ID/NAME', where ID specifies an SPU context ID in the target
|
`ID/NAME', where ID specifies an SPU context ID in the target
|
process, and NAME identifes the `spufs' file in that context
|
process, and NAME identifes the `spufs' file in that context
|
to be accessed.
|
to be accessed.
|
|
|
This packet is not probed by default; the remote stub must
|
This packet is not probed by default; the remote stub must
|
request it, by supplying an appropriate `qSupported' response
|
request it, by supplying an appropriate `qSupported' response
|
(*note qSupported::).
|
(*note qSupported::).
|
|
|
Reply:
|
Reply:
|
`m DATA'
|
`m DATA'
|
Data DATA (*note Binary Data::) has been read from the
|
Data DATA (*note Binary Data::) has been read from the
|
target. There may be more data at a higher address (although
|
target. There may be more data at a higher address (although
|
it is permitted to return `m' even for the last valid block
|
it is permitted to return `m' even for the last valid block
|
of data, as long as at least one byte of data was read).
|
of data, as long as at least one byte of data was read).
|
DATA may have fewer bytes than the LENGTH in the request.
|
DATA may have fewer bytes than the LENGTH in the request.
|
|
|
`l DATA'
|
`l DATA'
|
Data DATA (*note Binary Data::) has been read from the target.
|
Data DATA (*note Binary Data::) has been read from the target.
|
There is no more data to be read. DATA may have fewer bytes
|
There is no more data to be read. DATA may have fewer bytes
|
than the LENGTH in the request.
|
than the LENGTH in the request.
|
|
|
`l'
|
`l'
|
The OFFSET in the request is at the end of the data. There
|
The OFFSET in the request is at the end of the data. There
|
is no more data to be read.
|
is no more data to be read.
|
|
|
`E00'
|
`E00'
|
The request was malformed, or ANNEX was invalid.
|
The request was malformed, or ANNEX was invalid.
|
|
|
`E NN'
|
`E NN'
|
The offset was invalid, or there was an error encountered
|
The offset was invalid, or there was an error encountered
|
reading the data. NN is a hex-encoded `errno' value.
|
reading the data. NN is a hex-encoded `errno' value.
|
|
|
`'
|
`'
|
An empty reply indicates the OBJECT string was not recognized
|
An empty reply indicates the OBJECT string was not recognized
|
by the stub, or that the object does not support reading.
|
by the stub, or that the object does not support reading.
|
|
|
`qXfer:OBJECT:write:ANNEX:OFFSET:DATA...'
|
`qXfer:OBJECT:write:ANNEX:OFFSET:DATA...'
|
Write uninterpreted bytes into the target's special data area
|
Write uninterpreted bytes into the target's special data area
|
identified by the keyword OBJECT, starting at OFFSET bytes into
|
identified by the keyword OBJECT, starting at OFFSET bytes into
|
the data. DATA... is the binary-encoded data (*note Binary
|
the data. DATA... is the binary-encoded data (*note Binary
|
Data::) to be written. The content and encoding of ANNEX is
|
Data::) to be written. The content and encoding of ANNEX is
|
specific to OBJECT; it can supply additional details about what
|
specific to OBJECT; it can supply additional details about what
|
data to access.
|
data to access.
|
|
|
Here are the specific requests of this form defined so far. All
|
Here are the specific requests of this form defined so far. All
|
`qXfer:OBJECT:write:...' requests use the same reply formats,
|
`qXfer:OBJECT:write:...' requests use the same reply formats,
|
listed below.
|
listed below.
|
|
|
`qXfer:SPU:write:ANNEX:OFFSET:DATA...'
|
`qXfer:SPU:write:ANNEX:OFFSET:DATA...'
|
Write DATA to an `spufs' file on the target system. The
|
Write DATA to an `spufs' file on the target system. The
|
annex specifies which file to write; it must be of the form
|
annex specifies which file to write; it must be of the form
|
`ID/NAME', where ID specifies an SPU context ID in the target
|
`ID/NAME', where ID specifies an SPU context ID in the target
|
process, and NAME identifes the `spufs' file in that context
|
process, and NAME identifes the `spufs' file in that context
|
to be accessed.
|
to be accessed.
|
|
|
This packet is not probed by default; the remote stub must
|
This packet is not probed by default; the remote stub must
|
request it, by supplying an appropriate `qSupported' response
|
request it, by supplying an appropriate `qSupported' response
|
(*note qSupported::).
|
(*note qSupported::).
|
|
|
Reply:
|
Reply:
|
`NN'
|
`NN'
|
NN (hex encoded) is the number of bytes written. This may be
|
NN (hex encoded) is the number of bytes written. This may be
|
fewer bytes than supplied in the request.
|
fewer bytes than supplied in the request.
|
|
|
`E00'
|
`E00'
|
The request was malformed, or ANNEX was invalid.
|
The request was malformed, or ANNEX was invalid.
|
|
|
`E NN'
|
`E NN'
|
The offset was invalid, or there was an error encountered
|
The offset was invalid, or there was an error encountered
|
writing the data. NN is a hex-encoded `errno' value.
|
writing the data. NN is a hex-encoded `errno' value.
|
|
|
`'
|
`'
|
An empty reply indicates the OBJECT string was not recognized
|
An empty reply indicates the OBJECT string was not recognized
|
by the stub, or that the object does not support writing.
|
by the stub, or that the object does not support writing.
|
|
|
`qXfer:OBJECT:OPERATION:...'
|
`qXfer:OBJECT:OPERATION:...'
|
Requests of this form may be added in the future. When a stub does
|
Requests of this form may be added in the future. When a stub does
|
not recognize the OBJECT keyword, or its support for OBJECT does
|
not recognize the OBJECT keyword, or its support for OBJECT does
|
not recognize the OPERATION keyword, the stub must respond with an
|
not recognize the OPERATION keyword, the stub must respond with an
|
empty packet.
|
empty packet.
|
|
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) The `qP' and `qL' packets predate these conventions, and have
|
(1) The `qP' and `qL' packets predate these conventions, and have
|
arguments without any terminator for the packet name; we suspect they
|
arguments without any terminator for the packet name; we suspect they
|
are in widespread use in places that are difficult to upgrade. The
|
are in widespread use in places that are difficult to upgrade. The
|
`qC' packet has no arguments, but some existing stubs (e.g. RedBoot)
|
`qC' packet has no arguments, but some existing stubs (e.g. RedBoot)
|
are known to not check for the end of the packet.
|
are known to not check for the end of the packet.
|
|
|
|
|
File: gdb.info, Node: Register Packet Format, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol
|
File: gdb.info, Node: Register Packet Format, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol
|
|
|
D.5 Register Packet Format
|
D.5 Register Packet Format
|
==========================
|
==========================
|
|
|
The following `g'/`G' packets have previously been defined. In the
|
The following `g'/`G' packets have previously been defined. In the
|
below, some thirty-two bit registers are transferred as sixty-four
|
below, some thirty-two bit registers are transferred as sixty-four
|
bits. Those registers should be zero/sign extended (which?) to fill
|
bits. Those registers should be zero/sign extended (which?) to fill
|
the space allocated. Register bytes are transferred in target byte
|
the space allocated. Register bytes are transferred in target byte
|
order. The two nibbles within a register byte are transferred
|
order. The two nibbles within a register byte are transferred
|
most-significant - least-significant.
|
most-significant - least-significant.
|
|
|
MIPS32
|
MIPS32
|
All registers are transferred as thirty-two bit quantities in the
|
All registers are transferred as thirty-two bit quantities in the
|
order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32
|
order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32
|
floating-point registers; fsr; fir; fp.
|
floating-point registers; fsr; fir; fp.
|
|
|
MIPS64
|
MIPS64
|
All registers are transferred as sixty-four bit quantities
|
All registers are transferred as sixty-four bit quantities
|
(including thirty-two bit registers such as `sr'). The ordering
|
(including thirty-two bit registers such as `sr'). The ordering
|
is the same as `MIPS32'.
|
is the same as `MIPS32'.
|
|
|
|
|
|
|
File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Register Packet Format, Up: Remote Protocol
|
File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Register Packet Format, Up: Remote Protocol
|
|
|
D.6 Tracepoint Packets
|
D.6 Tracepoint Packets
|
======================
|
======================
|
|
|
Here we describe the packets GDB uses to implement tracepoints (*note
|
Here we describe the packets GDB uses to implement tracepoints (*note
|
Tracepoints::).
|
Tracepoints::).
|
|
|
`QTDP:N:ADDR:ENA:STEP:PASS[-]'
|
`QTDP:N:ADDR:ENA:STEP:PASS[-]'
|
Create a new tracepoint, number N, at ADDR. If ENA is `E', then
|
Create a new tracepoint, number N, at ADDR. If ENA is `E', then
|
the tracepoint is enabled; if it is `D', then the tracepoint is
|
the tracepoint is enabled; if it is `D', then the tracepoint is
|
disabled. STEP is the tracepoint's step count, and PASS is its
|
disabled. STEP is the tracepoint's step count, and PASS is its
|
pass count. If the trailing `-' is present, further `QTDP'
|
pass count. If the trailing `-' is present, further `QTDP'
|
packets will follow to specify this tracepoint's actions.
|
packets will follow to specify this tracepoint's actions.
|
|
|
Replies:
|
Replies:
|
`OK'
|
`OK'
|
The packet was understood and carried out.
|
The packet was understood and carried out.
|
|
|
`'
|
`'
|
The packet was not recognized.
|
The packet was not recognized.
|
|
|
`QTDP:-N:ADDR:[S]ACTION...[-]'
|
`QTDP:-N:ADDR:[S]ACTION...[-]'
|
Define actions to be taken when a tracepoint is hit. N and ADDR
|
Define actions to be taken when a tracepoint is hit. N and ADDR
|
must be the same as in the initial `QTDP' packet for this
|
must be the same as in the initial `QTDP' packet for this
|
tracepoint. This packet may only be sent immediately after
|
tracepoint. This packet may only be sent immediately after
|
another `QTDP' packet that ended with a `-'. If the trailing `-'
|
another `QTDP' packet that ended with a `-'. If the trailing `-'
|
is present, further `QTDP' packets will follow, specifying more
|
is present, further `QTDP' packets will follow, specifying more
|
actions for this tracepoint.
|
actions for this tracepoint.
|
|
|
In the series of action packets for a given tracepoint, at most one
|
In the series of action packets for a given tracepoint, at most one
|
can have an `S' before its first ACTION. If such a packet is
|
can have an `S' before its first ACTION. If such a packet is
|
sent, it and the following packets define "while-stepping"
|
sent, it and the following packets define "while-stepping"
|
actions. Any prior packets define ordinary actions -- that is,
|
actions. Any prior packets define ordinary actions -- that is,
|
those taken when the tracepoint is first hit. If no action packet
|
those taken when the tracepoint is first hit. If no action packet
|
has an `S', then all the packets in the series specify ordinary
|
has an `S', then all the packets in the series specify ordinary
|
tracepoint actions.
|
tracepoint actions.
|
|
|
The `ACTION...' portion of the packet is a series of actions,
|
The `ACTION...' portion of the packet is a series of actions,
|
concatenated without separators. Each action has one of the
|
concatenated without separators. Each action has one of the
|
following forms:
|
following forms:
|
|
|
`R MASK'
|
`R MASK'
|
Collect the registers whose bits are set in MASK. MASK is a
|
Collect the registers whose bits are set in MASK. MASK is a
|
hexadecimal number whose I'th bit is set if register number I
|
hexadecimal number whose I'th bit is set if register number I
|
should be collected. (The least significant bit is numbered
|
should be collected. (The least significant bit is numbered
|
zero.) Note that MASK may be any number of digits long; it
|
zero.) Note that MASK may be any number of digits long; it
|
may not fit in a 32-bit word.
|
may not fit in a 32-bit word.
|
|
|
`M BASEREG,OFFSET,LEN'
|
`M BASEREG,OFFSET,LEN'
|
Collect LEN bytes of memory starting at the address in
|
Collect LEN bytes of memory starting at the address in
|
register number BASEREG, plus OFFSET. If BASEREG is `-1',
|
register number BASEREG, plus OFFSET. If BASEREG is `-1',
|
then the range has a fixed address: OFFSET is the address of
|
then the range has a fixed address: OFFSET is the address of
|
the lowest byte to collect. The BASEREG, OFFSET, and LEN
|
the lowest byte to collect. The BASEREG, OFFSET, and LEN
|
parameters are all unsigned hexadecimal values (the `-1'
|
parameters are all unsigned hexadecimal values (the `-1'
|
value for BASEREG is a special case).
|
value for BASEREG is a special case).
|
|
|
`X LEN,EXPR'
|
`X LEN,EXPR'
|
Evaluate EXPR, whose length is LEN, and collect memory as it
|
Evaluate EXPR, whose length is LEN, and collect memory as it
|
directs. EXPR is an agent expression, as described in *Note
|
directs. EXPR is an agent expression, as described in *Note
|
Agent Expressions::. Each byte of the expression is encoded
|
Agent Expressions::. Each byte of the expression is encoded
|
as a two-digit hex number in the packet; LEN is the number of
|
as a two-digit hex number in the packet; LEN is the number of
|
bytes in the expression (and thus one-half the number of hex
|
bytes in the expression (and thus one-half the number of hex
|
digits in the packet).
|
digits in the packet).
|
|
|
|
|
Any number of actions may be packed together in a single `QTDP'
|
Any number of actions may be packed together in a single `QTDP'
|
packet, as long as the packet does not exceed the maximum packet
|
packet, as long as the packet does not exceed the maximum packet
|
length (400 bytes, for many stubs). There may be only one `R'
|
length (400 bytes, for many stubs). There may be only one `R'
|
action per tracepoint, and it must precede any `M' or `X' actions.
|
action per tracepoint, and it must precede any `M' or `X' actions.
|
Any registers referred to by `M' and `X' actions must be
|
Any registers referred to by `M' and `X' actions must be
|
collected by a preceding `R' action. (The "while-stepping"
|
collected by a preceding `R' action. (The "while-stepping"
|
actions are treated as if they were attached to a separate
|
actions are treated as if they were attached to a separate
|
tracepoint, as far as these restrictions are concerned.)
|
tracepoint, as far as these restrictions are concerned.)
|
|
|
Replies:
|
Replies:
|
`OK'
|
`OK'
|
The packet was understood and carried out.
|
The packet was understood and carried out.
|
|
|
`'
|
`'
|
The packet was not recognized.
|
The packet was not recognized.
|
|
|
`QTFrame:N'
|
`QTFrame:N'
|
Select the N'th tracepoint frame from the buffer, and use the
|
Select the N'th tracepoint frame from the buffer, and use the
|
register and memory contents recorded there to answer subsequent
|
register and memory contents recorded there to answer subsequent
|
request packets from GDB.
|
request packets from GDB.
|
|
|
A successful reply from the stub indicates that the stub has found
|
A successful reply from the stub indicates that the stub has found
|
the requested frame. The response is a series of parts,
|
the requested frame. The response is a series of parts,
|
concatenated without separators, describing the frame we selected.
|
concatenated without separators, describing the frame we selected.
|
Each part has one of the following forms:
|
Each part has one of the following forms:
|
|
|
`F F'
|
`F F'
|
The selected frame is number N in the trace frame buffer; F
|
The selected frame is number N in the trace frame buffer; F
|
is a hexadecimal number. If F is `-1', then there was no
|
is a hexadecimal number. If F is `-1', then there was no
|
frame matching the criteria in the request packet.
|
frame matching the criteria in the request packet.
|
|
|
`T T'
|
`T T'
|
The selected trace frame records a hit of tracepoint number T;
|
The selected trace frame records a hit of tracepoint number T;
|
T is a hexadecimal number.
|
T is a hexadecimal number.
|
|
|
|
|
`QTFrame:pc:ADDR'
|
`QTFrame:pc:ADDR'
|
Like `QTFrame:N', but select the first tracepoint frame after the
|
Like `QTFrame:N', but select the first tracepoint frame after the
|
currently selected frame whose PC is ADDR; ADDR is a hexadecimal
|
currently selected frame whose PC is ADDR; ADDR is a hexadecimal
|
number.
|
number.
|
|
|
`QTFrame:tdp:T'
|
`QTFrame:tdp:T'
|
Like `QTFrame:N', but select the first tracepoint frame after the
|
Like `QTFrame:N', but select the first tracepoint frame after the
|
currently selected frame that is a hit of tracepoint T; T is a
|
currently selected frame that is a hit of tracepoint T; T is a
|
hexadecimal number.
|
hexadecimal number.
|
|
|
`QTFrame:range:START:END'
|
`QTFrame:range:START:END'
|
Like `QTFrame:N', but select the first tracepoint frame after the
|
Like `QTFrame:N', but select the first tracepoint frame after the
|
currently selected frame whose PC is between START (inclusive) and
|
currently selected frame whose PC is between START (inclusive) and
|
END (exclusive); START and END are hexadecimal numbers.
|
END (exclusive); START and END are hexadecimal numbers.
|
|
|
`QTFrame:outside:START:END'
|
`QTFrame:outside:START:END'
|
Like `QTFrame:range:START:END', but select the first frame
|
Like `QTFrame:range:START:END', but select the first frame
|
_outside_ the given range of addresses.
|
_outside_ the given range of addresses.
|
|
|
`QTStart'
|
`QTStart'
|
Begin the tracepoint experiment. Begin collecting data from
|
Begin the tracepoint experiment. Begin collecting data from
|
tracepoint hits in the trace frame buffer.
|
tracepoint hits in the trace frame buffer.
|
|
|
`QTStop'
|
`QTStop'
|
End the tracepoint experiment. Stop collecting trace frames.
|
End the tracepoint experiment. Stop collecting trace frames.
|
|
|
`QTinit'
|
`QTinit'
|
Clear the table of tracepoints, and empty the trace frame buffer.
|
Clear the table of tracepoints, and empty the trace frame buffer.
|
|
|
`QTro:START1,END1:START2,END2:...'
|
`QTro:START1,END1:START2,END2:...'
|
Establish the given ranges of memory as "transparent". The stub
|
Establish the given ranges of memory as "transparent". The stub
|
will answer requests for these ranges from memory's current
|
will answer requests for these ranges from memory's current
|
contents, if they were not collected as part of the tracepoint hit.
|
contents, if they were not collected as part of the tracepoint hit.
|
|
|
GDB uses this to mark read-only regions of memory, like those
|
GDB uses this to mark read-only regions of memory, like those
|
containing program code. Since these areas never change, they
|
containing program code. Since these areas never change, they
|
should still have the same contents they did when the tracepoint
|
should still have the same contents they did when the tracepoint
|
was hit, so there's no reason for the stub to refuse to provide
|
was hit, so there's no reason for the stub to refuse to provide
|
their contents.
|
their contents.
|
|
|
`qTStatus'
|
`qTStatus'
|
Ask the stub if there is a trace experiment running right now.
|
Ask the stub if there is a trace experiment running right now.
|
|
|
Replies:
|
Replies:
|
`T0'
|
`T0'
|
There is no trace experiment running.
|
There is no trace experiment running.
|
|
|
`T1'
|
`T1'
|
There is a trace experiment running.
|
There is a trace experiment running.
|
|
|
|
|
|
|
File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol
|
File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol
|
|
|
D.7 Host I/O Packets
|
D.7 Host I/O Packets
|
====================
|
====================
|
|
|
The "Host I/O" packets allow GDB to perform I/O operations on the far
|
The "Host I/O" packets allow GDB to perform I/O operations on the far
|
side of a remote link. For example, Host I/O is used to upload and
|
side of a remote link. For example, Host I/O is used to upload and
|
download files to a remote target with its own filesystem. Host I/O
|
download files to a remote target with its own filesystem. Host I/O
|
uses the same constant values and data structure layout as the
|
uses the same constant values and data structure layout as the
|
target-initiated File-I/O protocol. However, the Host I/O packets are
|
target-initiated File-I/O protocol. However, the Host I/O packets are
|
structured differently. The target-initiated protocol relies on target
|
structured differently. The target-initiated protocol relies on target
|
memory to store parameters and buffers. Host I/O requests are
|
memory to store parameters and buffers. Host I/O requests are
|
initiated by GDB, and the target's memory is not involved. *Note
|
initiated by GDB, and the target's memory is not involved. *Note
|
File-I/O Remote Protocol Extension::, for more details on the
|
File-I/O Remote Protocol Extension::, for more details on the
|
target-initiated protocol.
|
target-initiated protocol.
|
|
|
The Host I/O request packets all encode a single operation along with
|
The Host I/O request packets all encode a single operation along with
|
its arguments. They have this format:
|
its arguments. They have this format:
|
|
|
`vFile:OPERATION: PARAMETER...'
|
`vFile:OPERATION: PARAMETER...'
|
OPERATION is the name of the particular request; the target should
|
OPERATION is the name of the particular request; the target should
|
compare the entire packet name up to the second colon when checking
|
compare the entire packet name up to the second colon when checking
|
for a supported operation. The format of PARAMETER depends on the
|
for a supported operation. The format of PARAMETER depends on the
|
operation. Numbers are always passed in hexadecimal. Negative
|
operation. Numbers are always passed in hexadecimal. Negative
|
numbers have an explicit minus sign (i.e. two's complement is not
|
numbers have an explicit minus sign (i.e. two's complement is not
|
used). Strings (e.g. filenames) are encoded as a series of
|
used). Strings (e.g. filenames) are encoded as a series of
|
hexadecimal bytes. The last argument to a system call may be a
|
hexadecimal bytes. The last argument to a system call may be a
|
buffer of escaped binary data (*note Binary Data::).
|
buffer of escaped binary data (*note Binary Data::).
|
|
|
|
|
The valid responses to Host I/O packets are:
|
The valid responses to Host I/O packets are:
|
|
|
`F RESULT [, ERRNO] [; ATTACHMENT]'
|
`F RESULT [, ERRNO] [; ATTACHMENT]'
|
RESULT is the integer value returned by this operation, usually
|
RESULT is the integer value returned by this operation, usually
|
non-negative for success and -1 for errors. If an error has
|
non-negative for success and -1 for errors. If an error has
|
occured, ERRNO will be included in the result. ERRNO will have a
|
occured, ERRNO will be included in the result. ERRNO will have a
|
value defined by the File-I/O protocol (*note Errno Values::). For
|
value defined by the File-I/O protocol (*note Errno Values::). For
|
operations which return data, ATTACHMENT supplies the data as a
|
operations which return data, ATTACHMENT supplies the data as a
|
binary buffer. Binary buffers in response packets are escaped in
|
binary buffer. Binary buffers in response packets are escaped in
|
the normal way (*note Binary Data::). See the individual packet
|
the normal way (*note Binary Data::). See the individual packet
|
documentation for the interpretation of RESULT and ATTACHMENT.
|
documentation for the interpretation of RESULT and ATTACHMENT.
|
|
|
`'
|
`'
|
An empty response indicates that this operation is not recognized.
|
An empty response indicates that this operation is not recognized.
|
|
|
|
|
These are the supported Host I/O operations:
|
These are the supported Host I/O operations:
|
|
|
`vFile:open: PATHNAME, FLAGS, MODE'
|
`vFile:open: PATHNAME, FLAGS, MODE'
|
Open a file at PATHNAME and return a file descriptor for it, or
|
Open a file at PATHNAME and return a file descriptor for it, or
|
return -1 if an error occurs. PATHNAME is a string, FLAGS is an
|
return -1 if an error occurs. PATHNAME is a string, FLAGS is an
|
integer indicating a mask of open flags (*note Open Flags::), and
|
integer indicating a mask of open flags (*note Open Flags::), and
|
MODE is an integer indicating a mask of mode bits to use if the
|
MODE is an integer indicating a mask of mode bits to use if the
|
file is created (*note mode_t Values::). *Note open::, for
|
file is created (*note mode_t Values::). *Note open::, for
|
details of the open flags and mode values.
|
details of the open flags and mode values.
|
|
|
`vFile:close: FD'
|
`vFile:close: FD'
|
Close the open file corresponding to FD and return 0, or -1 if an
|
Close the open file corresponding to FD and return 0, or -1 if an
|
error occurs.
|
error occurs.
|
|
|
`vFile:pread: FD, COUNT, OFFSET'
|
`vFile:pread: FD, COUNT, OFFSET'
|
Read data from the open file corresponding to FD. Up to COUNT
|
Read data from the open file corresponding to FD. Up to COUNT
|
bytes will be read from the file, starting at OFFSET relative to
|
bytes will be read from the file, starting at OFFSET relative to
|
the start of the file. The target may read fewer bytes; common
|
the start of the file. The target may read fewer bytes; common
|
reasons include packet size limits and an end-of-file condition.
|
reasons include packet size limits and an end-of-file condition.
|
The number of bytes read is returned. Zero should only be
|
The number of bytes read is returned. Zero should only be
|
returned for a successful read at the end of the file, or if COUNT
|
returned for a successful read at the end of the file, or if COUNT
|
was zero.
|
was zero.
|
|
|
The data read should be returned as a binary attachment on success.
|
The data read should be returned as a binary attachment on success.
|
If zero bytes were read, the response should include an empty
|
If zero bytes were read, the response should include an empty
|
binary attachment (i.e. a trailing semicolon). The return value
|
binary attachment (i.e. a trailing semicolon). The return value
|
is the number of target bytes read; the binary attachment may be
|
is the number of target bytes read; the binary attachment may be
|
longer if some characters were escaped.
|
longer if some characters were escaped.
|
|
|
`vFile:pwrite: FD, OFFSET, DATA'
|
`vFile:pwrite: FD, OFFSET, DATA'
|
Write DATA (a binary buffer) to the open file corresponding to FD.
|
Write DATA (a binary buffer) to the open file corresponding to FD.
|
Start the write at OFFSET from the start of the file. Unlike
|
Start the write at OFFSET from the start of the file. Unlike
|
many `write' system calls, there is no separate COUNT argument;
|
many `write' system calls, there is no separate COUNT argument;
|
the length of DATA in the packet is used. `vFile:write' returns
|
the length of DATA in the packet is used. `vFile:write' returns
|
the number of bytes written, which may be shorter than the length
|
the number of bytes written, which may be shorter than the length
|
of DATA, or -1 if an error occurred.
|
of DATA, or -1 if an error occurred.
|
|
|
`vFile:unlink: PATHNAME'
|
`vFile:unlink: PATHNAME'
|
Delete the file at PATHNAME on the target. Return 0, or -1 if an
|
Delete the file at PATHNAME on the target. Return 0, or -1 if an
|
error occurs. PATHNAME is a string.
|
error occurs. PATHNAME is a string.
|
|
|
|
|
|
|
File: gdb.info, Node: Interrupts, Next: Examples, Prev: Host I/O Packets, Up: Remote Protocol
|
File: gdb.info, Node: Interrupts, Next: Examples, Prev: Host I/O Packets, Up: Remote Protocol
|
|
|
D.8 Interrupts
|
D.8 Interrupts
|
==============
|
==============
|
|
|
When a program on the remote target is running, GDB may attempt to
|
When a program on the remote target is running, GDB may attempt to
|
interrupt it by sending a `Ctrl-C' or a `BREAK', control of which is
|
interrupt it by sending a `Ctrl-C' or a `BREAK', control of which is
|
specified via GDB's `remotebreak' setting (*note set remotebreak::).
|
specified via GDB's `remotebreak' setting (*note set remotebreak::).
|
|
|
The precise meaning of `BREAK' is defined by the transport mechanism
|
The precise meaning of `BREAK' is defined by the transport mechanism
|
and may, in fact, be undefined. GDB does not currently define a
|
and may, in fact, be undefined. GDB does not currently define a
|
`BREAK' mechanism for any of the network interfaces.
|
`BREAK' mechanism for any of the network interfaces.
|
|
|
`Ctrl-C', on the other hand, is defined and implemented for all
|
`Ctrl-C', on the other hand, is defined and implemented for all
|
transport mechanisms. It is represented by sending the single byte
|
transport mechanisms. It is represented by sending the single byte
|
`0x03' without any of the usual packet overhead described in the
|
`0x03' without any of the usual packet overhead described in the
|
Overview section (*note Overview::). When a `0x03' byte is transmitted
|
Overview section (*note Overview::). When a `0x03' byte is transmitted
|
as part of a packet, it is considered to be packet data and does _not_
|
as part of a packet, it is considered to be packet data and does _not_
|
represent an interrupt. E.g., an `X' packet (*note X packet::), used
|
represent an interrupt. E.g., an `X' packet (*note X packet::), used
|
for binary downloads, may include an unescaped `0x03' as part of its
|
for binary downloads, may include an unescaped `0x03' as part of its
|
packet.
|
packet.
|
|
|
Stubs are not required to recognize these interrupt mechanisms and
|
Stubs are not required to recognize these interrupt mechanisms and
|
the precise meaning associated with receipt of the interrupt is
|
the precise meaning associated with receipt of the interrupt is
|
implementation defined. If the stub is successful at interrupting the
|
implementation defined. If the stub is successful at interrupting the
|
running program, it is expected that it will send one of the Stop Reply
|
running program, it is expected that it will send one of the Stop Reply
|
Packets (*note Stop Reply Packets::) to GDB as a result of successfully
|
Packets (*note Stop Reply Packets::) to GDB as a result of successfully
|
stopping the program. Interrupts received while the program is stopped
|
stopping the program. Interrupts received while the program is stopped
|
will be discarded.
|
will be discarded.
|
|
|
|
|
File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Interrupts, Up: Remote Protocol
|
File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Interrupts, Up: Remote Protocol
|
|
|
D.9 Examples
|
D.9 Examples
|
============
|
============
|
|
|
Example sequence of a target being re-started. Notice how the restart
|
Example sequence of a target being re-started. Notice how the restart
|
does not get any direct output:
|
does not get any direct output:
|
|
|
-> `R00'
|
-> `R00'
|
<- `+'
|
<- `+'
|
_target restarts_
|
_target restarts_
|
-> `?'
|
-> `?'
|
<- `+'
|
<- `+'
|
<- `T001:1234123412341234'
|
<- `T001:1234123412341234'
|
-> `+'
|
-> `+'
|
|
|
Example sequence of a target being stepped by a single instruction:
|
Example sequence of a target being stepped by a single instruction:
|
|
|
-> `G1445...'
|
-> `G1445...'
|
<- `+'
|
<- `+'
|
-> `s'
|
-> `s'
|
<- `+'
|
<- `+'
|
_time passes_
|
_time passes_
|
<- `T001:1234123412341234'
|
<- `T001:1234123412341234'
|
-> `+'
|
-> `+'
|
-> `g'
|
-> `g'
|
<- `+'
|
<- `+'
|
<- `1455...'
|
<- `1455...'
|
-> `+'
|
-> `+'
|
|
|
|
|
File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol
|
File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol
|
|
|
D.10 File-I/O Remote Protocol Extension
|
D.10 File-I/O Remote Protocol Extension
|
=======================================
|
=======================================
|
|
|
* Menu:
|
* Menu:
|
|
|
* File-I/O Overview::
|
* File-I/O Overview::
|
* Protocol Basics::
|
* Protocol Basics::
|
* The F Request Packet::
|
* The F Request Packet::
|
* The F Reply Packet::
|
* The F Reply Packet::
|
* The Ctrl-C Message::
|
* The Ctrl-C Message::
|
* Console I/O::
|
* Console I/O::
|
* List of Supported Calls::
|
* List of Supported Calls::
|
* Protocol-specific Representation of Datatypes::
|
* Protocol-specific Representation of Datatypes::
|
* Constants::
|
* Constants::
|
* File-I/O Examples::
|
* File-I/O Examples::
|
|
|
|
|
File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension
|
File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension
|
|
|
D.10.1 File-I/O Overview
|
D.10.1 File-I/O Overview
|
------------------------
|
------------------------
|
|
|
The "File I/O remote protocol extension" (short: File-I/O) allows the
|
The "File I/O remote protocol extension" (short: File-I/O) allows the
|
target to use the host's file system and console I/O to perform various
|
target to use the host's file system and console I/O to perform various
|
system calls. System calls on the target system are translated into a
|
system calls. System calls on the target system are translated into a
|
remote protocol packet to the host system, which then performs the
|
remote protocol packet to the host system, which then performs the
|
needed actions and returns a response packet to the target system.
|
needed actions and returns a response packet to the target system.
|
This simulates file system operations even on targets that lack file
|
This simulates file system operations even on targets that lack file
|
systems.
|
systems.
|
|
|
The protocol is defined to be independent of both the host and
|
The protocol is defined to be independent of both the host and
|
target systems. It uses its own internal representation of datatypes
|
target systems. It uses its own internal representation of datatypes
|
and values. Both GDB and the target's GDB stub are responsible for
|
and values. Both GDB and the target's GDB stub are responsible for
|
translating the system-dependent value representations into the internal
|
translating the system-dependent value representations into the internal
|
protocol representations when data is transmitted.
|
protocol representations when data is transmitted.
|
|
|
The communication is synchronous. A system call is possible only
|
The communication is synchronous. A system call is possible only
|
when GDB is waiting for a response from the `C', `c', `S' or `s'
|
when GDB is waiting for a response from the `C', `c', `S' or `s'
|
packets. While GDB handles the request for a system call, the target
|
packets. While GDB handles the request for a system call, the target
|
is stopped to allow deterministic access to the target's memory.
|
is stopped to allow deterministic access to the target's memory.
|
Therefore File-I/O is not interruptible by target signals. On the
|
Therefore File-I/O is not interruptible by target signals. On the
|
other hand, it is possible to interrupt File-I/O by a user interrupt
|
other hand, it is possible to interrupt File-I/O by a user interrupt
|
(`Ctrl-C') within GDB.
|
(`Ctrl-C') within GDB.
|
|
|
The target's request to perform a host system call does not finish
|
The target's request to perform a host system call does not finish
|
the latest `C', `c', `S' or `s' action. That means, after finishing
|
the latest `C', `c', `S' or `s' action. That means, after finishing
|
the system call, the target returns to continuing the previous activity
|
the system call, the target returns to continuing the previous activity
|
(continue, step). No additional continue or step request from GDB is
|
(continue, step). No additional continue or step request from GDB is
|
required.
|
required.
|
|
|
(gdb) continue
|
(gdb) continue
|
<- target requests 'system call X'
|
<- target requests 'system call X'
|
target is stopped, GDB executes system call
|
target is stopped, GDB executes system call
|
-> GDB returns result
|
-> GDB returns result
|
... target continues, GDB returns to wait for the target
|
... target continues, GDB returns to wait for the target
|
<- target hits breakpoint and sends a Txx packet
|
<- target hits breakpoint and sends a Txx packet
|
|
|
The protocol only supports I/O on the console and to regular files on
|
The protocol only supports I/O on the console and to regular files on
|
the host file system. Character or block special devices, pipes, named
|
the host file system. Character or block special devices, pipes, named
|
pipes, sockets or any other communication method on the host system are
|
pipes, sockets or any other communication method on the host system are
|
not supported by this protocol.
|
not supported by this protocol.
|
|
|
|
|
File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension
|
File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension
|
|
|
D.10.2 Protocol Basics
|
D.10.2 Protocol Basics
|
----------------------
|
----------------------
|
|
|
The File-I/O protocol uses the `F' packet as the request as well as
|
The File-I/O protocol uses the `F' packet as the request as well as
|
reply packet. Since a File-I/O system call can only occur when GDB is
|
reply packet. Since a File-I/O system call can only occur when GDB is
|
waiting for a response from the continuing or stepping target, the
|
waiting for a response from the continuing or stepping target, the
|
File-I/O request is a reply that GDB has to expect as a result of a
|
File-I/O request is a reply that GDB has to expect as a result of a
|
previous `C', `c', `S' or `s' packet. This `F' packet contains all
|
previous `C', `c', `S' or `s' packet. This `F' packet contains all
|
information needed to allow GDB to call the appropriate host system
|
information needed to allow GDB to call the appropriate host system
|
call:
|
call:
|
|
|
* A unique identifier for the requested system call.
|
* A unique identifier for the requested system call.
|
|
|
* All parameters to the system call. Pointers are given as addresses
|
* All parameters to the system call. Pointers are given as addresses
|
in the target memory address space. Pointers to strings are given
|
in the target memory address space. Pointers to strings are given
|
as pointer/length pair. Numerical values are given as they are.
|
as pointer/length pair. Numerical values are given as they are.
|
Numerical control flags are given in a protocol-specific
|
Numerical control flags are given in a protocol-specific
|
representation.
|
representation.
|
|
|
|
|
At this point, GDB has to perform the following actions.
|
At this point, GDB has to perform the following actions.
|
|
|
* If the parameters include pointer values to data needed as input
|
* If the parameters include pointer values to data needed as input
|
to a system call, GDB requests this data from the target with a
|
to a system call, GDB requests this data from the target with a
|
standard `m' packet request. This additional communication has to
|
standard `m' packet request. This additional communication has to
|
be expected by the target implementation and is handled as any
|
be expected by the target implementation and is handled as any
|
other `m' packet.
|
other `m' packet.
|
|
|
* GDB translates all value from protocol representation to host
|
* GDB translates all value from protocol representation to host
|
representation as needed. Datatypes are coerced into the host
|
representation as needed. Datatypes are coerced into the host
|
types.
|
types.
|
|
|
* GDB calls the system call.
|
* GDB calls the system call.
|
|
|
* It then coerces datatypes back to protocol representation.
|
* It then coerces datatypes back to protocol representation.
|
|
|
* If the system call is expected to return data in buffer space
|
* If the system call is expected to return data in buffer space
|
specified by pointer parameters to the call, the data is
|
specified by pointer parameters to the call, the data is
|
transmitted to the target using a `M' or `X' packet. This packet
|
transmitted to the target using a `M' or `X' packet. This packet
|
has to be expected by the target implementation and is handled as
|
has to be expected by the target implementation and is handled as
|
any other `M' or `X' packet.
|
any other `M' or `X' packet.
|
|
|
|
|
Eventually GDB replies with another `F' packet which contains all
|
Eventually GDB replies with another `F' packet which contains all
|
necessary information for the target to continue. This at least
|
necessary information for the target to continue. This at least
|
contains
|
contains
|
|
|
* Return value.
|
* Return value.
|
|
|
* `errno', if has been changed by the system call.
|
* `errno', if has been changed by the system call.
|
|
|
* "Ctrl-C" flag.
|
* "Ctrl-C" flag.
|
|
|
|
|
After having done the needed type and value coercion, the target
|
After having done the needed type and value coercion, the target
|
continues the latest continue or step action.
|
continues the latest continue or step action.
|
|
|
|
|
File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension
|
File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension
|
|
|
D.10.3 The `F' Request Packet
|
D.10.3 The `F' Request Packet
|
-----------------------------
|
-----------------------------
|
|
|
The `F' request packet has the following format:
|
The `F' request packet has the following format:
|
|
|
`FCALL-ID,PARAMETER...'
|
`FCALL-ID,PARAMETER...'
|
CALL-ID is the identifier to indicate the host system call to be
|
CALL-ID is the identifier to indicate the host system call to be
|
called. This is just the name of the function.
|
called. This is just the name of the function.
|
|
|
PARAMETER... are the parameters to the system call. Parameters
|
PARAMETER... are the parameters to the system call. Parameters
|
are hexadecimal integer values, either the actual values in case
|
are hexadecimal integer values, either the actual values in case
|
of scalar datatypes, pointers to target buffer space in case of
|
of scalar datatypes, pointers to target buffer space in case of
|
compound datatypes and unspecified memory areas, or pointer/length
|
compound datatypes and unspecified memory areas, or pointer/length
|
pairs in case of string parameters. These are appended to the
|
pairs in case of string parameters. These are appended to the
|
CALL-ID as a comma-delimited list. All values are transmitted in
|
CALL-ID as a comma-delimited list. All values are transmitted in
|
ASCII string representation, pointer/length pairs separated by a
|
ASCII string representation, pointer/length pairs separated by a
|
slash.
|
slash.
|
|
|
|
|
|
|
File: gdb.info, Node: The F Reply Packet, Next: The Ctrl-C Message, Prev: The F Request Packet, Up: File-I/O Remote Protocol Extension
|
File: gdb.info, Node: The F Reply Packet, Next: The Ctrl-C Message, Prev: The F Request Packet, Up: File-I/O Remote Protocol Extension
|
|
|
D.10.4 The `F' Reply Packet
|
D.10.4 The `F' Reply Packet
|
---------------------------
|
---------------------------
|
|
|
The `F' reply packet has the following format:
|
The `F' reply packet has the following format:
|
|
|
`FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'
|
`FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'
|
RETCODE is the return code of the system call as hexadecimal value.
|
RETCODE is the return code of the system call as hexadecimal value.
|
|
|
ERRNO is the `errno' set by the call, in protocol-specific
|
ERRNO is the `errno' set by the call, in protocol-specific
|
representation. This parameter can be omitted if the call was
|
representation. This parameter can be omitted if the call was
|
successful.
|
successful.
|
|
|
CTRL-C FLAG is only sent if the user requested a break. In this
|
CTRL-C FLAG is only sent if the user requested a break. In this
|
case, ERRNO must be sent as well, even if the call was successful.
|
case, ERRNO must be sent as well, even if the call was successful.
|
The CTRL-C FLAG itself consists of the character `C':
|
The CTRL-C FLAG itself consists of the character `C':
|
|
|
F0,0,C
|
F0,0,C
|
|
|
or, if the call was interrupted before the host call has been
|
or, if the call was interrupted before the host call has been
|
performed:
|
performed:
|
|
|
F-1,4,C
|
F-1,4,C
|
|
|
assuming 4 is the protocol-specific representation of `EINTR'.
|
assuming 4 is the protocol-specific representation of `EINTR'.
|
|
|
|
|
|
|
File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension
|
File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension
|
|
|
D.10.5 The `Ctrl-C' Message
|
D.10.5 The `Ctrl-C' Message
|
---------------------------
|
---------------------------
|
|
|
If the `Ctrl-C' flag is set in the GDB reply packet (*note The F Reply
|
If the `Ctrl-C' flag is set in the GDB reply packet (*note The F Reply
|
Packet::), the target should behave as if it had gotten a break
|
Packet::), the target should behave as if it had gotten a break
|
message. The meaning for the target is "system call interrupted by
|
message. The meaning for the target is "system call interrupted by
|
`SIGINT'". Consequentially, the target should actually stop (as with a
|
`SIGINT'". Consequentially, the target should actually stop (as with a
|
break message) and return to GDB with a `T02' packet.
|
break message) and return to GDB with a `T02' packet.
|
|
|
It's important for the target to know in which state the system call
|
It's important for the target to know in which state the system call
|
was interrupted. There are two possible cases:
|
was interrupted. There are two possible cases:
|
|
|
* The system call hasn't been performed on the host yet.
|
* The system call hasn't been performed on the host yet.
|
|
|
* The system call on the host has been finished.
|
* The system call on the host has been finished.
|
|
|
|
|
These two states can be distinguished by the target by the value of
|
These two states can be distinguished by the target by the value of
|
the returned `errno'. If it's the protocol representation of `EINTR',
|
the returned `errno'. If it's the protocol representation of `EINTR',
|
the system call hasn't been performed. This is equivalent to the
|
the system call hasn't been performed. This is equivalent to the
|
`EINTR' handling on POSIX systems. In any other case, the target may
|
`EINTR' handling on POSIX systems. In any other case, the target may
|
presume that the system call has been finished -- successfully or not
|
presume that the system call has been finished -- successfully or not
|
-- and should behave as if the break message arrived right after the
|
-- and should behave as if the break message arrived right after the
|
system call.
|
system call.
|
|
|
GDB must behave reliably. If the system call has not been called
|
GDB must behave reliably. If the system call has not been called
|
yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno'
|
yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno'
|
in the packet. If the system call on the host has been finished before
|
in the packet. If the system call on the host has been finished before
|
the user requests a break, the full action must be finished by GDB.
|
the user requests a break, the full action must be finished by GDB.
|
This requires sending `M' or `X' packets as necessary. The `F' packet
|
This requires sending `M' or `X' packets as necessary. The `F' packet
|
may only be sent when either nothing has happened or the full action
|
may only be sent when either nothing has happened or the full action
|
has been completed.
|
has been completed.
|
|
|
|
|
File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension
|
File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension
|
|
|
D.10.6 Console I/O
|
D.10.6 Console I/O
|
------------------
|
------------------
|
|
|
By default and if not explicitly closed by the target system, the file
|
By default and if not explicitly closed by the target system, the file
|
descriptors 0, 1 and 2 are connected to the GDB console. Output on the
|
descriptors 0, 1 and 2 are connected to the GDB console. Output on the
|
GDB console is handled as any other file output operation (`write(1,
|
GDB console is handled as any other file output operation (`write(1,
|
...)' or `write(2, ...)'). Console input is handled by GDB so that
|
...)' or `write(2, ...)'). Console input is handled by GDB so that
|
after the target read request from file descriptor 0 all following
|
after the target read request from file descriptor 0 all following
|
typing is buffered until either one of the following conditions is met:
|
typing is buffered until either one of the following conditions is met:
|
|
|
* The user types `Ctrl-c'. The behaviour is as explained above, and
|
* The user types `Ctrl-c'. The behaviour is as explained above, and
|
the `read' system call is treated as finished.
|
the `read' system call is treated as finished.
|
|
|
* The user presses . This is treated as end of input with a
|
* The user presses . This is treated as end of input with a
|
trailing newline.
|
trailing newline.
|
|
|
* The user types `Ctrl-d'. This is treated as end of input. No
|
* The user types `Ctrl-d'. This is treated as end of input. No
|
trailing character (neither newline nor `Ctrl-D') is appended to
|
trailing character (neither newline nor `Ctrl-D') is appended to
|
the input.
|
the input.
|
|
|
|
|
If the user has typed more characters than fit in the buffer given to
|
If the user has typed more characters than fit in the buffer given to
|
the `read' call, the trailing characters are buffered in GDB until
|
the `read' call, the trailing characters are buffered in GDB until
|
either another `read(0, ...)' is requested by the target, or debugging
|
either another `read(0, ...)' is requested by the target, or debugging
|
is stopped at the user's request.
|
is stopped at the user's request.
|
|
|
|
|
File: gdb.info, Node: List of Supported Calls, Next: Protocol-specific Representation of Datatypes, Prev: Console I/O, Up: File-I/O Remote Protocol Extension
|
File: gdb.info, Node: List of Supported Calls, Next: Protocol-specific Representation of Datatypes, Prev: Console I/O, Up: File-I/O Remote Protocol Extension
|
|
|
D.10.7 List of Supported Calls
|
D.10.7 List of Supported Calls
|
------------------------------
|
------------------------------
|
|
|
* Menu:
|
* Menu:
|
|
|
* open::
|
* open::
|
* close::
|
* close::
|
* read::
|
* read::
|
* write::
|
* write::
|
* lseek::
|
* lseek::
|
* rename::
|
* rename::
|
* unlink::
|
* unlink::
|
* stat/fstat::
|
* stat/fstat::
|
* gettimeofday::
|
* gettimeofday::
|
* isatty::
|
* isatty::
|
* system::
|
* system::
|
|
|
|
|
File: gdb.info, Node: open, Next: close, Up: List of Supported Calls
|
File: gdb.info, Node: open, Next: close, Up: List of Supported Calls
|
|
|
open
|
open
|
....
|
....
|
|
|
Synopsis:
|
Synopsis:
|
int open(const char *pathname, int flags);
|
int open(const char *pathname, int flags);
|
int open(const char *pathname, int flags, mode_t mode);
|
int open(const char *pathname, int flags, mode_t mode);
|
|
|
Request:
|
Request:
|
`Fopen,PATHPTR/LEN,FLAGS,MODE'
|
`Fopen,PATHPTR/LEN,FLAGS,MODE'
|
|
|
FLAGS is the bitwise `OR' of the following values:
|
FLAGS is the bitwise `OR' of the following values:
|
|
|
`O_CREAT'
|
`O_CREAT'
|
If the file does not exist it will be created. The host
|
If the file does not exist it will be created. The host
|
rules apply as far as file ownership and time stamps are
|
rules apply as far as file ownership and time stamps are
|
concerned.
|
concerned.
|
|
|
`O_EXCL'
|
`O_EXCL'
|
When used with `O_CREAT', if the file already exists it is an
|
When used with `O_CREAT', if the file already exists it is an
|
error and open() fails.
|
error and open() fails.
|
|
|
`O_TRUNC'
|
`O_TRUNC'
|
If the file already exists and the open mode allows writing
|
If the file already exists and the open mode allows writing
|
(`O_RDWR' or `O_WRONLY' is given) it will be truncated to
|
(`O_RDWR' or `O_WRONLY' is given) it will be truncated to
|
zero length.
|
zero length.
|
|
|
`O_APPEND'
|
`O_APPEND'
|
The file is opened in append mode.
|
The file is opened in append mode.
|
|
|
`O_RDONLY'
|
`O_RDONLY'
|
The file is opened for reading only.
|
The file is opened for reading only.
|
|
|
`O_WRONLY'
|
`O_WRONLY'
|
The file is opened for writing only.
|
The file is opened for writing only.
|
|
|
`O_RDWR'
|
`O_RDWR'
|
The file is opened for reading and writing.
|
The file is opened for reading and writing.
|
|
|
Other bits are silently ignored.
|
Other bits are silently ignored.
|
|
|
MODE is the bitwise `OR' of the following values:
|
MODE is the bitwise `OR' of the following values:
|
|
|
`S_IRUSR'
|
`S_IRUSR'
|
User has read permission.
|
User has read permission.
|
|
|
`S_IWUSR'
|
`S_IWUSR'
|
User has write permission.
|
User has write permission.
|
|
|
`S_IRGRP'
|
`S_IRGRP'
|
Group has read permission.
|
Group has read permission.
|
|
|
`S_IWGRP'
|
`S_IWGRP'
|
Group has write permission.
|
Group has write permission.
|
|
|
`S_IROTH'
|
`S_IROTH'
|
Others have read permission.
|
Others have read permission.
|
|
|
`S_IWOTH'
|
`S_IWOTH'
|
Others have write permission.
|
Others have write permission.
|
|
|
Other bits are silently ignored.
|
Other bits are silently ignored.
|
|
|
Return value:
|
Return value:
|
`open' returns the new file descriptor or -1 if an error occurred.
|
`open' returns the new file descriptor or -1 if an error occurred.
|
|
|
Errors:
|
Errors:
|
|
|
`EEXIST'
|
`EEXIST'
|
PATHNAME already exists and `O_CREAT' and `O_EXCL' were used.
|
PATHNAME already exists and `O_CREAT' and `O_EXCL' were used.
|
|
|
`EISDIR'
|
`EISDIR'
|
PATHNAME refers to a directory.
|
PATHNAME refers to a directory.
|
|
|
`EACCES'
|
`EACCES'
|
The requested access is not allowed.
|
The requested access is not allowed.
|
|
|
`ENAMETOOLONG'
|
`ENAMETOOLONG'
|
PATHNAME was too long.
|
PATHNAME was too long.
|
|
|
`ENOENT'
|
`ENOENT'
|
A directory component in PATHNAME does not exist.
|
A directory component in PATHNAME does not exist.
|
|
|
`ENODEV'
|
`ENODEV'
|
PATHNAME refers to a device, pipe, named pipe or socket.
|
PATHNAME refers to a device, pipe, named pipe or socket.
|
|
|
`EROFS'
|
`EROFS'
|
PATHNAME refers to a file on a read-only filesystem and write
|
PATHNAME refers to a file on a read-only filesystem and write
|
access was requested.
|
access was requested.
|
|
|
`EFAULT'
|
`EFAULT'
|
PATHNAME is an invalid pointer value.
|
PATHNAME is an invalid pointer value.
|
|
|
`ENOSPC'
|
`ENOSPC'
|
No space on device to create the file.
|
No space on device to create the file.
|
|
|
`EMFILE'
|
`EMFILE'
|
The process already has the maximum number of files open.
|
The process already has the maximum number of files open.
|
|
|
`ENFILE'
|
`ENFILE'
|
The limit on the total number of files open on the system has
|
The limit on the total number of files open on the system has
|
been reached.
|
been reached.
|
|
|
`EINTR'
|
`EINTR'
|
The call was interrupted by the user.
|
The call was interrupted by the user.
|
|
|
|
|
|
|
File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls
|
File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls
|
|
|
close
|
close
|
.....
|
.....
|
|
|
Synopsis:
|
Synopsis:
|
int close(int fd);
|
int close(int fd);
|
|
|
Request:
|
Request:
|
`Fclose,FD'
|
`Fclose,FD'
|
|
|
Return value:
|
Return value:
|
`close' returns zero on success, or -1 if an error occurred.
|
`close' returns zero on success, or -1 if an error occurred.
|
|
|
Errors:
|
Errors:
|
|
|
`EBADF'
|
`EBADF'
|
FD isn't a valid open file descriptor.
|
FD isn't a valid open file descriptor.
|
|
|
`EINTR'
|
`EINTR'
|
The call was interrupted by the user.
|
The call was interrupted by the user.
|
|
|
|
|
|
|
File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls
|
File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls
|
|
|
read
|
read
|
....
|
....
|
|
|
Synopsis:
|
Synopsis:
|
int read(int fd, void *buf, unsigned int count);
|
int read(int fd, void *buf, unsigned int count);
|
|
|
Request:
|
Request:
|
`Fread,FD,BUFPTR,COUNT'
|
`Fread,FD,BUFPTR,COUNT'
|
|
|
Return value:
|
Return value:
|
On success, the number of bytes read is returned. Zero indicates
|
On success, the number of bytes read is returned. Zero indicates
|
end of file. If count is zero, read returns zero as well. On
|
end of file. If count is zero, read returns zero as well. On
|
error, -1 is returned.
|
error, -1 is returned.
|
|
|
Errors:
|
Errors:
|
|
|
`EBADF'
|
`EBADF'
|
FD is not a valid file descriptor or is not open for reading.
|
FD is not a valid file descriptor or is not open for reading.
|
|
|
`EFAULT'
|
`EFAULT'
|
BUFPTR is an invalid pointer value.
|
BUFPTR is an invalid pointer value.
|
|
|
`EINTR'
|
`EINTR'
|
The call was interrupted by the user.
|
The call was interrupted by the user.
|
|
|
|
|
|
|
File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls
|
File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls
|
|
|
write
|
write
|
.....
|
.....
|
|
|
Synopsis:
|
Synopsis:
|
int write(int fd, const void *buf, unsigned int count);
|
int write(int fd, const void *buf, unsigned int count);
|
|
|
Request:
|
Request:
|
`Fwrite,FD,BUFPTR,COUNT'
|
`Fwrite,FD,BUFPTR,COUNT'
|
|
|
Return value:
|
Return value:
|
On success, the number of bytes written are returned. Zero
|
On success, the number of bytes written are returned. Zero
|
indicates nothing was written. On error, -1 is returned.
|
indicates nothing was written. On error, -1 is returned.
|
|
|
Errors:
|
Errors:
|
|
|
`EBADF'
|
`EBADF'
|
FD is not a valid file descriptor or is not open for writing.
|
FD is not a valid file descriptor or is not open for writing.
|
|
|
`EFAULT'
|
`EFAULT'
|
BUFPTR is an invalid pointer value.
|
BUFPTR is an invalid pointer value.
|
|
|
`EFBIG'
|
`EFBIG'
|
An attempt was made to write a file that exceeds the
|
An attempt was made to write a file that exceeds the
|
host-specific maximum file size allowed.
|
host-specific maximum file size allowed.
|
|
|
`ENOSPC'
|
`ENOSPC'
|
No space on device to write the data.
|
No space on device to write the data.
|
|
|
`EINTR'
|
`EINTR'
|
The call was interrupted by the user.
|
The call was interrupted by the user.
|
|
|
|
|
|
|
File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls
|
File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls
|
|
|
lseek
|
lseek
|
.....
|
.....
|
|
|
Synopsis:
|
Synopsis:
|
long lseek (int fd, long offset, int flag);
|
long lseek (int fd, long offset, int flag);
|
|
|
Request:
|
Request:
|
`Flseek,FD,OFFSET,FLAG'
|
`Flseek,FD,OFFSET,FLAG'
|
|
|
FLAG is one of:
|
FLAG is one of:
|
|
|
`SEEK_SET'
|
`SEEK_SET'
|
The offset is set to OFFSET bytes.
|
The offset is set to OFFSET bytes.
|
|
|
`SEEK_CUR'
|
`SEEK_CUR'
|
The offset is set to its current location plus OFFSET bytes.
|
The offset is set to its current location plus OFFSET bytes.
|
|
|
`SEEK_END'
|
`SEEK_END'
|
The offset is set to the size of the file plus OFFSET bytes.
|
The offset is set to the size of the file plus OFFSET bytes.
|
|
|
Return value:
|
Return value:
|
On success, the resulting unsigned offset in bytes from the
|
On success, the resulting unsigned offset in bytes from the
|
beginning of the file is returned. Otherwise, a value of -1 is
|
beginning of the file is returned. Otherwise, a value of -1 is
|
returned.
|
returned.
|
|
|
Errors:
|
Errors:
|
|
|
`EBADF'
|
`EBADF'
|
FD is not a valid open file descriptor.
|
FD is not a valid open file descriptor.
|
|
|
`ESPIPE'
|
`ESPIPE'
|
FD is associated with the GDB console.
|
FD is associated with the GDB console.
|
|
|
`EINVAL'
|
`EINVAL'
|
FLAG is not a proper value.
|
FLAG is not a proper value.
|
|
|
`EINTR'
|
`EINTR'
|
The call was interrupted by the user.
|
The call was interrupted by the user.
|
|
|
|
|
|
|
File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls
|
File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls
|
|
|
rename
|
rename
|
......
|
......
|
|
|
Synopsis:
|
Synopsis:
|
int rename(const char *oldpath, const char *newpath);
|
int rename(const char *oldpath, const char *newpath);
|
|
|
Request:
|
Request:
|
`Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'
|
`Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'
|
|
|
Return value:
|
Return value:
|
On success, zero is returned. On error, -1 is returned.
|
On success, zero is returned. On error, -1 is returned.
|
|
|
Errors:
|
Errors:
|
|
|
`EISDIR'
|
`EISDIR'
|
NEWPATH is an existing directory, but OLDPATH is not a
|
NEWPATH is an existing directory, but OLDPATH is not a
|
directory.
|
directory.
|
|
|
`EEXIST'
|
`EEXIST'
|
NEWPATH is a non-empty directory.
|
NEWPATH is a non-empty directory.
|
|
|
`EBUSY'
|
`EBUSY'
|
OLDPATH or NEWPATH is a directory that is in use by some
|
OLDPATH or NEWPATH is a directory that is in use by some
|
process.
|
process.
|
|
|
`EINVAL'
|
`EINVAL'
|
An attempt was made to make a directory a subdirectory of
|
An attempt was made to make a directory a subdirectory of
|
itself.
|
itself.
|
|
|
`ENOTDIR'
|
`ENOTDIR'
|
A component used as a directory in OLDPATH or new path is
|
A component used as a directory in OLDPATH or new path is
|
not a directory. Or OLDPATH is a directory and NEWPATH
|
not a directory. Or OLDPATH is a directory and NEWPATH
|
exists but is not a directory.
|
exists but is not a directory.
|
|
|
`EFAULT'
|
`EFAULT'
|
OLDPATHPTR or NEWPATHPTR are invalid pointer values.
|
OLDPATHPTR or NEWPATHPTR are invalid pointer values.
|
|
|
`EACCES'
|
`EACCES'
|
No access to the file or the path of the file.
|
No access to the file or the path of the file.
|
|
|
`ENAMETOOLONG'
|
`ENAMETOOLONG'
|
OLDPATH or NEWPATH was too long.
|
OLDPATH or NEWPATH was too long.
|
|
|
`ENOENT'
|
`ENOENT'
|
A directory component in OLDPATH or NEWPATH does not exist.
|
A directory component in OLDPATH or NEWPATH does not exist.
|
|
|
`EROFS'
|
`EROFS'
|
The file is on a read-only filesystem.
|
The file is on a read-only filesystem.
|
|
|
`ENOSPC'
|
`ENOSPC'
|
The device containing the file has no room for the new
|
The device containing the file has no room for the new
|
directory entry.
|
directory entry.
|
|
|
`EINTR'
|
`EINTR'
|
The call was interrupted by the user.
|
The call was interrupted by the user.
|
|
|
|
|
|
|
File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls
|
File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls
|
|
|
unlink
|
unlink
|
......
|
......
|
|
|
Synopsis:
|
Synopsis:
|
int unlink(const char *pathname);
|
int unlink(const char *pathname);
|
|
|
Request:
|
Request:
|
`Funlink,PATHNAMEPTR/LEN'
|
`Funlink,PATHNAMEPTR/LEN'
|
|
|
Return value:
|
Return value:
|
On success, zero is returned. On error, -1 is returned.
|
On success, zero is returned. On error, -1 is returned.
|
|
|
Errors:
|
Errors:
|
|
|
`EACCES'
|
`EACCES'
|
No access to the file or the path of the file.
|
No access to the file or the path of the file.
|
|
|
`EPERM'
|
`EPERM'
|
The system does not allow unlinking of directories.
|
The system does not allow unlinking of directories.
|
|
|
`EBUSY'
|
`EBUSY'
|
The file PATHNAME cannot be unlinked because it's being used
|
The file PATHNAME cannot be unlinked because it's being used
|
by another process.
|
by another process.
|
|
|
`EFAULT'
|
`EFAULT'
|
PATHNAMEPTR is an invalid pointer value.
|
PATHNAMEPTR is an invalid pointer value.
|
|
|
`ENAMETOOLONG'
|
`ENAMETOOLONG'
|
PATHNAME was too long.
|
PATHNAME was too long.
|
|
|
`ENOENT'
|
`ENOENT'
|
A directory component in PATHNAME does not exist.
|
A directory component in PATHNAME does not exist.
|
|
|
`ENOTDIR'
|
`ENOTDIR'
|
A component of the path is not a directory.
|
A component of the path is not a directory.
|
|
|
`EROFS'
|
`EROFS'
|
The file is on a read-only filesystem.
|
The file is on a read-only filesystem.
|
|
|
`EINTR'
|
`EINTR'
|
The call was interrupted by the user.
|
The call was interrupted by the user.
|
|
|
|
|
|
|
File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls
|
File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls
|
|
|
stat/fstat
|
stat/fstat
|
..........
|
..........
|
|
|
Synopsis:
|
Synopsis:
|
int stat(const char *pathname, struct stat *buf);
|
int stat(const char *pathname, struct stat *buf);
|
int fstat(int fd, struct stat *buf);
|
int fstat(int fd, struct stat *buf);
|
|
|
Request:
|
Request:
|
`Fstat,PATHNAMEPTR/LEN,BUFPTR'
|
`Fstat,PATHNAMEPTR/LEN,BUFPTR'
|
`Ffstat,FD,BUFPTR'
|
`Ffstat,FD,BUFPTR'
|
|
|
Return value:
|
Return value:
|
On success, zero is returned. On error, -1 is returned.
|
On success, zero is returned. On error, -1 is returned.
|
|
|
Errors:
|
Errors:
|
|
|
`EBADF'
|
`EBADF'
|
FD is not a valid open file.
|
FD is not a valid open file.
|
|
|
`ENOENT'
|
`ENOENT'
|
A directory component in PATHNAME does not exist or the path
|
A directory component in PATHNAME does not exist or the path
|
is an empty string.
|
is an empty string.
|
|
|
`ENOTDIR'
|
`ENOTDIR'
|
A component of the path is not a directory.
|
A component of the path is not a directory.
|
|
|
`EFAULT'
|
`EFAULT'
|
PATHNAMEPTR is an invalid pointer value.
|
PATHNAMEPTR is an invalid pointer value.
|
|
|
`EACCES'
|
`EACCES'
|
No access to the file or the path of the file.
|
No access to the file or the path of the file.
|
|
|
`ENAMETOOLONG'
|
`ENAMETOOLONG'
|
PATHNAME was too long.
|
PATHNAME was too long.
|
|
|
`EINTR'
|
`EINTR'
|
The call was interrupted by the user.
|
The call was interrupted by the user.
|
|
|
|
|
|
|
File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls
|
File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls
|
|
|
gettimeofday
|
gettimeofday
|
............
|
............
|
|
|
Synopsis:
|
Synopsis:
|
int gettimeofday(struct timeval *tv, void *tz);
|
int gettimeofday(struct timeval *tv, void *tz);
|
|
|
Request:
|
Request:
|
`Fgettimeofday,TVPTR,TZPTR'
|
`Fgettimeofday,TVPTR,TZPTR'
|
|
|
Return value:
|
Return value:
|
On success, 0 is returned, -1 otherwise.
|
On success, 0 is returned, -1 otherwise.
|
|
|
Errors:
|
Errors:
|
|
|
`EINVAL'
|
`EINVAL'
|
TZ is a non-NULL pointer.
|
TZ is a non-NULL pointer.
|
|
|
`EFAULT'
|
`EFAULT'
|
TVPTR and/or TZPTR is an invalid pointer value.
|
TVPTR and/or TZPTR is an invalid pointer value.
|
|
|
|
|
|
|
File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls
|
File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls
|
|
|
isatty
|
isatty
|
......
|
......
|
|
|
Synopsis:
|
Synopsis:
|
int isatty(int fd);
|
int isatty(int fd);
|
|
|
Request:
|
Request:
|
`Fisatty,FD'
|
`Fisatty,FD'
|
|
|
Return value:
|
Return value:
|
Returns 1 if FD refers to the GDB console, 0 otherwise.
|
Returns 1 if FD refers to the GDB console, 0 otherwise.
|
|
|
Errors:
|
Errors:
|
|
|
`EINTR'
|
`EINTR'
|
The call was interrupted by the user.
|
The call was interrupted by the user.
|
|
|
|
|
Note that the `isatty' call is treated as a special case: it returns
|
Note that the `isatty' call is treated as a special case: it returns
|
1 to the target if the file descriptor is attached to the GDB console,
|
1 to the target if the file descriptor is attached to the GDB console,
|
0 otherwise. Implementing through system calls would require
|
0 otherwise. Implementing through system calls would require
|
implementing `ioctl' and would be more complex than needed.
|
implementing `ioctl' and would be more complex than needed.
|
|
|
|
|
File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls
|
File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls
|
|
|
system
|
system
|
......
|
......
|
|
|
Synopsis:
|
Synopsis:
|
int system(const char *command);
|
int system(const char *command);
|
|
|
Request:
|
Request:
|
`Fsystem,COMMANDPTR/LEN'
|
`Fsystem,COMMANDPTR/LEN'
|
|
|
Return value:
|
Return value:
|
If LEN is zero, the return value indicates whether a shell is
|
If LEN is zero, the return value indicates whether a shell is
|
available. A zero return value indicates a shell is not available.
|
available. A zero return value indicates a shell is not available.
|
For non-zero LEN, the value returned is -1 on error and the return
|
For non-zero LEN, the value returned is -1 on error and the return
|
status of the command otherwise. Only the exit status of the
|
status of the command otherwise. Only the exit status of the
|
command is returned, which is extracted from the host's `system'
|
command is returned, which is extracted from the host's `system'
|
return value by calling `WEXITSTATUS(retval)'. In case `/bin/sh'
|
return value by calling `WEXITSTATUS(retval)'. In case `/bin/sh'
|
could not be executed, 127 is returned.
|
could not be executed, 127 is returned.
|
|
|
Errors:
|
Errors:
|
|
|
`EINTR'
|
`EINTR'
|
The call was interrupted by the user.
|
The call was interrupted by the user.
|
|
|
|
|
GDB takes over the full task of calling the necessary host calls to
|
GDB takes over the full task of calling the necessary host calls to
|
perform the `system' call. The return value of `system' on the host is
|
perform the `system' call. The return value of `system' on the host is
|
simplified before it's returned to the target. Any termination signal
|
simplified before it's returned to the target. Any termination signal
|
information from the child process is discarded, and the return value
|
information from the child process is discarded, and the return value
|
consists entirely of the exit status of the called command.
|
consists entirely of the exit status of the called command.
|
|
|
Due to security concerns, the `system' call is by default refused by
|
Due to security concerns, the `system' call is by default refused by
|
GDB. The user has to allow this call explicitly with the `set remote
|
GDB. The user has to allow this call explicitly with the `set remote
|
system-call-allowed 1' command.
|
system-call-allowed 1' command.
|
|
|
`set remote system-call-allowed'
|
`set remote system-call-allowed'
|
Control whether to allow the `system' calls in the File I/O
|
Control whether to allow the `system' calls in the File I/O
|
protocol for the remote target. The default is zero (disabled).
|
protocol for the remote target. The default is zero (disabled).
|
|
|
`show remote system-call-allowed'
|
`show remote system-call-allowed'
|
Show whether the `system' calls are allowed in the File I/O
|
Show whether the `system' calls are allowed in the File I/O
|
protocol.
|
protocol.
|
|
|
|
|
File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension
|
File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension
|
|
|
D.10.8 Protocol-specific Representation of Datatypes
|
D.10.8 Protocol-specific Representation of Datatypes
|
----------------------------------------------------
|
----------------------------------------------------
|
|
|
* Menu:
|
* Menu:
|
|
|
* Integral Datatypes::
|
* Integral Datatypes::
|
* Pointer Values::
|
* Pointer Values::
|
* Memory Transfer::
|
* Memory Transfer::
|
* struct stat::
|
* struct stat::
|
* struct timeval::
|
* struct timeval::
|
|
|
|
|
File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes
|
File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes
|
|
|
Integral Datatypes
|
Integral Datatypes
|
..................
|
..................
|
|
|
The integral datatypes used in the system calls are `int', `unsigned
|
The integral datatypes used in the system calls are `int', `unsigned
|
int', `long', `unsigned long', `mode_t', and `time_t'.
|
int', `long', `unsigned long', `mode_t', and `time_t'.
|
|
|
`int', `unsigned int', `mode_t' and `time_t' are implemented as 32
|
`int', `unsigned int', `mode_t' and `time_t' are implemented as 32
|
bit values in this protocol.
|
bit values in this protocol.
|
|
|
`long' and `unsigned long' are implemented as 64 bit types.
|
`long' and `unsigned long' are implemented as 64 bit types.
|
|
|
*Note Limits::, for corresponding MIN and MAX values (similar to
|
*Note Limits::, for corresponding MIN and MAX values (similar to
|
those in `limits.h') to allow range checking on host and target.
|
those in `limits.h') to allow range checking on host and target.
|
|
|
`time_t' datatypes are defined as seconds since the Epoch.
|
`time_t' datatypes are defined as seconds since the Epoch.
|
|
|
All integral datatypes transferred as part of a memory read or write
|
All integral datatypes transferred as part of a memory read or write
|
of a structured datatype e.g. a `struct stat' have to be given in big
|
of a structured datatype e.g. a `struct stat' have to be given in big
|
endian byte order.
|
endian byte order.
|
|
|
|
|
File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes
|
File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes
|
|
|
Pointer Values
|
Pointer Values
|
..............
|
..............
|
|
|
Pointers to target data are transmitted as they are. An exception is
|
Pointers to target data are transmitted as they are. An exception is
|
made for pointers to buffers for which the length isn't transmitted as
|
made for pointers to buffers for which the length isn't transmitted as
|
part of the function call, namely strings. Strings are transmitted as
|
part of the function call, namely strings. Strings are transmitted as
|
a pointer/length pair, both as hex values, e.g.
|
a pointer/length pair, both as hex values, e.g.
|
|
|
`1aaf/12'
|
`1aaf/12'
|
|
|
which is a pointer to data of length 18 bytes at position 0x1aaf. The
|
which is a pointer to data of length 18 bytes at position 0x1aaf. The
|
length is defined as the full string length in bytes, including the
|
length is defined as the full string length in bytes, including the
|
trailing null byte. For example, the string `"hello world"' at address
|
trailing null byte. For example, the string `"hello world"' at address
|
0x123456 is transmitted as
|
0x123456 is transmitted as
|
|
|
`123456/d'
|
`123456/d'
|
|
|
|
|
File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes
|
File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes
|
|
|
Memory Transfer
|
Memory Transfer
|
...............
|
...............
|
|
|
Structured data which is transferred using a memory read or write (for
|
Structured data which is transferred using a memory read or write (for
|
example, a `struct stat') is expected to be in a protocol-specific
|
example, a `struct stat') is expected to be in a protocol-specific
|
format with all scalar multibyte datatypes being big endian.
|
format with all scalar multibyte datatypes being big endian.
|
Translation to this representation needs to be done both by the target
|
Translation to this representation needs to be done both by the target
|
before the `F' packet is sent, and by GDB before it transfers memory to
|
before the `F' packet is sent, and by GDB before it transfers memory to
|
the target. Transferred pointers to structured data should point to
|
the target. Transferred pointers to structured data should point to
|
the already-coerced data at any time.
|
the already-coerced data at any time.
|
|
|
|
|
File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes
|
File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes
|
|
|
struct stat
|
struct stat
|
...........
|
...........
|
|
|
The buffer of type `struct stat' used by the target and GDB is defined
|
The buffer of type `struct stat' used by the target and GDB is defined
|
as follows:
|
as follows:
|
|
|
struct stat {
|
struct stat {
|
unsigned int st_dev; /* device */
|
unsigned int st_dev; /* device */
|
unsigned int st_ino; /* inode */
|
unsigned int st_ino; /* inode */
|
mode_t st_mode; /* protection */
|
mode_t st_mode; /* protection */
|
unsigned int st_nlink; /* number of hard links */
|
unsigned int st_nlink; /* number of hard links */
|
unsigned int st_uid; /* user ID of owner */
|
unsigned int st_uid; /* user ID of owner */
|
unsigned int st_gid; /* group ID of owner */
|
unsigned int st_gid; /* group ID of owner */
|
unsigned int st_rdev; /* device type (if inode device) */
|
unsigned int st_rdev; /* device type (if inode device) */
|
unsigned long st_size; /* total size, in bytes */
|
unsigned long st_size; /* total size, in bytes */
|
unsigned long st_blksize; /* blocksize for filesystem I/O */
|
unsigned long st_blksize; /* blocksize for filesystem I/O */
|
unsigned long st_blocks; /* number of blocks allocated */
|
unsigned long st_blocks; /* number of blocks allocated */
|
time_t st_atime; /* time of last access */
|
time_t st_atime; /* time of last access */
|
time_t st_mtime; /* time of last modification */
|
time_t st_mtime; /* time of last modification */
|
time_t st_ctime; /* time of last change */
|
time_t st_ctime; /* time of last change */
|
};
|
};
|
|
|
The integral datatypes conform to the definitions given in the
|
The integral datatypes conform to the definitions given in the
|
appropriate section (see *Note Integral Datatypes::, for details) so
|
appropriate section (see *Note Integral Datatypes::, for details) so
|
this structure is of size 64 bytes.
|
this structure is of size 64 bytes.
|
|
|
The values of several fields have a restricted meaning and/or range
|
The values of several fields have a restricted meaning and/or range
|
of values.
|
of values.
|
|
|
`st_dev'
|
`st_dev'
|
A value of 0 represents a file, 1 the console.
|
A value of 0 represents a file, 1 the console.
|
|
|
`st_ino'
|
`st_ino'
|
No valid meaning for the target. Transmitted unchanged.
|
No valid meaning for the target. Transmitted unchanged.
|
|
|
`st_mode'
|
`st_mode'
|
Valid mode bits are described in *Note Constants::. Any other
|
Valid mode bits are described in *Note Constants::. Any other
|
bits have currently no meaning for the target.
|
bits have currently no meaning for the target.
|
|
|
`st_uid'
|
`st_uid'
|
`st_gid'
|
`st_gid'
|
`st_rdev'
|
`st_rdev'
|
No valid meaning for the target. Transmitted unchanged.
|
No valid meaning for the target. Transmitted unchanged.
|
|
|
`st_atime'
|
`st_atime'
|
`st_mtime'
|
`st_mtime'
|
`st_ctime'
|
`st_ctime'
|
These values have a host and file system dependent accuracy.
|
These values have a host and file system dependent accuracy.
|
Especially on Windows hosts, the file system may not support exact
|
Especially on Windows hosts, the file system may not support exact
|
timing values.
|
timing values.
|
|
|
The target gets a `struct stat' of the above representation and is
|
The target gets a `struct stat' of the above representation and is
|
responsible for coercing it to the target representation before
|
responsible for coercing it to the target representation before
|
continuing.
|
continuing.
|
|
|
Note that due to size differences between the host, target, and
|
Note that due to size differences between the host, target, and
|
protocol representations of `struct stat' members, these members could
|
protocol representations of `struct stat' members, these members could
|
eventually get truncated on the target.
|
eventually get truncated on the target.
|
|
|
|
|
File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes
|
File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes
|
|
|
struct timeval
|
struct timeval
|
..............
|
..............
|
|
|
The buffer of type `struct timeval' used by the File-I/O protocol is
|
The buffer of type `struct timeval' used by the File-I/O protocol is
|
defined as follows:
|
defined as follows:
|
|
|
struct timeval {
|
struct timeval {
|
time_t tv_sec; /* second */
|
time_t tv_sec; /* second */
|
long tv_usec; /* microsecond */
|
long tv_usec; /* microsecond */
|
};
|
};
|
|
|
The integral datatypes conform to the definitions given in the
|
The integral datatypes conform to the definitions given in the
|
appropriate section (see *Note Integral Datatypes::, for details) so
|
appropriate section (see *Note Integral Datatypes::, for details) so
|
this structure is of size 8 bytes.
|
this structure is of size 8 bytes.
|
|
|
|
|
File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension
|
File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension
|
|
|
D.10.9 Constants
|
D.10.9 Constants
|
----------------
|
----------------
|
|
|
The following values are used for the constants inside of the protocol.
|
The following values are used for the constants inside of the protocol.
|
GDB and target are responsible for translating these values before and
|
GDB and target are responsible for translating these values before and
|
after the call as needed.
|
after the call as needed.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Open Flags::
|
* Open Flags::
|
* mode_t Values::
|
* mode_t Values::
|
* Errno Values::
|
* Errno Values::
|
* Lseek Flags::
|
* Lseek Flags::
|
* Limits::
|
* Limits::
|
|
|
|
|
File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants
|
File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants
|
|
|
Open Flags
|
Open Flags
|
..........
|
..........
|
|
|
All values are given in hexadecimal representation.
|
All values are given in hexadecimal representation.
|
|
|
O_RDONLY 0x0
|
O_RDONLY 0x0
|
O_WRONLY 0x1
|
O_WRONLY 0x1
|
O_RDWR 0x2
|
O_RDWR 0x2
|
O_APPEND 0x8
|
O_APPEND 0x8
|
O_CREAT 0x200
|
O_CREAT 0x200
|
O_TRUNC 0x400
|
O_TRUNC 0x400
|
O_EXCL 0x800
|
O_EXCL 0x800
|
|
|
|
|
File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants
|
File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants
|
|
|
mode_t Values
|
mode_t Values
|
.............
|
.............
|
|
|
All values are given in octal representation.
|
All values are given in octal representation.
|
|
|
S_IFREG 0100000
|
S_IFREG 0100000
|
S_IFDIR 040000
|
S_IFDIR 040000
|
S_IRUSR 0400
|
S_IRUSR 0400
|
S_IWUSR 0200
|
S_IWUSR 0200
|
S_IXUSR 0100
|
S_IXUSR 0100
|
S_IRGRP 040
|
S_IRGRP 040
|
S_IWGRP 020
|
S_IWGRP 020
|
S_IXGRP 010
|
S_IXGRP 010
|
S_IROTH 04
|
S_IROTH 04
|
S_IWOTH 02
|
S_IWOTH 02
|
S_IXOTH 01
|
S_IXOTH 01
|
|
|
|
|
File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants
|
File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants
|
|
|
Errno Values
|
Errno Values
|
............
|
............
|
|
|
All values are given in decimal representation.
|
All values are given in decimal representation.
|
|
|
EPERM 1
|
EPERM 1
|
ENOENT 2
|
ENOENT 2
|
EINTR 4
|
EINTR 4
|
EBADF 9
|
EBADF 9
|
EACCES 13
|
EACCES 13
|
EFAULT 14
|
EFAULT 14
|
EBUSY 16
|
EBUSY 16
|
EEXIST 17
|
EEXIST 17
|
ENODEV 19
|
ENODEV 19
|
ENOTDIR 20
|
ENOTDIR 20
|
EISDIR 21
|
EISDIR 21
|
EINVAL 22
|
EINVAL 22
|
ENFILE 23
|
ENFILE 23
|
EMFILE 24
|
EMFILE 24
|
EFBIG 27
|
EFBIG 27
|
ENOSPC 28
|
ENOSPC 28
|
ESPIPE 29
|
ESPIPE 29
|
EROFS 30
|
EROFS 30
|
ENAMETOOLONG 91
|
ENAMETOOLONG 91
|
EUNKNOWN 9999
|
EUNKNOWN 9999
|
|
|
`EUNKNOWN' is used as a fallback error value if a host system returns
|
`EUNKNOWN' is used as a fallback error value if a host system returns
|
any error value not in the list of supported error numbers.
|
any error value not in the list of supported error numbers.
|
|
|
|
|
File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants
|
File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants
|
|
|
Lseek Flags
|
Lseek Flags
|
...........
|
...........
|
|
|
SEEK_SET 0
|
SEEK_SET 0
|
SEEK_CUR 1
|
SEEK_CUR 1
|
SEEK_END 2
|
SEEK_END 2
|
|
|
|
|
File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants
|
File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants
|
|
|
Limits
|
Limits
|
......
|
......
|
|
|
All values are given in decimal representation.
|
All values are given in decimal representation.
|
|
|
INT_MIN -2147483648
|
INT_MIN -2147483648
|
INT_MAX 2147483647
|
INT_MAX 2147483647
|
UINT_MAX 4294967295
|
UINT_MAX 4294967295
|
LONG_MIN -9223372036854775808
|
LONG_MIN -9223372036854775808
|
LONG_MAX 9223372036854775807
|
LONG_MAX 9223372036854775807
|
ULONG_MAX 18446744073709551615
|
ULONG_MAX 18446744073709551615
|
|
|
|
|
File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension
|
File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension
|
|
|
D.10.10 File-I/O Examples
|
D.10.10 File-I/O Examples
|
-------------------------
|
-------------------------
|
|
|
Example sequence of a write call, file descriptor 3, buffer is at target
|
Example sequence of a write call, file descriptor 3, buffer is at target
|
address 0x1234, 6 bytes should be written:
|
address 0x1234, 6 bytes should be written:
|
|
|
<- `Fwrite,3,1234,6'
|
<- `Fwrite,3,1234,6'
|
_request memory read from target_
|
_request memory read from target_
|
-> `m1234,6'
|
-> `m1234,6'
|
<- XXXXXX
|
<- XXXXXX
|
_return "6 bytes written"_
|
_return "6 bytes written"_
|
-> `F6'
|
-> `F6'
|
|
|
Example sequence of a read call, file descriptor 3, buffer is at
|
Example sequence of a read call, file descriptor 3, buffer is at
|
target address 0x1234, 6 bytes should be read:
|
target address 0x1234, 6 bytes should be read:
|
|
|
<- `Fread,3,1234,6'
|
<- `Fread,3,1234,6'
|
_request memory write to target_
|
_request memory write to target_
|
-> `X1234,6:XXXXXX'
|
-> `X1234,6:XXXXXX'
|
_return "6 bytes read"_
|
_return "6 bytes read"_
|
-> `F6'
|
-> `F6'
|
|
|
Example sequence of a read call, call fails on the host due to
|
Example sequence of a read call, call fails on the host due to
|
invalid file descriptor (`EBADF'):
|
invalid file descriptor (`EBADF'):
|
|
|
<- `Fread,3,1234,6'
|
<- `Fread,3,1234,6'
|
-> `F-1,9'
|
-> `F-1,9'
|
|
|
Example sequence of a read call, user presses `Ctrl-c' before
|
Example sequence of a read call, user presses `Ctrl-c' before
|
syscall on host is called:
|
syscall on host is called:
|
|
|
<- `Fread,3,1234,6'
|
<- `Fread,3,1234,6'
|
-> `F-1,4,C'
|
-> `F-1,4,C'
|
<- `T02'
|
<- `T02'
|
|
|
Example sequence of a read call, user presses `Ctrl-c' after syscall
|
Example sequence of a read call, user presses `Ctrl-c' after syscall
|
on host is called:
|
on host is called:
|
|
|
<- `Fread,3,1234,6'
|
<- `Fread,3,1234,6'
|
-> `X1234,6:XXXXXX'
|
-> `X1234,6:XXXXXX'
|
<- `T02'
|
<- `T02'
|
|
|
|
|
File: gdb.info, Node: Library List Format, Next: Memory Map Format, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol
|
File: gdb.info, Node: Library List Format, Next: Memory Map Format, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol
|
|
|
D.11 Library List Format
|
D.11 Library List Format
|
========================
|
========================
|
|
|
On some platforms, a dynamic loader (e.g. `ld.so') runs in the same
|
On some platforms, a dynamic loader (e.g. `ld.so') runs in the same
|
process as your application to manage libraries. In this case, GDB can
|
process as your application to manage libraries. In this case, GDB can
|
use the loader's symbol table and normal memory operations to maintain
|
use the loader's symbol table and normal memory operations to maintain
|
a list of shared libraries. On other platforms, the operating system
|
a list of shared libraries. On other platforms, the operating system
|
manages loaded libraries. GDB can not retrieve the list of currently
|
manages loaded libraries. GDB can not retrieve the list of currently
|
loaded libraries through memory operations, so it uses the
|
loaded libraries through memory operations, so it uses the
|
`qXfer:libraries:read' packet (*note qXfer library list read::)
|
`qXfer:libraries:read' packet (*note qXfer library list read::)
|
instead. The remote stub queries the target's operating system and
|
instead. The remote stub queries the target's operating system and
|
reports which libraries are loaded.
|
reports which libraries are loaded.
|
|
|
The `qXfer:libraries:read' packet returns an XML document which
|
The `qXfer:libraries:read' packet returns an XML document which
|
lists loaded libraries and their offsets. Each library has an
|
lists loaded libraries and their offsets. Each library has an
|
associated name and one or more segment base addresses, which report
|
associated name and one or more segment base addresses, which report
|
where the library was loaded in memory. The segment bases are start
|
where the library was loaded in memory. The segment bases are start
|
addresses, not relocation offsets; they do not depend on the library's
|
addresses, not relocation offsets; they do not depend on the library's
|
link-time base addresses.
|
link-time base addresses.
|
|
|
GDB must be linked with the Expat library to support XML library
|
GDB must be linked with the Expat library to support XML library
|
lists. *Note Expat::.
|
lists. *Note Expat::.
|
|
|
A simple memory map, with one loaded library relocated by a single
|
A simple memory map, with one loaded library relocated by a single
|
offset, looks like this:
|
offset, looks like this:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The format of a library list is described by this DTD:
|
The format of a library list is described by this DTD:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: gdb.info, Node: Memory Map Format, Prev: Library List Format, Up: Remote Protocol
|
File: gdb.info, Node: Memory Map Format, Prev: Library List Format, Up: Remote Protocol
|
|
|
D.12 Memory Map Format
|
D.12 Memory Map Format
|
======================
|
======================
|
|
|
To be able to write into flash memory, GDB needs to obtain a memory map
|
To be able to write into flash memory, GDB needs to obtain a memory map
|
from the target. This section describes the format of the memory map.
|
from the target. This section describes the format of the memory map.
|
|
|
The memory map is obtained using the `qXfer:memory-map:read' (*note
|
The memory map is obtained using the `qXfer:memory-map:read' (*note
|
qXfer memory map read::) packet and is an XML document that lists
|
qXfer memory map read::) packet and is an XML document that lists
|
memory regions.
|
memory regions.
|
|
|
GDB must be linked with the Expat library to support XML memory
|
GDB must be linked with the Expat library to support XML memory
|
maps. *Note Expat::.
|
maps. *Note Expat::.
|
|
|
The top-level structure of the document is shown below:
|
The top-level structure of the document is shown below:
|
|
|
|
|
|
|
PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
|
PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
|
"http://sourceware.org/gdb/gdb-memory-map.dtd">
|
"http://sourceware.org/gdb/gdb-memory-map.dtd">
|
|
|
region...
|
region...
|
|
|
|
|
Each region can be either:
|
Each region can be either:
|
|
|
* A region of RAM starting at ADDR and extending for LENGTH bytes
|
* A region of RAM starting at ADDR and extending for LENGTH bytes
|
from there:
|
from there:
|
|
|
|
|
|
|
* A region of read-only memory:
|
* A region of read-only memory:
|
|
|
|
|
|
|
* A region of flash memory, with erasure blocks BLOCKSIZE bytes in
|
* A region of flash memory, with erasure blocks BLOCKSIZE bytes in
|
length:
|
length:
|
|
|
|
|
BLOCKSIZE
|
BLOCKSIZE
|
|
|
|
|
|
|
Regions must not overlap. GDB assumes that areas of memory not
|
Regions must not overlap. GDB assumes that areas of memory not
|
covered by the memory map are RAM, and uses the ordinary `M' and `X'
|
covered by the memory map are RAM, and uses the ordinary `M' and `X'
|
packets to write to addresses in such ranges.
|
packets to write to addresses in such ranges.
|
|
|
The formal DTD for memory map format is given below:
|
The formal DTD for memory map format is given below:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
and its type, or device. -->
|
|
|
start CDATA #REQUIRED
|
start CDATA #REQUIRED
|
length CDATA #REQUIRED
|
length CDATA #REQUIRED
|
device CDATA #IMPLIED>
|
device CDATA #IMPLIED>
|
|
|
|
|
|
|
|
|
|
|
File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top
|
File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top
|
|
|
Appendix E The GDB Agent Expression Mechanism
|
Appendix E The GDB Agent Expression Mechanism
|
*********************************************
|
*********************************************
|
|
|
In some applications, it is not feasible for the debugger to interrupt
|
In some applications, it is not feasible for the debugger to interrupt
|
the program's execution long enough for the developer to learn anything
|
the program's execution long enough for the developer to learn anything
|
helpful about its behavior. If the program's correctness depends on its
|
helpful about its behavior. If the program's correctness depends on its
|
real-time behavior, delays introduced by a debugger might cause the
|
real-time behavior, delays introduced by a debugger might cause the
|
program to fail, even when the code itself is correct. It is useful to
|
program to fail, even when the code itself is correct. It is useful to
|
be able to observe the program's behavior without interrupting it.
|
be able to observe the program's behavior without interrupting it.
|
|
|
Using GDB's `trace' and `collect' commands, the user can specify
|
Using GDB's `trace' and `collect' commands, the user can specify
|
locations in the program, and arbitrary expressions to evaluate when
|
locations in the program, and arbitrary expressions to evaluate when
|
those locations are reached. Later, using the `tfind' command, she can
|
those locations are reached. Later, using the `tfind' command, she can
|
examine the values those expressions had when the program hit the trace
|
examine the values those expressions had when the program hit the trace
|
points. The expressions may also denote objects in memory --
|
points. The expressions may also denote objects in memory --
|
structures or arrays, for example -- whose values GDB should record;
|
structures or arrays, for example -- whose values GDB should record;
|
while visiting a particular tracepoint, the user may inspect those
|
while visiting a particular tracepoint, the user may inspect those
|
objects as if they were in memory at that moment. However, because GDB
|
objects as if they were in memory at that moment. However, because GDB
|
records these values without interacting with the user, it can do so
|
records these values without interacting with the user, it can do so
|
quickly and unobtrusively, hopefully not disturbing the program's
|
quickly and unobtrusively, hopefully not disturbing the program's
|
behavior.
|
behavior.
|
|
|
When GDB is debugging a remote target, the GDB "agent" code running
|
When GDB is debugging a remote target, the GDB "agent" code running
|
on the target computes the values of the expressions itself. To avoid
|
on the target computes the values of the expressions itself. To avoid
|
having a full symbolic expression evaluator on the agent, GDB translates
|
having a full symbolic expression evaluator on the agent, GDB translates
|
expressions in the source language into a simpler bytecode language, and
|
expressions in the source language into a simpler bytecode language, and
|
then sends the bytecode to the agent; the agent then executes the
|
then sends the bytecode to the agent; the agent then executes the
|
bytecode, and records the values for GDB to retrieve later.
|
bytecode, and records the values for GDB to retrieve later.
|
|
|
The bytecode language is simple; there are forty-odd opcodes, the
|
The bytecode language is simple; there are forty-odd opcodes, the
|
bulk of which are the usual vocabulary of C operands (addition,
|
bulk of which are the usual vocabulary of C operands (addition,
|
subtraction, shifts, and so on) and various sizes of literals and
|
subtraction, shifts, and so on) and various sizes of literals and
|
memory reference operations. The bytecode interpreter operates
|
memory reference operations. The bytecode interpreter operates
|
strictly on machine-level values -- various sizes of integers and
|
strictly on machine-level values -- various sizes of integers and
|
floating point numbers -- and requires no information about types or
|
floating point numbers -- and requires no information about types or
|
symbols; thus, the interpreter's internal data structures are simple,
|
symbols; thus, the interpreter's internal data structures are simple,
|
and each bytecode requires only a few native machine instructions to
|
and each bytecode requires only a few native machine instructions to
|
implement it. The interpreter is small, and strict limits on the
|
implement it. The interpreter is small, and strict limits on the
|
memory and time required to evaluate an expression are easy to
|
memory and time required to evaluate an expression are easy to
|
determine, making it suitable for use by the debugging agent in
|
determine, making it suitable for use by the debugging agent in
|
real-time applications.
|
real-time applications.
|
|
|
* Menu:
|
* Menu:
|
|
|
* General Bytecode Design:: Overview of the interpreter.
|
* General Bytecode Design:: Overview of the interpreter.
|
* Bytecode Descriptions:: What each one does.
|
* Bytecode Descriptions:: What each one does.
|
* Using Agent Expressions:: How agent expressions fit into the big picture.
|
* Using Agent Expressions:: How agent expressions fit into the big picture.
|
* Varying Target Capabilities:: How to discover what the target can do.
|
* Varying Target Capabilities:: How to discover what the target can do.
|
* Tracing on Symmetrix:: Special info for implementation on EMC's
|
* Tracing on Symmetrix:: Special info for implementation on EMC's
|
boxes.
|
boxes.
|
* Rationale:: Why we did it this way.
|
* Rationale:: Why we did it this way.
|
|
|
|
|
File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions
|
File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions
|
|
|
E.1 General Bytecode Design
|
E.1 General Bytecode Design
|
===========================
|
===========================
|
|
|
The agent represents bytecode expressions as an array of bytes. Each
|
The agent represents bytecode expressions as an array of bytes. Each
|
instruction is one byte long (thus the term "bytecode"). Some
|
instruction is one byte long (thus the term "bytecode"). Some
|
instructions are followed by operand bytes; for example, the `goto'
|
instructions are followed by operand bytes; for example, the `goto'
|
instruction is followed by a destination for the jump.
|
instruction is followed by a destination for the jump.
|
|
|
The bytecode interpreter is a stack-based machine; most instructions
|
The bytecode interpreter is a stack-based machine; most instructions
|
pop their operands off the stack, perform some operation, and push the
|
pop their operands off the stack, perform some operation, and push the
|
result back on the stack for the next instruction to consume. Each
|
result back on the stack for the next instruction to consume. Each
|
element of the stack may contain either a integer or a floating point
|
element of the stack may contain either a integer or a floating point
|
value; these values are as many bits wide as the largest integer that
|
value; these values are as many bits wide as the largest integer that
|
can be directly manipulated in the source language. Stack elements
|
can be directly manipulated in the source language. Stack elements
|
carry no record of their type; bytecode could push a value as an
|
carry no record of their type; bytecode could push a value as an
|
integer, then pop it as a floating point value. However, GDB will not
|
integer, then pop it as a floating point value. However, GDB will not
|
generate code which does this. In C, one might define the type of a
|
generate code which does this. In C, one might define the type of a
|
stack element as follows:
|
stack element as follows:
|
union agent_val {
|
union agent_val {
|
LONGEST l;
|
LONGEST l;
|
DOUBLEST d;
|
DOUBLEST d;
|
};
|
};
|
where `LONGEST' and `DOUBLEST' are `typedef' names for the largest
|
where `LONGEST' and `DOUBLEST' are `typedef' names for the largest
|
integer and floating point types on the machine.
|
integer and floating point types on the machine.
|
|
|
By the time the bytecode interpreter reaches the end of the
|
By the time the bytecode interpreter reaches the end of the
|
expression, the value of the expression should be the only value left
|
expression, the value of the expression should be the only value left
|
on the stack. For tracing applications, `trace' bytecodes in the
|
on the stack. For tracing applications, `trace' bytecodes in the
|
expression will have recorded the necessary data, and the value on the
|
expression will have recorded the necessary data, and the value on the
|
stack may be discarded. For other applications, like conditional
|
stack may be discarded. For other applications, like conditional
|
breakpoints, the value may be useful.
|
breakpoints, the value may be useful.
|
|
|
Separate from the stack, the interpreter has two registers:
|
Separate from the stack, the interpreter has two registers:
|
`pc'
|
`pc'
|
The address of the next bytecode to execute.
|
The address of the next bytecode to execute.
|
|
|
`start'
|
`start'
|
The address of the start of the bytecode expression, necessary for
|
The address of the start of the bytecode expression, necessary for
|
interpreting the `goto' and `if_goto' instructions.
|
interpreting the `goto' and `if_goto' instructions.
|
|
|
Neither of these registers is directly visible to the bytecode
|
Neither of these registers is directly visible to the bytecode
|
language itself, but they are useful for defining the meanings of the
|
language itself, but they are useful for defining the meanings of the
|
bytecode operations.
|
bytecode operations.
|
|
|
There are no instructions to perform side effects on the running
|
There are no instructions to perform side effects on the running
|
program, or call the program's functions; we assume that these
|
program, or call the program's functions; we assume that these
|
expressions are only used for unobtrusive debugging, not for patching
|
expressions are only used for unobtrusive debugging, not for patching
|
the running code.
|
the running code.
|
|
|
Most bytecode instructions do not distinguish between the various
|
Most bytecode instructions do not distinguish between the various
|
sizes of values, and operate on full-width values; the upper bits of the
|
sizes of values, and operate on full-width values; the upper bits of the
|
values are simply ignored, since they do not usually make a difference
|
values are simply ignored, since they do not usually make a difference
|
to the value computed. The exceptions to this rule are:
|
to the value computed. The exceptions to this rule are:
|
memory reference instructions (`ref'N)
|
memory reference instructions (`ref'N)
|
There are distinct instructions to fetch different word sizes from
|
There are distinct instructions to fetch different word sizes from
|
memory. Once on the stack, however, the values are treated as
|
memory. Once on the stack, however, the values are treated as
|
full-size integers. They may need to be sign-extended; the `ext'
|
full-size integers. They may need to be sign-extended; the `ext'
|
instruction exists for this purpose.
|
instruction exists for this purpose.
|
|
|
the sign-extension instruction (`ext' N)
|
the sign-extension instruction (`ext' N)
|
These clearly need to know which portion of their operand is to be
|
These clearly need to know which portion of their operand is to be
|
extended to occupy the full length of the word.
|
extended to occupy the full length of the word.
|
|
|
|
|
If the interpreter is unable to evaluate an expression completely for
|
If the interpreter is unable to evaluate an expression completely for
|
some reason (a memory location is inaccessible, or a divisor is zero,
|
some reason (a memory location is inaccessible, or a divisor is zero,
|
for example), we say that interpretation "terminates with an error".
|
for example), we say that interpretation "terminates with an error".
|
This means that the problem is reported back to the interpreter's caller
|
This means that the problem is reported back to the interpreter's caller
|
in some helpful way. In general, code using agent expressions should
|
in some helpful way. In general, code using agent expressions should
|
assume that they may attempt to divide by zero, fetch arbitrary memory
|
assume that they may attempt to divide by zero, fetch arbitrary memory
|
locations, and misbehave in other ways.
|
locations, and misbehave in other ways.
|
|
|
Even complicated C expressions compile to a few bytecode
|
Even complicated C expressions compile to a few bytecode
|
instructions; for example, the expression `x + y * z' would typically
|
instructions; for example, the expression `x + y * z' would typically
|
produce code like the following, assuming that `x' and `y' live in
|
produce code like the following, assuming that `x' and `y' live in
|
registers, and `z' is a global variable holding a 32-bit `int':
|
registers, and `z' is a global variable holding a 32-bit `int':
|
reg 1
|
reg 1
|
reg 2
|
reg 2
|
const32 address of z
|
const32 address of z
|
ref32
|
ref32
|
ext 32
|
ext 32
|
mul
|
mul
|
add
|
add
|
end
|
end
|
|
|
In detail, these mean:
|
In detail, these mean:
|
`reg 1'
|
`reg 1'
|
Push the value of register 1 (presumably holding `x') onto the
|
Push the value of register 1 (presumably holding `x') onto the
|
stack.
|
stack.
|
|
|
`reg 2'
|
`reg 2'
|
Push the value of register 2 (holding `y').
|
Push the value of register 2 (holding `y').
|
|
|
`const32 address of z'
|
`const32 address of z'
|
Push the address of `z' onto the stack.
|
Push the address of `z' onto the stack.
|
|
|
`ref32'
|
`ref32'
|
Fetch a 32-bit word from the address at the top of the stack;
|
Fetch a 32-bit word from the address at the top of the stack;
|
replace the address on the stack with the value. Thus, we replace
|
replace the address on the stack with the value. Thus, we replace
|
the address of `z' with `z''s value.
|
the address of `z' with `z''s value.
|
|
|
`ext 32'
|
`ext 32'
|
Sign-extend the value on the top of the stack from 32 bits to full
|
Sign-extend the value on the top of the stack from 32 bits to full
|
length. This is necessary because `z' is a signed integer.
|
length. This is necessary because `z' is a signed integer.
|
|
|
`mul'
|
`mul'
|
Pop the top two numbers on the stack, multiply them, and push their
|
Pop the top two numbers on the stack, multiply them, and push their
|
product. Now the top of the stack contains the value of the
|
product. Now the top of the stack contains the value of the
|
expression `y * z'.
|
expression `y * z'.
|
|
|
`add'
|
`add'
|
Pop the top two numbers, add them, and push the sum. Now the top
|
Pop the top two numbers, add them, and push the sum. Now the top
|
of the stack contains the value of `x + y * z'.
|
of the stack contains the value of `x + y * z'.
|
|
|
`end'
|
`end'
|
Stop executing; the value left on the stack top is the value to be
|
Stop executing; the value left on the stack top is the value to be
|
recorded.
|
recorded.
|
|
|
|
|
|
|
