Common Lisp the Language, 2nd Edition

Next: Assertions Up: Program Interface to Previous: Program Interface to

## 29.4.1. Signaling Conditions

The functions in this section provide various mechanisms for signaling warnings, breaks, continuable errors, and fatal errors.

[Function]
`error datum &rest arguments`

[This supersedes the description of `error` given in section 24.1.-GLS]

Invokes the signal facility on a condition. If the condition is not handled, `(invoke-debugger condition)` is executed. As a consequence of calling `invoke-debugger`, `error` never directly returns to its caller; the only exit from this function can come by non-local transfer of control in a handler or by use of an interactive debugging command.

If datum is a condition, then that condition is used directly. In this case, it is an error for the list of arguments to be non-empty; that is, `error` must have been called with exactly one argument, the condition.

If datum is a condition type (a class or class name), then the condition used is effectively the result of `(apply #'make-condition datum arguments)`.

If datum is a string, then the condition used is effectively the result of

    (make-condition 'simple-error
                    :format-string datum
                    :format-arguments arguments)

[Function]
`cerror continue-format-string datum &rest arguments`

[This supersedes the description of `cerror` given in section 24.1.-GLS]

The function `cerror` invokes the error facility on a condition. If the condition is not handled, `(invoke-debugger condition)` is executed. While signaling is going on, and while control is in the debugger (if it is reached), it is possible to continue program execution (thereby returning from the call to `cerror`) using the `continue` restart.

If datum is a condition, then that condition is used directly. In this case, the list of arguments need not be empty, but will be used only with the continue-format-string and will not be used to initialize datum.

If datum is a condition type (a class or class name), then the condition used is effectively the result of `(apply #'make-condition datum arguments)`.

If datum is a string, then the condition used is effectively the result of

    (make-condition 'simple-error
                    :format-string datum
                    :format-arguments arguments)

The continue-format-string must be a string. Note that if datum is not a string, then the format arguments used by the continue-format-string will still be the list of arguments (which is in keyword format if datum is a condition type). In this case, some care may be necessary to set up the continue-format-string correctly. The `format` directive `~*`, which ignores and skips over `format` arguments, may be particularly useful in this situation.

The value returned by `cerror` is `nil`.

[Function]
`signal datum &rest arguments`

Invokes the signal facility on a condition. If the condition is not handled, `signal` returns `nil`.

If datum is a condition, then that condition is used directly. In this case, it is an error for the list of arguments to be non-empty; that is, `error` must have been called with exactly one argument, the condition.

If datum is a condition type (a class or class name), then the condition used is effectively the result of `(apply #'make-condition datum arguments)`.

If datum is a string, then the condition used is effectively the result of

    (make-condition 'simple-error
                    :format-string datum
                    :format-arguments arguments)

Note that if `(typep condition *break-on-signals*)` is true, then the debugger will be entered prior to beginning the process of signaling. The `continue` restart function may be used to continue with the signaling process; the restart is associated with the signaled condition as if by use of `with-condition-restarts`. This is true also for all other functions and macros that signal conditions, such as `warn`, `error`, `cerror`, `assert`, and `check-type`.

During the dynamic extent of a call to `signal` with a particular condition, the effect of calling `signal` again on that condition object for a distinct abstract event is not defined. For example, although a handler may resignal a condition in order to allow outer handlers first shot at handling the condition, two distinct asynchronous keyboard events must not signal an the same (`eq`) condition object at the same time.

For further details about signaling and handling, see the discussion of condition handlers in section 29.3.17.

[Variable]
`*break-on-signals*`

This variable is intended primarily for use when the user is debugging programs that do signaling. The value of `*break-on-signals*` should be suitable as a second argument to `typep`, that is, a type or type specifier.

When `(typep condition *break-on-signals*)` is true, then calls to `signal` (and to other advertised functions such as `error` that implicitly call `signal`) will enter the debugger prior to signaling that condition. The `continue` restart may be used to continue with the normal signaling process; the restart is associated with the signaled condition as if by use of `with-condition-restarts`.

Note that `nil` is a valid type specifier. If the value of `*break-on-signals*` is `nil`, then `signal` will never enter the debugger in this implicit manner.

When setting this variable, the user is encouraged to choose the most restrictive specification that suffices. Setting this flag effectively violates the modular handling of condition signaling that this chapter seeks to establish. Its complete effect may be unpredictable in some cases, since the user may not be aware of the variety or number of calls to `signal` that are used in programs called only incidentally.

By default-and certainly in any ``production'' use-the value of this variable should be `nil`, both for reasons of performance and for reasons of modularity and abstraction.

X3J13 voted in March 1989 (BREAK-ON-WARNINGS-OBSOLETE) to remove `*break-on-warnings*` from the language; `*break-on-signals*` offers all the power of `*break-on-warnings*` and more.

Compatibility note: This variable is similar to the Zetalisp variable `trace-conditions` except for the obvious difference that `zl:trace-conditions` takes a type or list of types while `*break-on-signals*` takes a single type specifier.

[There is no loss of generality in Common Lisp because the `or` type specifier may be used to indicate that any of a set of conditions should enter the debugger.-GLS]

Next: Assertions Up: Program Interface to Previous: Program Interface to