### 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. See 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. See 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:

- function
- filename:linenum
- filename:function
- *address

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. See 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 specified thread-id.

##### Result

See 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 `-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. See Setting 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"}
         (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"}
         (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"}
         (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"}
         (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"}
         (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)