Top-level CommandToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
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

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 can be

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

Location specification

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 psoition, or a record number. The full specification is:

   <function-name> [:pc | :pos | :rec] number

:pc for offest from the program counter; :pos for checrater 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.

Other options: :slide, :set, :inside, :not-inside, :language


This option doesn't actually set the breakpoint, but sets a slide point instead. Sliding is a method for navigating around the soure 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.

:inside, :not-inside

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.

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-2015, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 10.0. The object described on this page has been modified in the 10.0 release; see the Release Notes.
Created 2015.5.21.

Allegro CL version 10.0
Object described on page has changed in 10.0.
9.0 version