:break

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. Breakpoint options, described below, are displayed in the output.

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

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 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.

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

The options are :slide, :set, :inside, :not-inside, :include-process, :exclude-process, :start-debug, :end-debug, and :trace. These options may take arguments.

:slide

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.

:set

This option sets a breakpoint based on the current slide-point. See the description of the :slide top-level command.

:language language-name

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 function-or-list
:not-inside function-or-list

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.

:include-process process
:exclude-process process

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.

:start-debug

The breakpoint being set is marked as a :start-debug breakpoint, which means it will not stop like other breakpoints do, but it will cause the thread being stopped at to be marked as being debugged. This means that the garbage collector will walk the stack in a conservative manner, which also means that variable slots in the stack which have died but which still have valid Lisp values in them will continue to be forwarded, so as to allow the user to see local variables even after they have just died.

:end-debug

The breakpoint being set is not stopped at, but signals to the debugger to revert the current thread back to not being debugged (i.e. back to precise-gc).

:trace

Instead of stopping, the breakpoint will be printed out.

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-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 10.0 page.
Created 2019.8.20.