26.8. gdb/mi Breakpoint table commands

This section documents gdb/mi commands for manipulating breakpoints.

26.8.1. The -break-afterCommand

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

26.8.1.2. gdb Command

The corresponding gdb command is ignore.

26.8.1.3. Example

(gdb)
-break-insert main
^done,bkpt={number="1",addr="0x000100d0",file="hello.c",line="5"}
(gdb)
-break-after 1 3
~
^done
(gdb)
-break-list
^done,BreakpointTable={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",line="5",times="0",
ignore="3"}]}
(gdb)

26.8.2. The -break-conditionCommand

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

26.8.2.2. gdb Command

The corresponding gdb command is condition.

26.8.2.3. 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",line="5",cond="1",
times="0",ignore="3"}]}
(gdb)

26.8.3. The -break-deleteCommand

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

26.8.3.2. gdb command

The corresponding gdb command is delete.

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

26.8.4. The -break-disableCommand

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

26.8.4.2. gdb Command

The corresponding gdb command is disable.

26.8.4.3. 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",line="5",times="0"}]}
(gdb)

26.8.5. The -break-enableCommand

26.8.5.1. Synopsis

 -break-enable ( breakpoint )+

Enable (previously disabled) breakpoint(s).

26.8.5.2. gdb Command

The corresponding gdb command is enable.

26.8.5.3. 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",line="5",times="0"}]}
(gdb)

26.8.6. The -break-infoCommand

26.8.6.1. Synopsis

 -break-info breakpoint

Get information about a single breakpoint.

26.8.6.2. gdb command

The corresponding gdb command is info break breakpoint.

26.8.6.3. Example

N.A.

26.8.7. The -break-insertCommand

26.8.7.1. Synopsis

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

If specified, line, can be one of:

  • function

  • filename:linenum

  • filename:function

  • *address

The possible optional parameters of this command are:

-t

Insert a tempoary breakpoint.

-h

Insert a hardware breakpoint.

-c condition

Make the breakpoint conditional on condition.

-i ignore-count

Initialize the ignore-count.

-r

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

26.8.7.2. Result

The result is in the form:

 ^done,bkptno="number",func="funcname",
  file="filename",line="lineno"

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 source file which contains this function, and lineno is the source line number within that file.

Note: this format is open to change.

26.8.7.3. gdb Command

The corresponding gdb commands are break, tbreak, hbreak, thbreak, and rbreak.

26.8.7.4. Example

(gdb)
-break-insert main
^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
(gdb)
-break-insert -t foo
^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",line="11"}
(gdb)
-break-list
^done,BreakpointTable={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",line="4",times="0"},
bkpt={number="2",type="breakpoint",disp="del",enabled="y",
addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"}]}
(gdb)
-break-insert -r foo.*
~int foo(int, int);
^done,bkpt={number="3",addr="0x00010774",file="recursive2.c",line="11"}
(gdb)

26.8.8. The -break-listCommand

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

Times

number of times the breakpoint has been hit

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

26.8.8.2. gdb Command

The corresponding gdb command is info break.

26.8.8.3. 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",times="0"},
bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x00010114",func="foo",file="hello.c",line="13",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)

26.8.9. The -break-watchCommand

26.8.9.1. Synopsis

 -break-watch [ -a | -r ]

Create a watchpoint. With the -a option it will create an access watchpoint, that is, 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, that is, it will trigger only when the memory location is accessed for reading. Without either of the options, the watchpoint created is a regular watchpoint, that is, it will trigger when the memory location is accessed for writing. Refer to Section 7.1.2 Setting watchpoints.

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

26.8.9.2. gdb Command

The corresponding gdb commands are watch, awatch, and rwatch.

26.8.9.3. 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
^done,reason="watchpoint-trigger",wpt={number="2",exp="x"},
value={old="-268439212",new="55"},
frame={func="main",args=[],file="recursive2.c",line="5"}
(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
^done,reason="watchpoint-trigger",
wpt={number="5",exp="C"},value={old="-276895068",new="3"},
frame={func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
(gdb)
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="5",
frame={func="callee3",args=[{name="strarg",
value="0x11940 \"A string argument.\""}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
(gdb)

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",line="8",times="1"},
bkpt={number="2",type="watchpoint",disp="keep",
enabled="y",addr="",what="C",times="0"}]}
(gdb)
-exec-continue
^running
^done,reason="watchpoint-trigger",wpt={number="2",exp="C"},
value={old="-276895068",new="3"},
frame={func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
(gdb)
-break-list
^done,BreakpointTable={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",line="8",times="1"},
bkpt={number="2",type="watchpoint",disp="keep",
enabled="y",addr="",what="C",times="-5"}]}
(gdb)
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="2",
frame={func="callee3",args=[{name="strarg",
value="0x11940 \"A string argument.\""}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
(gdb)
-break-list
^done,BreakpointTable={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",line="8",times="1"}]}
(gdb)