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

linespec location

  A linespec location. See 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. See 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. See 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. 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 thread with the specified global 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 `-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. See -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 (see ignore count) to ignore-count.

‘`-p thread-id`’

  Restrict the breakpoint to the thread with the specified global thread-id.

#### Result

See 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. 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",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)