gdb: GDB/MI Breakpoint Commands
27.8 GDB/MI Breakpoint Commands
===============================
This section documents GDB/MI commands for manipulating breakpoints.
The '-break-after' Command
--------------------------
Synopsis
........
-break-after NUMBER COUNT
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
'-break-list' command, see the description of the '-break-list' command
below.
GDB Command
...........
The corresponding GDB command is 'ignore'.
Example
.......
(gdb)
-break-insert main
^done,bkpt={number="1",type="breakpoint",disp="keep",
enabled="y",addr="0x000100d0",func="main",file="hello.c",
fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
times="0"}
(gdb)
-break-after 1 3
~
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",thread-groups=["i1"],times="0",ignore="3"}]}
(gdb)
The '-break-commands' Command
-----------------------------
Synopsis
........
-break-commands NUMBER [ COMMAND1 ... COMMANDN ]
Specifies the CLI commands that should be executed when breakpoint
NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands.
If no command is specified, any previously-set commands are cleared.
Break Commands. Typical use of this functionality is tracing a
program, that is, printing of values of some variables whenever
breakpoint is hit and then continuing.
GDB Command
...........
The corresponding GDB command is 'commands'.
Example
.......
(gdb)
-break-insert main
^done,bkpt={number="1",type="breakpoint",disp="keep",
enabled="y",addr="0x000100d0",func="main",file="hello.c",
fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
times="0"}
(gdb)
-break-commands 1 "print v" "continue"
^done
(gdb)
The '-break-condition' Command
------------------------------
Synopsis
........
-break-condition NUMBER EXPR
Breakpoint NUMBER will stop the program only if the condition in EXPR
is true. The condition becomes part of the '-break-list' output (see
the description of the '-break-list' command below).
GDB Command
...........
The corresponding GDB command is 'condition'.
Example
.......
(gdb)
-break-condition 1 1
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"}]}
(gdb)
The '-break-delete' Command
---------------------------
Synopsis
........
-break-delete ( BREAKPOINT )+
Delete the breakpoint(s) whose number(s) are specified in the
argument list. This is obviously reflected in the breakpoint list.
GDB Command
...........
The corresponding GDB command is 'delete'.
Example
.......
(gdb)
-break-delete 1
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="0",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[]}
(gdb)
The '-break-disable' Command
----------------------------
Synopsis
........
-break-disable ( BREAKPOINT )+
Disable the named BREAKPOINT(s). The field 'enabled' in the break
list is now set to 'n' for the named BREAKPOINT(s).
GDB Command
...........
The corresponding GDB command is 'disable'.
Example
.......
(gdb)
-break-disable 2
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",thread-groups=["i1"],times="0"}]}
(gdb)
The '-break-enable' Command
---------------------------
Synopsis
........
-break-enable ( BREAKPOINT )+
Enable (previously disabled) BREAKPOINT(s).
GDB Command
...........
The corresponding GDB command is 'enable'.
Example
.......
(gdb)
-break-enable 2
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",thread-groups=["i1"],times="0"}]}
(gdb)
The '-break-info' Command
-------------------------
Synopsis
........
-break-info BREAKPOINT
Get information about a single breakpoint.
The result is a table of breakpoints. GDB/MI Breakpoint
Information, for details on the format of each breakpoint in the
table.
GDB Command
...........
The corresponding GDB command is 'info break BREAKPOINT'.
Example
.......
N.A.
The '-break-insert' Command
---------------------------
Synopsis
........
-break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
[ -c CONDITION ] [ -i IGNORE-COUNT ]
[ -p THREAD-ID ] [ LOCATION ]
If specified, LOCATION, can be one of:
LINESPEC LOCATION
A linespec location. Linespec Locations.
EXPLICIT LOCATION
An explicit location. GDB/MI explicit locations are analogous to
the CLI's explicit locations using the option names listed below.
Explicit Locations.
'--source FILENAME'
The source file name of the location. This option requires
the use of either '--function' or '--line'.
'--function FUNCTION'
The name of a function or method.
'--label LABEL'
The name of a label.
'--line LINEOFFSET'
An absolute or relative line offset from the start of the
location.
ADDRESS LOCATION
An address location, *ADDRESS. Address Locations.
The possible optional parameters of this command are:
'-t'
Insert a temporary breakpoint.
'-h'
Insert a hardware breakpoint.
'-f'
If LOCATION cannot be parsed (for example if it refers to unknown
files or functions), create a pending breakpoint. Without this
flag, GDB will report an error, and won't create a breakpoint, if
LOCATION cannot be parsed.
'-d'
Create a disabled breakpoint.
'-a'
Create a tracepoint. Tracepoints. When this parameter is
used together with '-h', a fast tracepoint is created.
'-c CONDITION'
Make the breakpoint conditional on CONDITION.
'-i IGNORE-COUNT'
Initialize the IGNORE-COUNT.
'-p THREAD-ID'
Restrict the breakpoint to the thread with the specified global
THREAD-ID.
Result
......
GDB/MI Breakpoint Information, for details on the format of the
resulting breakpoint.
Note: this format is open to change.
GDB Command
...........
The corresponding GDB commands are 'break', 'tbreak', 'hbreak', and
'thbreak'.
Example
.......
(gdb)
-break-insert main
^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",
fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"],
times="0"}
(gdb)
-break-insert -t foo
^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",
fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"],
times="0"}
(gdb)
-break-list
^done,BreakpointTable={nr_rows="2",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x0001072c", func="main",file="recursive2.c",
fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"],
times="0"},
bkpt={number="2",type="breakpoint",disp="del",enabled="y",
addr="0x00010774",func="foo",file="recursive2.c",
fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
times="0"}]}
(gdb)
The '-dprintf-insert' Command
-----------------------------
Synopsis
........
-dprintf-insert [ -t ] [ -f ] [ -d ]
[ -c CONDITION ] [ -i IGNORE-COUNT ]
[ -p THREAD-ID ] [ LOCATION ] [ FORMAT ]
[ ARGUMENT ]
If supplied, LOCATION may be specified the same way as for the
'-break-insert' command. -break-insert.
The possible optional parameters of this command are:
'-t'
Insert a temporary breakpoint.
'-f'
If LOCATION cannot be parsed (for example, if it refers to unknown
files or functions), create a pending breakpoint. Without this
flag, GDB will report an error, and won't create a breakpoint, if
LOCATION cannot be parsed.
'-d'
Create a disabled breakpoint.
'-c CONDITION'
Make the breakpoint conditional on CONDITION.
'-i IGNORE-COUNT'
Set the ignore count of the breakpoint (ignore count
Conditions.) to IGNORE-COUNT.
'-p THREAD-ID'
Restrict the breakpoint to the thread with the specified global
THREAD-ID.
Result
......
GDB/MI Breakpoint Information, for details on the format of the
resulting breakpoint.
GDB Command
...........
The corresponding GDB command is 'dprintf'.
Example
.......
(gdb)
4-dprintf-insert foo "At foo entry\n"
4^done,bkpt={number="1",type="dprintf",disp="keep",enabled="y",
addr="0x000000000040061b",func="foo",file="mi-dprintf.c",
fullname="mi-dprintf.c",line="25",thread-groups=["i1"],
times="0",script={"printf \"At foo entry\\n\"","continue"},
original-location="foo"}
(gdb)
5-dprintf-insert 26 "arg=%d, g=%d\n" arg g
5^done,bkpt={number="2",type="dprintf",disp="keep",enabled="y",
addr="0x000000000040062a",func="foo",file="mi-dprintf.c",
fullname="mi-dprintf.c",line="26",thread-groups=["i1"],
times="0",script={"printf \"arg=%d, g=%d\\n\", arg, g","continue"},
original-location="mi-dprintf.c:26"}
(gdb)
The '-break-list' Command
-------------------------
Synopsis
........
-break-list
Displays the list of inserted breakpoints, showing the following
fields:
'Number'
number of the breakpoint
'Type'
type of the breakpoint: 'breakpoint' or 'watchpoint'
'Disposition'
should the breakpoint be deleted or disabled when it is hit: 'keep'
or 'nokeep'
'Enabled'
is the breakpoint enabled or no: 'y' or 'n'
'Address'
memory location at which the breakpoint is set
'What'
logical location of the breakpoint, expressed by function name,
file name, line number
'Thread-groups'
list of thread groups to which this breakpoint applies
'Times'
number of times the breakpoint has been hit
If there are no breakpoints or watchpoints, the 'BreakpointTable'
'body' field is an empty list.
GDB Command
...........
The corresponding GDB command is 'info break'.
Example
.......
(gdb)
-break-list
^done,BreakpointTable={nr_rows="2",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"],
times="0"},
bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
line="13",thread-groups=["i1"],times="0"}]}
(gdb)
Here's an example of the result when there are no breakpoints:
(gdb)
-break-list
^done,BreakpointTable={nr_rows="0",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[]}
(gdb)
The '-break-passcount' Command
------------------------------
Synopsis
........
-break-passcount TRACEPOINT-NUMBER PASSCOUNT
Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If
the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint,
error is emitted. This corresponds to CLI command 'passcount'.
The '-break-watch' Command
--------------------------
Synopsis
........
-break-watch [ -a | -r ]
Create a watchpoint. With the '-a' option it will create an "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 watchpoint
created is a "read" watchpoint, i.e., it will trigger only when the
memory location is accessed for reading. Without either of the options,
the watchpoint created is a regular watchpoint, i.e., it will trigger
when the memory location is accessed for writing. Setting
Watchpoints Set Watchpoints.
Note that '-break-list' will report a single list of watchpoints and
breakpoints inserted.
GDB Command
...........
The corresponding GDB commands are 'watch', 'awatch', and 'rwatch'.
Example
.......
Setting a watchpoint on a variable in the 'main' function:
(gdb)
-break-watch x
^done,wpt={number="2",exp="x"}
(gdb)
-exec-continue
^running
(gdb)
*stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"},
value={old="-268439212",new="55"},
frame={func="main",args=[],file="recursive2.c",
fullname="/home/foo/bar/recursive2.c",line="5",arch="i386:x86_64"}
(gdb)
Setting a watchpoint on a variable local to a function. GDB will
stop the program execution twice: first for the variable changing value,
then for the watchpoint going out of scope.
(gdb)
-break-watch C
^done,wpt={number="5",exp="C"}
(gdb)
-exec-continue
^running
(gdb)
*stopped,reason="watchpoint-trigger",
wpt={number="5",exp="C"},value={old="-276895068",new="3"},
frame={func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13",
arch="i386:x86_64"}
(gdb)
-exec-continue
^running
(gdb)
*stopped,reason="watchpoint-scope",wpnum="5",
frame={func="callee3",args=[{name="strarg",
value="0x11940 \"A string argument.\""}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",
arch="i386:x86_64"}
(gdb)
Listing breakpoints and watchpoints, at different points in the
program execution. Note that once the watchpoint goes out of scope, it
is deleted.
(gdb)
-break-watch C
^done,wpt={number="2",exp="C"}
(gdb)
-break-list
^done,BreakpointTable={nr_rows="2",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"],
times="1"},
bkpt={number="2",type="watchpoint",disp="keep",
enabled="y",addr="",what="C",thread-groups=["i1"],times="0"}]}
(gdb)
-exec-continue
^running
(gdb)
*stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"},
value={old="-276895068",new="3"},
frame={func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13",
arch="i386:x86_64"}
(gdb)
-break-list
^done,BreakpointTable={nr_rows="2",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"],
times="1"},
bkpt={number="2",type="watchpoint",disp="keep",
enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"}]}
(gdb)
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="2",
frame={func="callee3",args=[{name="strarg",
value="0x11940 \"A string argument.\""}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",
arch="i386:x86_64"}
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
thread-groups=["i1"],times="1"}]}
(gdb)
Info Catalog
gdb: GDB/MI Command Description Format
gdb: GDB/MI
gdb: GDB/MI Catchpoint Commands