*break-on-signals*

∗break-on-signals∗ Variable

Value Type:

a type specifier .

Initial Value:

nil.

∗break-on-signals∗

Description:

When (typep condition *break-on-signals*) returns true, calls to signal, and to other operators such as error that implicitly call signal, enter the debugger prior to signaling the condition.

The continue restart can be used to continue with the normal signaling process when a break occurs process due to *break-on-signals*.

Examples:

\*break-on-signals\* → NIL 
(ignore-errors (error ’simple-error :format-control "Fooey!")) 
→ NIL, #<SIMPLE-ERROR 32207172> 
(let ((\*break-on-signals\* ’error)) 
  (ignore-errors (error ’simple-error :format-control "Fooey!"))) 
▷ Break: Fooey! 
▷ BREAK entered because of \*BREAK-ON-SIGNALS\*. 
▷ To continue, type :CONTINUE followed by an option number: 
▷ 1: Continue to signal. 
▷ 2: Top level. 
▷ Debug> :CONTINUE 1 
▷ Continue to signal. 
→ NIL, #<SIMPLE-ERROR 32212257> 
(let ((\*break-on-signals\* ’error)) 
  (error ’simple-error :format-control "Fooey!")) 
▷ Break: Fooey! 
▷ BREAK entered because of \*BREAK-ON-SIGNALS\*. 
▷ To continue, type :CONTINUE followed by an option number: 
▷ 1: Continue to signal. 
▷ 2: Top level. 
▷ Debug> :CONTINUE 1 
▷ Continue to signal. 
▷ Error: Fooey! 
▷ To continue, type :CONTINUE followed by an option number: 
▷ 1: Top level. 
▷ Debug> :CONTINUE 1 
▷ Top level. 

See Also:

break, signal, warn, error, typep, Section 9.1 (Condition System Concepts)

Notes:

*break-on-signals* is intended primarily for use in debugging code that does signaling. When setting *break-on-signals*, the user is encouraged to choose the most restrictive specification

that suffices. Setting *break-on-signals* effectively violates the modular handling of condition signaling. In practice, the complete effect of setting *break-on-signals* might be unpredictable in some cases since the user might not be aware of the variety or number of calls to signal that are used in code called only incidentally.

*break-on-signals* enables an early entry to the debugger but such an entry does not preclude an additional entry to the debugger in the case of operations such as error and cerror.

Expanded Reference: *break-on-signals*

Default Value

*break-on-signals* is nil by default, meaning no automatic debugger entry before signaling.

*break-on-signals*

=> NIL

Breaking on All Errors

Setting *break-on-signals* to a type specifier causes the debugger to be entered before signaling any condition matching that type. The continue restart proceeds with normal signaling.

;; (let ((*break-on-signals* 'error))
;;   (ignore-errors (error "test")))
;; => enters debugger BEFORE the error is signaled
;; => after continuing
;; => ignore-errors handles the error normally

Breaking on Warnings

You can use it to debug warning conditions too.

;; (let ((*break-on-signals* 'warning))
;;   (warn "something suspicious"))
=> enters debugger before the warning is signaled

Using a Specific Type

For targeted debugging, set it to a specific condition type.

;; Only break on type-error conditions:
;; (let ((*break-on-signals* 'type-error))
;;   (check-type x integer))

Debugging Tip

Use the most specific type possible. Setting *break-on-signals* to t (matching all conditions) can cause excessive debugger entries because many internal operations signal conditions.

;; Avoid this in production:
;; (setf *break-on-signals* t)  ; too broad
;;
;; Prefer this for targeted debugging:
;; (setf *break-on-signals* 'my-custom-error)