| Allegro CL version 10.0 Object described on page has changed in 10.0. 9.0 version | ||||||||||
Arguments: &optional mode &rest mode-values
This command allows the user to add or delete breakpoints and to print out information about the breakpoints currently in use.
Called without arguments, this command prints information on what breakpoints are set, if any.
cl-user(131): :break
No breakpoints set
cl-user(132): :break open
Adding #<Function open>: 0
0: 48 81 ec 88 01 subq rsp,$392 ; 49
00 00
cl-user(133): :break
#<Function open>: asm: pc=0 not yet hit
cl-user(134):
Called with arguments, :break sets breakpoints or otherwise manages them.
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 mode is on, see :ldb, or the code being evaluated is within the body of 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 The Lisp DeBug (ldb) stepper in debugging.htm for information on this point.
Again, :break called with arguments adds or deletes breakpoints from the current breakpoint set. Its arguments are mode and mode-values.
mode can be
:add, to add
breakpoints. mode-values in that case should
be 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.A breakpoint specification is made up of a particular pc (program counter, look at the output of 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 leaving out all but the first function name; thus
foo 10 20 30
is equivalent to specifying
foo 10 foo 20 foo 30
In the examples above (like foo 10), the numeric
value (10) is a relative program counter, 10 bytes after the
start of the function foo. You can also specify a character
position, or a record number. The full specification is:
<function-name> [:pc | :pos | :rec] number
:pc for offest from the program counter; :pos for character position; and :rec for record number. The default is :pc, so that is what is used in all examples above. Thus:
:break foo 10
is the same as
:break foo :pc 10
Either will set a breakpoint within function foo which contains program-counter location 10 (the instruction or form may start precisely at 10, or it may start earlier but contain pc 10 as part of it).
:break foo :rec 4
will select the fifth (zero-based) source debug record and set the breakpoint there.
Note: If none of :pc, :rec, or :pos are given and an integer is also not given, then the default is :rec 0:
:br foo
will set the breakpoint to the first record for function foo. It may be at pc 0, and if the language for foo's breakpoints is :asm then the breakpoint will always be at pc location zero (since :asm breakpoint records are manufactured on the fly).
:br foo :pos 12497
will set the breakpoint whose form starts at character-position 12497 in the file. If there are multiple such records, the one which has the lowest level (probably a level 0 record, which lexically appears in the file) is selected. Usually, the form will start with a left paren, and the file position is 0-based (contrast this with the 1-based position indication of emacs, so it might become a bit confusing).
Note: A breakpoint is set as soon as an integer is seen in the :break command, or, if no integer is seen, when the command arguments have been exhausted or a new function name is seen at which time the integer 0 is used). A function name starts a new breakpoint. If some of the above options are specified after an integer is seen, but before the end of the command or a new function, then that option is ignored.
The options are :slide, :set, :inside, :not-inside, and :language. These options may take arguments.
This option doesn't actually set the breakpoint, but sets a slide point instead. Sliding is a method for navigating around the source debug info for a function without actually setting these breakpoints. Contrast this option, which sets the slide point using breakpoint criteria, with the :slide top-level command, which allows the slide point to be moved around using navigation directions.
This option sets a breakpoint based on the current slide-point. See the description of the :slide top-level command.
This option establishes the preferred language for a breakpoint. Breakpoints set within the same command after this option will be of the specified language. The language can currently be :asm, :lisp, or :python (when cl-python is loaded). Other languages may follow.
These are identical in specification and operation
the :inside and :not-inside
option to
trace. These
determine whether the breakpoint is stopped at based on whether there
is or is not a particular enclosing function on the stack. See the
:inside and :not-inside options
in the description of the trace macro. The
argument function-or-list should be a function
name, function object, or a list of those.
These options takes a single argument which designates the process to
include or exclude. Each option can be used multiple times, as long
as the opposite option has not yet been used. If neither of these
options are used, then breakpoints will stop regardless of the process
that is executing that code. If only one process is specified
in :include-process then all others will be
excluded by default.
See The Lisp DeBug (ldb) stepper in debugging.htm for information on ldb stepping. See top-level.htm for more information on top-level commands.
Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
The object described on this page has been modified in the 10.0 release; see the Release Notes.
Created 2019.8.20.
| Allegro CL version 10.0 Object described on page has changed in 10.0. 9.0 version | ||||||||||