ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0

## 1.0 Errors

Errors in Allegro CL are handled by the condition system as described in the ANSI spec. Note too that some errors in Allegro CL are still classified as simple-errors when they should be classified otherwise.

The errorset macro is preserved from earlier versions of Allegro CL although its functionality is completely superceded by the condition system. It is maintained for backward compatibility and its use in newly written code is not recommended.

Here is the condition type hierarchy. Allegro CL has some additional error types defined. They are marked with an *. You can get the condition object associated with an error with the top-level command :error, which, besides printing the error message sets the value of * to the condition object.

      condition
      advance-warning *
      input-edit *
      ics-dependent-classa *
      ics-dependent-classb *
      compiler-note *
      serious-condition
        storage-condition
        error
          type-error
            case-failure *
            simple-type-error
          stream-error
            stream-closed-error *
            end-of-file
            reader-error (also subclass of parse-error)
            socket-error *
            errno-stream-error *
          parse-error
            reader-error (also subclass of stream-error)
          operating-system-signal *
            synchronous-operating-system-signal *
            asynchronous-operating-system-signal *
              interrupt-signal *
          package-error
            package-locked-error *
          file-error
            file-does-not-exist-error *
              autoload-file-does-not-exist-error *
          cell-error
            damaged-system-constant-error
            unbound-slot
            unbound-variable
            undefined-function
          print-not-readable
          arithmetic-error
            floating-point-inexact
            floating-point-invalid-operation
            floating-point-underflow [see note after table]
            floating-point-overflow
            division-by-zero
          compiler-not-available-error *
          program-error
          control-error
          simple-error
          socket-error *
          syscall-error *
          winapi-error *
      simple-break
        break-condition *
      warning
        compiler-not-available-warning *
        incompatible-conformance-change-warning *
        simple-warning
        style-warning
          ineffective-declaration-warning *
          compiler-undefined-functions-called-warning *
          compiler-no-in-package-warning *
          compiler-unreachable-code-warning *
          compiler-inconsistent-name-usage-warning *
      simple-condition
        simple-type-error
        simple-error
        simple-break *
        simple-warning

### Table Notes

`floating-point-underflow` is not usually signaled because most operating systems silently replace an underflow with zero without further action.

### 1.1 More on cl:stream-error

The stream-error class, as implemented in Allegro CL, has these slots:

- `stream`: the stream which got the error. This is the standard CL slot and is accessed by stream-error-stream.
- `action`: the action that was being attempted at the time of the error, accessed by stream-error-action.
- `code`: the errno code returned from the system, nil if none. Accessed by stream-error-code.
- `identifier`: symbolic identification of the code, or nil if unknown. Accessed by stream-error-identifier.

With the new stream-error conditions and slots, Allegro CL classifies stream error situations when possible, relying on a catch-all condition to hold errno returns that could not be classified. A user might want to do handler-binds on the condition subclasses, or on the stream-error condition and then test the identifier slot. All stream conditions have such an identifier slot, but some conditions (especially the catch-all errno-stream-error condition) may not fill it in.

In particular, when a system operation returns an errno value, it is looked up to see if it is a socket-error, and if so, a socket-error condition is created. It is intended then that other errno classifications will be tried. If no classification can be made, then an errno-stream-error condition is created. Its identifier slot is set to `:unknown`, but an attempt is made to find out from the operating system what the string for such an error is, and that is stored into the condition in the string slot, for easier human identification.

## 2.0 Some common errors

We list here some common error messages. This list is by no means exhaustive and we only give a brief description of the likely cause. Error messages start with Error:, but we leave that out here. Names (of functions, symbols, etc.) that appear in error messages are replaced with [name] or some other generic placeholder.

### 2.1 An unhandled error occurred during initialization:

This is printed when an error occurs while Lisp was running through its startup procedure. [message] is the error message generated by the actual error. The startup fails as a result of the error. Assuming the startup procedure has not been changed, these cannot be the cause of this error:

- Reading an initialization (.clinit.cl, clinit.cl or the sys:siteinit.cl) file. If an error reading one of these files is encountered, the error is reported and further reading of the file is aborted, but otherwise the error is ignored.
- Inability to find a loaded .so/.sl/.dll file. A warning but no error is signaled if the file cannot be found. Note that an error might be caused if a foreign function whose code resides in the missing .so file is called during startup.
- A problem with *restart-init-function* or *restart-app-function*. These functions are called outside the handler which prints the An unhandled error ... message.

