:break top-level command

$Revision: 5.0.2.4 $

Arguments: &optional mode &rest mode-values+

This command allows the user to add or delete instruction-level breakpoints and to print out information about the breakpoints currently in use.

Whether or not a breakpoint is effective (that is stops code execution when reached) depends on whether it is installed or uninstalled. An installed breakpoint is one which will cause normal execution to stop and the debugger entered if an attempt is made to execute the instruction at that location. An uninstalled breakpoint will not cause such an interruption of execution. Deleted breakpoints are always uninstalled but otherwise whether breakpoints are or are not installed depends on (as we said just above) whether ldb debugging more is on, see :ldb, or the code being evaluated is within the body of a with-breakpoints-installed form.

The situation is further complicated by the fact that when a breakpoint is hit and stops execution, the debugging mode changes from ldb to ldb-step and breakpoints are then uninstalled. See 12.0 The Lisp DeBug (ldb) stepper in debugging.htm for information on this point.

Again, :break adds or deletes breakpoints from the current breakpoint set. Its arguments are

mode can be

:add, to add breakpoints. mode-values in that case should one or more breakpoint specifications (described just below). Any number of breakpoint specifications can be specified. If none are specified, the command is a no-op, i.e. does nothing.
:del, to delete breakpoints. mode-values in that case should be breakpoint specifications (described just below) for the breakpoints to be deleted (they must have been previously added). Any number of breakpoint specifications can be specified. If none are specified, the command is a no-op, i.e. does nothing.
nil, to delete all breakpoints.

When called with no arguments, :break prints out the current breakpoint set.

A breakpoint specification is made up of a particular pc (program counter, look at the output of cl:disassemble) offset from the beginning of a particular function. A single breakpoint can be specified by

function-name [offset]

where offset defaults to 0. Multiple breakpoints can be specified by simply naming pairs:

foo 10 bar 20

When multiple breakpoints are specified, the offsets are not optional. However, multiple breakpoints within the same function can be specified by eliding all but the first function name; thus

foo 10 20 30

is equivalent to specifying

foo 10 foo 20 foo 30

If the pc offset is not at an exact instruction location the instruction containing that location is selected, and if the instruction or instructions around the desired location are not good stopping points for any reason, the next instruction that can be stopped at is selected, and if instructions are skipped over, they are shown as being skipped.

For example, on an HP:

user(1): :br comp::wfasl-string-symbol
Breakpoint set beyond
                 0: 37de0600 ldo 768(r30),r30
                 4: 6bc239d9 stw r2,-788(0,r30) 
                 8: 6bd13fe1 stw r17,-16(0,r30) 
Adding #<Function wfasl-string-symbol>: 12
                 12: b08037fb addit,<> -3,r4,r0     "number of args"
user(2):

And on an x86:

user(1): :br car 5
Adding #<Function car>: 4
                 4: 83 ec 24 subl    esp,$36
user(2):

See 12.0 The Lisp DeBug (ldb) stepper in debugging.htm for information on ldb stepping. See top_level.htm for more information on top-level commands.

The general documentation description is in introduction.htm. The index is in index.htm.