### 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",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",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",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",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",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",times="0"}]}
         (gdb)

#### The `-break-info` Command

##### Synopsis

          -break-info breakpoint

Get information about a single breakpoint.

##### 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 ] [ 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.
‘`-c condition`’
  Make the breakpoint conditional on condition.
‘`-i ignore-count`’
  Initialize the ignore-count.
‘`-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.

##### Result

The result is in the form:

         ^done,bkpt={number="number",type="type",disp="del"|"keep",
         enabled="y"|"n",addr="hex",func="funcname",file="filename",
         fullname="full_filename",line="lineno",[thread="threadno,]
         times="times"}

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, lineno is the 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 greater for -break-info or -break-list which use the same output).

Note: this format is open to change.

##### gdb Command

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

##### Example

         (gdb)
         -break-insert main
         ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",
         fullname="/home/foo/recursive2.c,line="4",times="0"}
         (gdb)
         -break-insert -t foo
         ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",
         fullname="/home/foo/recursive2.c,line="11",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",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",times="0"}]}
         (gdb)
         -break-insert -r foo.*
         ~int foo(int, int);
         ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c,
         "fullname="/home/foo/recursive2.c",line="11",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
‘`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",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",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",times="1"},
         bkpt={number="2",type="watchpoint",disp="keep",
         enabled="y",addr="",what="C",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",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",
         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",
         times="1"}]}
         (gdb)