These may be the cause:

- An error evaluating a `-e [form]` command-line argument. Try to start without the `-e` arguments.
- An error performing the *restart-actions*. Try to start with the following on the command line (it suppresses any restart actions). Be sure to wrap the parentheses with ' marks or other shell-specific quotation-like marks. `-e (setq excl:restart-actions nil)`
- An error evaluating the form that is the value of the ACL_STARTUP_HOOK environment variable. Try restarting after unsetenv'ing that variable.<

### 2.2 Attempt to call -name- which is defined as a macro

Code calling [name] was compiled before [name] was defined as a macro is the cause.

    user(1): (defun foo () (bar) 10)
    foo
    user(2): (compile *)
    Warning: While compiling these undefined functions were referenced: bar.
    foo
    nil
    nil
    user(3): (defmacro bar nil nil)
    bar
    user(4): (foo)
    Error: Attempt to call bar which is defined as a macro.
       [condition type: undefined-function]
    [1] user(5):

The example above shows the definitions typed to the top-level, but this error is most commonly caused when files are compiled in the wrong order.

### 2.3 Gc errors

See gc-errors in gc.html where these errors are discussed.

### 2.4 Bus errors and segmentation violations

Bus errors and segmentation violations are standard OS errors. They are not specific to Lisp. Typically, a bus error is caused by an attempt to write to read-only memory while a segmentation violation is an attempt to access memory that does not exist. You may see them signaled in Lisp, usually when an error is signaled from code compiled at high speed and low safety (so standard Lisp error checkers are not used). If you see such an error, try recompiling code at higher safety and lower speed (in particular, make trust-declarations-switch return `nil`) and see whether the error persists.

### 2.5 Using package [package] results in name conflicts...

Suppose you try to call a function in a currently-unused package but forget the package qualifier. For example, suppose you called process-run-function without the `mp:` and the multiprocessing package is not used. You get an error about process-run-function not having a function definition (as expected). Then you use the multiprocessing package by evaluating `(use-package :mp)`. The following error will be signaled:

    Error: Using package `MULTIPROCESSING' results in name conflicts for these
    symbols: PROCESS-RUN-FUNCTION [condition type: PACKAGE-ERROR]
    Restart actions (select using :continue):
      0: Unintern the conflicting symbols from the `COMMON-LISP-USER' package.
      [...]

In order for `process-run-function` typed without a package qualifier to be process-run-function, enter

    :continue 0

See the top-level command :continue.

## 3.0 Type errors in sequence functions: fastseq and safeseq

Many Common Lisp sequence function are sensitive to the type of their arguments. Consider the following incorrect forms:

    (make-list nil)  ;; argument should be an integer. NIL is illegal
    (elt #(1 2 3) nil) ;; second argument should be an integer.
                       ;; NIL is illegal
    (mapcar #'alpha-char-p "N ")  ;; second argument should be a list
                                  ;; not a string

In each case, the argument given is wrong, but not unreasonable, and a programmer could carelessly but understandably make the errors shown (indeed, all these errors come from our support files). But note they reached our support files because the result (in earlier releases of Allegro CL) of evaluating the erroneous form was more serious than expected: rather than simply signaling an error, Lisp would in some cases enter an infinite loop and have to be interrupted.

In safe code, sequence functions such as the ones above should check that their arguments are of the correct type and signal a type error if they are not. But there is always a price to pay for argument checking: it consumes machine cycles in every call to a function in order to weed out erroneous code.

Allegro CL has two sequence function modules: `:safeseq` and `:fastseq`. Either two can be require'd at any time, and they each cancel the effect of the other. These modules hold the safe or fast run-time definitions of several problematic sequence functions that are hard to decide how to balance between safety and speed.

Thus, to use safe sequence functions, evaluate at any time:

    (require :safeseq)

And to use fast (but without argument checking) sequence functions, evaluate at any time:

    (require :fastseq)

It should be noted that functions in the `:safeseq` module are not better per se than those in `:fastseq`, and for correct code each module's functions operate correctly. Rather, the functions in `:safeseq` behave better with improper arguments.

The current list of functions which are affected by these modules include (but are not limited to, possibly by indirection): elt, length, make-list, mapc, mapcar, mapcon, mapl, butlast, and nbutlast.

In development images, the module loaded by default in `:safeseq`. In production images (when the runtime argument to generate-application is non-`nil`, the default is `:fastseq`.

Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0