Primitive Exceptions

Whenever a primitive error occurs in MzScheme, an exception is raised. The value that is passed to the current exception handler is always an instance of the exn structure type. Every exn structure value has a message field that is a string, the primitive error message. The default exception handler recognizes exception values with the exn? predicate and passes the error message to the current error display handler (see error-display-handler in section 9.4.1.9).

Primitive errors do not create immediate instances of the exn structure type. Instead, an instance from a hierarchy of subtypes of exn is instantiated. The subtype more precisely identifies the error that occurred and may contain additional information about the error. The table below defines the type hierarchy that is used by primitive errors and matches each subtype with the primitive errors that instantiate it.

In the table, each bulleted line is a separate structure type. A type is nested under another when it is a subtype. The full name of the structure type (as used by predicates and selectors in the global environment) is built by combining the full name of the immediate supertype with ``:'' and the subtype name.

For example, applying a procedure to the wrong number of arguments raises an exception as an instance of exn:application:arity. An exception handler can test for this kind of excpetion using the global exn:application:arity? predicate. Given such an exception, the (incorrect) number of arguments provided is obtained from the exception with exn:application-value, while exn:application:arity-expected accesses the actual arity of the procedure.

   exn : not instantiated directly 
            fields: message -- error message (type: string) 
                    debug-info -- value returned by the current debug info handler (called immediately after the error is detected) (type: anything) 
         user : raised by calling error 
         syntax : all syntax errors, but not read errors 
                  fields: expr -- illegal expression (or #f if unknown) (type: S-expression) 
         variable : unbound global variable at run-time 
                  fields: id -- the unbound variable's global identifier (type: identifier) 
         application : not instantiated directly 
                  fields: value -- the error-specific inappropriate value (type: error-specific) 
               non-procedure : application of a non-procedure 
               arity : application with the wrong number of arguments 
                        fields: expected -- the correct procedure arity as returned by arity (type: arity) 
               type : wrong argument type to a procedure, not including divide-by-zero or platform-specific integer range errors 
                        fields: expected -- name of the expected type (type: symbol) 
               range : not instantiated directly 
                     bounds : not instantiated directly 
                              fields: min -- minimum legal index (type: integer) 
                                      max -- maximum legal index (type: integer) 
                           vector : illegal vector index; raised by vector-ref, vector-set! 
                           string : illegal string index; raised by string-ref, string-set!, substring 
                           struct : illegal struct index; raised by struct-ref 
                     list : illegal list index; raised by list-ref, list-tail 
               list-sizes : mismatched list sizes; raised by map, for-each, make-struct-case 
               map-arity : arity of supplied procedure does not match the number of lists provided to map, for-each, andmap, ormap 
                        fields: provided -- the number of lists provided for mapping (type: non-negative integer) 
               integer : integer out of machine-specific range; raised by make-semaphore, set-thread-weight!, seconds->date 
               list : encountered a non-pair in a value expected to be a proper list, or a non-pair item in a value expected to be an association list; raised by member, memv, memq, assoc, assv, assq 
               math : not instantiated directly 
                     zero : divide by zero, etc.; raised by /, quotient, remainder, modulo, angle; application-value is always zero 
                     infinity : infinity overflows; never raised by MzScheme 
                     negative : illegal negative input (e.g. sqrt); never raised by MzScheme 
                     radix : unsupported radix (positive fixnum); raised by number->string 
               mode-conflict : incompatible mode flags; raised by open-output-file, call-with-output-file, with-output-to-file 
                        fields: filename -- filename being opened (type: string) 
               file-position : position was provided, but the port was not a file port; raised by file-position; application-value is the port 
               fprintf : not instantiated directly 
                     extra-arguments : arguments without corresponding formatting tags; application-value is the format string 
                              fields: extras -- arguments without formatting tags (type: list of values) 
                     no-argument : formatting tags without corresponding arguments; application-value is the format string 
                     argument-type : argument does not match type expected by formatting tag; application-value is the bad value 
                              fields: expected -- type expected by formatting tag (type: symbol) 
               macos-typestring : string is not a four-character string, so it does not specify a MacOS application signature or file type; raised by system, execute, send-event 
         else : fall-through in cond or case 
         struct : not instantiated directly 
               struct-type : the supertype expression in a struct form returned a value that was not a structure type value 
                        fields: value -- the given supertype value (type: anything except structure type) 
         object : not instantiated directly 
               class-type : the superclass expression in class* returned a non-class 
                        fields: value -- the value provided as a superclass (type: anything except class) 
               interface-type : an interface expression in class* or scmfirstinterface returned a non-interface 
                        fields: value -- the value provided as an interface (type: anything except interface) 
               generic : the object was not an instance of the generic's class or interface; raised by generic procedures 
                        fields: object -- the object (type: object) 
               inherit : inherited ivar not found; raised by class* 
                        fields: ivar -- instance variable name (type: identifier) 
               implement : ivar required by an interface not found in the implementation; raised by class* 
                        fields: ivar -- instance variable name (type: identifier) 
               class-ivar : instance variable not found in class; raised by uq-make-generic 
                        fields: class -- the class (type: class) 
                                ivar -- instance variable name (type: identifier) 
               interface-ivar : instance variable not found in interface; raised by uq-make-generic 
                        fields: interface -- the interface (type: interface) 
                                ivar -- instance variable name (type: identifier) 
               ivar : instance variable not found; raised by uq-ivar 
                        fields: object -- the object (type: object) 
                                ivar -- instance variable name (type: identifier) 
               private-class : cannot instantiate or derive from this primitive class; raised by make-object, class* 
                        fields: class -- the class (type: class) 
               init : not instantiated directly 
                        fields: object -- the object (type: object) 
                                class -- the class that called a superclass initializer too much or not enough (type: class) 
                     multiple : the superclass intialization proc (e.g., super-init) called twice for the class 
                     never : the superclass intialization proc (e.g., super-init) never called for the class 
         unit : not instantiated directly 
               non-unit : attempt to link a non-unit; raised by compound-unit, invoke-unit, invoke-open-unit 
                        fields: value -- non-unit value (type: anything) 
               arity : attempt to link a unit with the wrong number of imported variables; raised by compound-unit 
                        fields: unit -- badly linked unit (type: unit) 
               import : cannot find variable to import; raised by compound-unit 
                        fields: in-unit -- importing unit (type: unit) 
                                out-unit -- source unit (type: unit) 
                                in-tag -- importing unit tag (type: identifier) 
                                out-tag -- source unit tag (type: identifier) 
                                name -- import variable name (type: identifier) 
               export : cannot find variable to export for compound unit; raised by compound-unit 
                        fields: unit -- source unit (type: unit) 
                                tag -- source unit tag (type: identifier) 
                                name -- source variable name (type: identifier) 
               invoke : not instantiated directly 
                     variable : cannot invoke with import of an undefined global variable 
                              fields: name -- bad identifier (type: identifier) 
               signature : not instantiated directly 
                     non-signed-unit : attempt to link a non-signed-unit; raised by compound-unit/sig, invoke-unit/sig, invoke-open-unit/sig 
                              fields: value -- non-signed-unit value (type: anything) 
                     arity : attempt to link signed unit with the wrong number of imported units; raised by compound-unit/sig 
                              fields: unit -- signed-unit (type: signed-unit) 
                     match : not instantiated directly 
                              fields: dest-context -- destination context (type: string) 
                                      src-context -- source context (type: string) 
                                      variable -- mismatch variable name (type: string) 
                           missing : signature mismatch (missing variable) detected by verify-signature-match 
                           extra : signature mismatch (extra variable) detected by verify-signature-match 
                           kind : signature mismatch (mismatched kinds) detected by verify-signature-match 
         read : not instantiated directly 
                  fields: port -- port being read (type: port) 
               paren : unexpected close paren 
               number : bad number syntax 
                        fields: input -- input number string (type: string) 
               char : bad character constant 
                        fields: input -- input character string without #\ (type: string) 
               eof : unexpected end of file 
                        fields: expected -- expected input (type: string) 
               dot : dot at top-level or illegal use of dot; e.g., ( . 1) 
               unsupported : unsupported # tag 
                        fields: input -- input string without # (type: string) 
               vector-length : bad vector size in vector constant 
                        fields: input -- vector length string (type: string) 
               compiled : illegal MzScheme compiled code 
               graph : bad graph syntax 
         i/o : not instantiated directly 
               read : error reading from a port 
                        fields: port -- port with read error (type: input port) 
               write : error writing to a port 
                        fields: port -- port with write error (type: output port) 
               filesystem : not instantiated directly 
                        fields: pathname -- pathname (type: string) 
                     path : bad pathname; raised by all file procedures that take a pathname 
                           username : bad username (Unix only); raised by all file procedures that take a pathname 
                     file : file not found or file operation failed; raised by procedures that operate on files, plus file-or-directory-modify-seconds, file-or-directory-permissions 
                     directory : directory not found or directory operation failed; raised by procedures that operate on directories 
                     rename : rename or copy failed; copy-file, rename-file-or-directory 
                              fields: destination -- pathname (type: string) 
                     collection : collection not found; raised by require-library, require-relative-library 
                     file-exists : cannot overwrite file; raised by open-output-file 
                     link : bad link discovered; raised by simplify-path 
               port-closed : attempt to operate on a closed port; raised by read, write, display, print, char-ready? 
                        fields: port -- port for attempted operation (type: port) 
               user-port : user-defined input port returned a non-character from the character-getting procedure 
                        fields: port -- user-defined input port (type: input port) 
               tcp : TCP errors 
                     connect : tcp-connect low-level failure 
                              fields: address -- address to connect to (type: string) 
                                      port-id -- port to connect to (type: integer) 
                     listen : tcp-listen low-level failure 
                              fields: port-id -- port to listen on (type: integer) 
                     accept : tcp-accept low-level failure 
                              fields: listener -- listener to accept from (type: listener) 
                     listener-closed : listener closed for tcp-accept, tcp-accept-ready?, tcp-stop 
                              fields: listener -- listener that has been closed (type: listener) 
         misc : low-level errors 
               unsupported : unsupported feature 
               user-break : asynchronous thread break 
               out-of-memory : out of memory 
               parameterization : the parameterization branch handler or sharing procedure returned a non-parameterization; raised by thread, make-parameterization-with-sharing 
                        fields: value -- bad value (type: anything except a parameterization) 
               defmacro : macro handler is not a procedure 
                        fields: value -- the given macro handler (type: anything except a procedure) 
               expansion-time : local-expansion-time-value, global-expansion-time-value, local-expand-defmacro, or local-expand-body-expression called at run-time 
               constant : attempt to change a constant global; raised by set!, define, undefine, invoke-open-unit 
                        fields: id -- constant identifier (type: identifier) 
               continuation : attempt to cross a continuation boundary or apply another thread's continuation 
               thread : not instantiated directly 
                     kill : cannot kill the thread; raised by kill-thread 
               semaphore : a semaphore's maximum internal count has been exceeded 
               hash-table : failed hash table lookup 
                        fields: key -- key for failed lookup (type: anything) 
               regexp : all regular expression errors 
               process : error executing an operating system process 
               send-event : error sending an event to another system process 
               dynamic-extension : not instantiated directly 
                        fields: name -- dynamic extension pathname (type: string) 
                     open : cannot open dynamic extension 
                     version : dynamic extension is wrong version 
                     initialize : cannot initialize dynamic extension 
               image : error dumping or restoring an image; raised by write-image-to-file, read-image-from-file 
                        fields: name -- image pathname (type: string)

Primitive procedures that accept a procedure argument with a particular required arity (e.g., call-with-input-file, call/cc) check the argument's arity immediately, raising exn:application:type if the arity is incorrect.

The secure-primitive-exception-types procedure takes no arguments and undefines all of the primitive exception structure type values and constructors, so that all new primitives exception values can only be generated by the system. The structure predicates and selectors are not affected.