/errors.62

   1.c This file is part of the Lisp Machine Manual.  -*-Bolio-*-
   2.c Error system.
   3
   4.chapter Errors and Debugging
   5.cindex error system
   6.cindex handling errors
   7.setq error-chapter chapter-number
   8
   9The first section of this chapter explains how programs
  10can handle errors, by means of condition handlers.  It also explains how
  11a program can signal an error if it detects something it doesn't like.
  12
  13The second explains how users can handle errors, by means of an interactive debugger;
  14that is, it explains how to recover if you do something wrong.
  15A new user of the Lisp Machine, or someone who just wants to know how
  16to deal with errors and not how to cause them, should ignore the first
  17section and skip ahead to (debugger).
  18
  19	The remaining sections describe some other debugging facilities.
  20Anyone who is going to be writing programs for the Lisp Machine should
  21familiarize himself with these.
  22
  23	The 2trace* facility provides the ability to perform certain
  24actions at the time a function is called or at the time it returns.  The
  25actions may be simple typeout, or more sophisticated debugging functions.
  26
  27	The 2advise* facility is a somewhat similar facility for modifying
  28the behavior of a function.
  29
  30	The 2step* facility allows the evaluation of a form to be
  31intercepted at every step so that the user may examine just what is happening
  32throughout the execution of the form.
  33
  34	The 2MAR* facility provides the ability to cause a trap
  35on any memory reference to a word (or a set of words) in memory.  If
  36something is getting clobbered by agents unknown, this can help track
  37down the source of the clobberage.
  38
  39.section The Error System
  40
  41.subsection Conditions
  42.cindex conditions
  43.setq condition section-page
  44
  45	Programmers often want to control what action is taken by their
  46programs when errors or other exceptional situations occur.  Usually
  47different situations are handled in different ways, and in order to express
  48what kind of handling each situation should have, each situation
  49must have an associated name.  In Zetalisp there is the
  50concept of a 2condition*.  Every condition has a name, which is a
  51symbol.  When an unusual situation occurs, some condition is 2signalled*, and a
  522handler* for that condition is invoked.
  53
  54	When a condition is signalled, the system (essentially) searches
  55up the stack of nested function invocations looking for a handler
  56established to handle that condition.  The handler is a function which
  57gets called to deal with the condition.  The condition mechanism itself
  58is just a convenient way for finding an appropriate handler function
  59given the name of an exceptional situation.  On top of this is built the
  60error-condition system, which defines what arguments are passed to a
  61handler function and what is done with the values returned by a handler
  62function.  Almost all current use of the condition mechanism is for
  63errors, but the user may find other uses for the underlying mechanism.
  64
  65.need 1000
  66.cindex signaller
  67.cindex signalling conditions
  68The search for an appropriate handler is done by the function 3signal*:
  69
  70.defun signal condition-name &rest args
  713signal* searches through all currently-established condition handlers,
  72starting with the most recent.  If it finds one that will handle
  73the condition 2condition-name*, then it calls that handler with a first argument
  74of 2condition-name*, and with 2args* as the rest of the arguments.
  75If the first value returned by the handler is 3nil*, 3signal*
  76will continue searching for another handler; otherwise,
  77it will return the first two values returned by the handler.
  78If 3signal* doesn't find any handler that returns a non-3nil*
  79value, it will return 3nil*.
  80.end_defun
  81
  82.cindex condition handler
  83.cindex handling conditions
  84
  85Condition handlers are established through the 3condition-bind* special form:
  86
  87.defspec condition-bind
  88The 3condition-bind* special form is used for establishing handlers for conditions.
  89It looks like:
  90.lisp
  91(condition-bind ((2cond-1* 2hand-1*)
  92                 (2cond-2* 2hand-2*)
  93                 ...)
  94  2body*)
  95.end_lisp
  96Each 2cond-n* is either the name of a condition, or a list of names of conditions,
  97or 3nil*.  If it is 3nil*, a handler is set up for 2all* conditions
  98(this does not mean that the handler really has to handle all
  99conditions, but it will be offered the chance to do so, and can return
 1003nil* for conditions which it is not interested in).
 101Each 2hand-n* is a form which is evaluated to produce a handler function.
 102The handlers are established sequentially such that the 2cond-1*
 103handler would be looked at first.
 104.lisp
 105.exdent 96 Example:
 106(condition-bind ((:wrong-type-argument 'my-wta-handler)
 107                 ((lossage-1 lossage-2) lossage-handler))
 108    (princ "Hello there.")
 109    (= t 69))
 110.end_lisp
 111This first sets up the function 3my-wta-handler* to handle
 112the 3:wrong-type-argument* condition.  Then, it sets up the value
 113of the symbol 3lossage-handler* to handle both the 3lossage-1*
 114and 3lossage-2* conditions.  With these handlers set up, it prints out a message and
 115then runs headlong into a wrong-type-argument error by calling the
 116function 3=* with an argument which is not a number.
 117The condition handler 3my-wta-handler* will be given a chance to
 118handle the error.  3condition-bind*
 119makes use of ordinary variable binding, so that if the
 1203condition-bind* form is thrown through, the handlers will be
 121disestablished.  This also means that condition handlers are established
 122only within the current stack-group.
 123.end_defspec
 124
 125.subsection Error Conditions
 126
 127[This section is incorrect.  The mechanism by which errors are
 128signalled does not work.  It will be redesigned someday.]
 129
 130The use of the condition mechanism by the error system defines an
 131additional protocol for what arguments are passed to error-condition
 132handlers and what values they may return.
 133
 134There are basically four possible responses to an error: 2proceeding*,
 1352restarting*, 2throwing*, or entering the 2debugger*.
 136The default action, taken if no handler exists or deigns to handle
 137the error (returns non-3nil*), is to enter the debugger.
 138A handler may give up on the execution that produced the error by
 139throwing (see 3*throw*, (*throw-fun)).  2Proceeding* means to
 140repair the error and continue execution.  The exact meaning of this
 141depends on the particular error, but it generally takes the form of
 142supplying a replacement for an unacceptable argument to some function,
 143and retrying the invocation of that function.  2Restarting* means
 144throwing to a special standard catch-tag, 3error-restart*.  Handlers
 145cause proceeding and restarting by returning certain special values,
 146described below.
 147
 148	Each error condition is signalled with some parameters, the meanings of which
 149depend on the condition.  For example, the condition 3:unbound-variable*,
 150which means that something tried to find the value of a symbol which was unbound,
 151is signalled with at least one parameter, the unbound symbol.  It is always
 152all right to signal an error condition with extra parameters beyond those whose
 153meanings are defined by the condition.
 154
 155	An error condition handler is applied to several arguments.  The first
 156argument is the name of the condition that was signalled (a symbol).
 157This allows the same function to handle several different conditions,
 158which is useful if the handling of those conditions is very similar.
 159(The first argument is also the name of the condition for non-error conditions.)
 160The second argument is a 3format* control string (see the description
 161of 3format*, on (format-fun)).  The third argument
 162is 3t* if the error is 2proceedable*; otherwise it is 3nil*.  The
 163fourth argument is 3t* if the error is 2restartable*; otherwise it
 164is 3nil*.
 165The fifth argument is the name of the function that signalled the
 166error, or 3nil* if the signaller can't figure out the correct name to pass.
 167The rest of the arguments are the parameters with which the condition was signalled.
 168If the 3format* control string is used with these parameters,
 169a readable English message should be produced.  Since more
 170information than just the parameters might be needed to print a reasonable
 171message, the program signalling the condition is free to pass any extra
 172parameters it wants to, after the parameters which the condition is 2defined*
 173to take.  This means that every handler must expect to be called
 174with an arbitrarily high number of arguments, so every handler should
 175have a 3&rest* argument (see (&rest)).
 176
 177	An error condition handler may return any of several values.  If it
 178returns 3nil*, then it is stating that it does not wish to handle
 179the condition after all; the process of signalling will continue
 180looking for a prior handler (established farther down on the stack) as
 181if the handler which returned 3nil* had not existed at all.
 182(This is also true for non-error conditions.)
 183If the handler does wish to handle the condition, it can try to
 184proceed from the error if it is proceedable, or restart from it if it
 185is restartable, or it can throw to a catch tag.
 186Proceeding and restarting are done by returning two values.  The first value
 187is one of the following symbols:
 188.table 3
 189.item :return
 190If the error was signalled by calling 3cerror*, the second value is returned
 191as the value of 3cerror*.  If the error was signalled by calling 3ferror*,
 192proceeding is not allowed.  If the error was detected by the Lisp system, the
 193error will be proceeded from, using the second value if a data object is needed.
 194For example, for an 3:undefined-function* error, the handler's second value will
 195be used as the function to be called, in place of the non-existent function definition.
 196
 197.item eh:return-value
 198If the error was signalled by calling 3ferror* or 3cerror*, the second value
 199is returned from that function, regardless of whether the error was proceedable.
 200If the error was detected by the Lisp system, the second value is returned as the
 201result of the function in which the error was detected.  It should be obvious
 202that 3:return-value* allows you to do things that are totally unanticipated by
 203the program that got the error.
 204
 205.item :error-restart
 206The second value is thrown to the catch tag 3error-restart*.
 207.end_table
 208The condition handler must not return any other sort of values.  However,
 209it can legitimately throw to any tag instead of returning at all.
 210If a handler tries to proceed an unproceedable error or
 211restart an unrestartable one, an error is signalled.
 212
 213	Note that if the handler returns 3nil*, it is not said to have
 214handled the error; rather, it has decided not to handle it, but to "continue to signal"
 215it so that someone else may handle it.  If an error is signalled
 216and none of the handlers for the condition decide to handle it, the
 217debugger is entered.
 218
 219	Here is an example of an excessively simple handler for the 3:wrong-type-argument*
 220condition.
 221
 222[Note that this code does not work in system 56.]
 223
 224.lisp
 225;;; This function handles the :wrong-type-argument condition,
 226;;; which takes two defined parameters: a symbol indicating
 227;;; the correct type, and the bad value.
 228(defun sample-wta-handler (condition control-string
 229			   proceedable-flag restartable-flag
 230			   function correct-type bad-value
 231			   &rest rest)
 232 (prog ()
 233   (format error-output "~%There was an error in ~S~%" function)
 234   (lexpr-funcall (function format) error-output
 235		  control-string correct-type bad-value rest)
 236   (cond ((and proceedable-flag
 237	       (yes-or-no-p "Do you want use nil instead?"))
 238	  (return 'return nil))
 239	 (t (return nil))))) ;don't handle
 240.end_lisp
 241
 242If an error condition reaches the error handler, the 3RESUME* (or control-C) command may be
 243used to continue from it.  If the condition name has a 3eh:proceed* property,
 244that property is called as a function with two arguments, the stack-group and
 245the "ete" (an internal error-handler data structure).  Usually it will ignore
 246these arguments.  If this function returns, its value will be returned from the
 2473ferror* or 3cerror* that signalled the condition.  If no such property
 248exists, the error-handler asks the user for a form, evaluates it, and causes
 2493ferror* or 3cerror* to return that value.  Putting such a property on can
 250be used to change the prompt for this form, avoid asking the user, or change
 251things in more far-reaching ways.
 252
 253.subsection Signalling Errors
 254.cindex signalling errors
 255
 256	Some error conditions are signalled by the Lisp system when it detects
 257that something has gone wrong.  Lisp programs can also signal errors,
 258by using any of the functions 3ferror*, 3cerror*, or 3error*.
 2593ferror* is the most commonly used of these.  3cerror* is used
 260if the signaller of the error wishes to make the error be 2proceedable*
 261or 2restartable*, or both.  3error* is provided for Maclisp compatibility.
 262
 263	A 3ferror* or 3cerror* that doesn't have any particular
 264condition to signal should use 3nil* as the condition name.  The
 265only kind of handler that will be invoked by the signaller in this case is the kind
 266that handles 2all* conditions, such as is set up by
 267.lisp
 268(condition-bind ((nil 2something*) ...) ...)
 269.end_lisp
 270In practice, the 3nil* condition is used a great deal.
 271.cindex nil, used as a condition name
 272
 273.defun ferror condition-name control-string &rest params
 2743ferror* signals the error condition 2condition-name*.  The associated error
 275message is obtained by calling 3format* (see (format)) on 2control-string*
 276and 2params*.  The error is neither proceedable nor restartable, so 3ferror*
 277will not return unless the user forces it to by intervening with the debugger.
 278In most cases 2condition-name* is 3nil*, which means that no condition-handler
 279is likely to be found and the debugger will be entered.
 280
 281.lisp
 282.exdent 96 Examples:
 283(cond ((> sz 60)
 284       (ferror nil
 285	       "The size, ~S, was greater than the maximum"
 286	       sz))
 287      (t (foo sz)))
 288
 289(defun func (a b)
 290   (cond ((and (> a 3) (not (symbolp b)))
 291          (ferror ':wrong-type-argument
 292                  "The name, ~1G~S, must be a symbol"
 293                  'symbolp
 294                  b))
 295         (t (func-internal a b))))
 296.end_lisp
 297
 298If the error is not handled and the debugger is entered, the error message is printed by
 299calling 3format* with 2control-string* as the control string and the elements of
 3002params* as the additional arguments.  Alternatively, the formatted output functions
 301((format:outfmt-fun)) can be used to generate the error message:
 302
 303.lisp
 304(ferror nil
 305  (format:outfmt "Frob has "
 306		 (format:plural (format:onum n-elts)
 307				" element")
 308		 " which is too few"))
 309.end_lisp
 310In this case 2params* are not used for printing the error message, and often none are
 311needed.  They may still be useful as information for condition handlers, and those that a
 312condition is documented to expect should always be supplied.
 313.end_defun
 314
 315.defun cerror proceedable-flag restartable-flag condition-name control-string &rest params
 3163cerror* is just like 3ferror* (see above) except for
 3172proceedable-flag* and 2restartable-flag*.  If 3cerror* is called with a
 318non-3nil* 2proceedable-flag*, the caller should be prepared
 319to accept the returned value of 3cerror* and use it to retry the
 320operation that failed.  Similarly, if he passes 3cerror* a non-3nil* 2restartable-flag*,
 321he should be sure that there is a 3*catch* above him for the tag 3error-restart*.
 322
 323If 2proceedable-flag* is 3t* and the error goes to the debugger, if the
 324user says to proceed from the error he will be asked for a replacement object
 325which 3cerror* will return.  If 2proceedable-flag* is not 3t* and not
 3263nil*, the user will not be asked for a replacement object and 3cerror*
 327will return no particular value when the error is proceeded.
 328
 329Note:  Many programs that want to signal restartable errors will want to use
 330the 3error-restart* special form; see (error-restart-fun).
 331.lisp
 332.exdent 96 Example:
 333(do ()
 334    ((symbolp a))
 335  1; Do this stuff until *a1 becomes a symbol.*
 336  (setq a (cerror t nil ':wrong-type-argument
 337	   "The argument ~2G~A was ~1G~S, which is not ~3G~A"
 338	   'symbolp a 'a "a symbol")))
 339.end_lisp
 340Note: the form in this example is so useful that there is a standard
 341special form to do it, called 3check-arg* (see (check-arg-fun)).
 342.end_defun
 343
 344.defun error message &optional object interrupt
 3453error* is provided for Maclisp compatibility.  In Maclisp,
 346the functionality of 3error* is, essentially, that 2message*
 347gets printed, preceeded by 2object* if present, and that
 3482interrupt*, if present, is a user interrupt channel to be invoked.
 349
 350	In order to fit this definition into Zetalisp way of handling
 351errors, 3error* is defined to be:
 352.lisp
 353(cerror (not (null 2interrupt*))
 354        nil
 355        (or (get 2interrupt* 'eh:condition-name)
 356            2interrupt*)
 357        (if (missing? 2object*) ;1If no 3object* given*
 358	    "~*~A"
 359	    "~S ~A")
 360        2object*
 361        2message*)
 362.end_lisp
 363
 364	Here is what that means in English: first of all, the condition
 365to be signalled is 3nil* if 2interrupt* is 3nil*.  If there is some
 366condition whose meaning is close to that of one of the Maclisp user interrupt
 367channels, the name of that channel has an 3eh:condition-name* property,
 368and the value of that property is the name of the condition to signal.
 369Otherwise, 2interrupt* is the name of the condition to signal; probably
 370there will be no handler and the debugger will be entered.
 371
 372	If 2interrupt* is specified, the error will be proceedable.
 373The error will not be restartable.  The 3format* control string
 374and the arguments are chosen so that the right error message gets printed,
 375and the handler is passed everything there is to pass.
 376.end_defun
 377
 378.defmac error-restart body...
 3793error-restart* is useful for denoting a section of a program
 380that can be restarted if certain errors occur during its execution.
 381The forms of the body are evaluated sequentially.  If an error occurs
 382within the evaluation of the body and is restarted (by a condition handler
 383or the debugger), the evaluation resumes at the beginning of the 3error-restart*'s
 384body.  The only way a restartable error can occur is if 3cerror* is called
 385with a second argument of 3t*.
 386.lisp
 3871Example:*
 388(error-restart
 389  (setq a (* b d))
 390  (cond ((> a maxtemp)
 391         (cerror nil t 'overheat
 392	    "The frammistat will overheat by ~D. degrees!"
 393	    (- a maxtemp))))
 394  (setq q (cons a a)))
 395.end_lisp
 396If the 3cerror* happens, and the handler invoked (or the debugger) restarts
 397the error, then evaluation will continue with the 3(setq a (* b d))*,
 398and the condition 3(> a maxtemp)* will get checked again.
 399
 400.lisp
 40113error-restart* is implemented as a macro that expands into:*
 402(prog ()
 403 loop (*catch 'error-restart
 404              (return (progn
 405                         2form-1*
 406                         2form-2*
 407                         2...*)))
 408      (go loop))
 409.end_lisp
 410.end_defmac
 411
 412.defmac check-arg var-name predicate description [type-symbol]
 413'cindex argument checking
 414The 3check-arg* form is useful for checking arguments
 415to make sure that they are valid.  A simple example is:
 416.lisp
 417(check-arg foo stringp "a string")
 418.end_lisp
 4193foo* is the name of an argument whose value should be a string.
 4203stringp* is a predicate of one argument, which returns 3t*
 421if the argument is a string.  3"a string"* is an English description
 422of the correct type for the variable.
 423
 424The general form of 3check-arg* is
 425.lisp
 426(check-arg 2var-name*
 427           2predicate*
 428           2description*
 429	   2type-symbol*)
 430.end_lisp
 4312var-name* is the name of the variable
 432whose value is of the wrong type.  If the error is proceeded this variable will
 433be 3setq*'ed to a replacement value.  2predicate* is a test for whether the
 434variable is of the correct type.  It can be either a symbol whose function definition
 435takes one argument and returns non-3nil* if the type is correct, or it can be a non-atomic
 436form which is evaluated to check the type, and presumably contains a reference to
 437the variable 2var-name*.  2description* is a string which expresses 2predicate*
 438in English, to be used in error messages.  2type-symbol* is a symbol which
 439is used by condition handlers to determine what type of argument was expected.
 440It may be omitted if it is to be the same as 2predicate*, which must be a symbol
 441in that case.
 442
 443The use of the 2type-symbol* is not really well-defined yet, but the intention
 444is that if it is 3numberp* (for example), the
 445condition handlers can tell that a number was needed, and might try to
 446convert the actual supplied value to a number and proceed.
 447
 448[We need to establish a conventional way of "registering" the
 449type-symbols to be used for various expected types.  It might as well
 450be in the form of a table right here.]
 451
 452The 2predicate* is usually a symbol such as 3fixp*, 3stringp*,
 4533listp*, or 3closurep*, but when there isn't any convenient predefined
 454predicate, or when the condition is complex, it can be a form.  In this case
 455you should supply a 2type-symbol* which encodes the type.  For example:
 456.lisp
 457(check-arg a
 458           (and (numberp a) ( a 10.) (> a 0.))
 459           "a number from one to ten"
 460           one-to-ten)
 461.end_lisp
 462If this error got to the debugger, the message
 463.lisp
 464The argument a was 17, which is not a number from one to ten.
 465.end_lisp
 466would be printed.
 467
 468In general, what constitutes a valid argument is specified in three
 469ways in a 3check-arg*.  2description* is human-understandable,
 4702type-symbol* is program-understandable, and 2predicate* is
 471executable.  It is up to the user to ensure that these three
 472specifications agree.
 473
 4743check-arg* uses 2predicate* to determine
 475whether the value of the variable is of the correct type.  If it is not,
 4763check-arg* signals the 3:wrong-type-argument* condition, with four
 477parameters.  First, 2type-symbol* if it was supplied, or else 2predicate*
 478if it was atomic, or else 3nil*.  Second, the bad value.
 479Third, the name of the argument (2var-name*).
 480Fourth, a string describing the proper type (2description*).
 481If the error is proceeded, the variable is set to the value returned,
 482and 3check-arg* starts over, checking the type again.
 483Note that only the first two of these parameters are defined for
 484the 3:wrong-type-argument* condition, and so 3:wrong-type-argument*
 485handlers should only depend on the meaning of these two.
 486.end_defmac
 487
 488.defmac check-arg-type var-name type-name [description]
 489This is a useful variant of the 3check-arg* form.  A simple example
 490is:
 491.lisp
 492(check-arg foo :number)
 493.end_lisp
 4943foo* is the name of an argument whose value should be a number.
 4953:number* is a value which is passed as a second argument to 3typep*
 496(see (typep-fun)); that is, it is a symbol that specifies a data type.
 497The English form of the type name, which gets put into the error message,
 498is found automatically.
 499
 500The general form of 3check-arg-type* is:
 501.lisp
 502(check-arg-type 2var-name*
 503                2type-name*
 504                2description*)
 505.end_lisp
 5062var-name* is the name of the variable whose value is of the wrong
 507type.  If the error is proceeded this variable will be 3setq*'ed to a
 508replacement value.  2type-name* describes the type which the
 509variable's value ought to have.  It can be exactly those things
 510acceptable as the second argument to 3typep*.  2description* is a
 511string which expresses 2predicate* in English, to be used in error
 512messages.  It is optional.  If it is omitted, and 2type-name* is one
 513of the keywords accepted by 3:typep*, which describes a basic Lisp
 514data type, then the right 2description* will be provided correctly.
 515If it is omitted and 2type-name* describes some other data type, then
 516the description will be the word "a" followed by the printed
 517representation of 2type-name* in lower-case.
 518.end_defmac
 519
 520.subsection Standard Condition Names
 521
 522	Some condition names are used by the kernel Lisp system, and are
 523documented below; since they are of global interest, they are on
 524the keyword package.  Programs outside the kernel system are free
 525to define their own condition names; it is intended that the
 526description of a function include a description of any conditions
 527that it may signal, so that people writing programs that call
 528that function may handle the condition if they desire.  When you
 529decide what package your condition names should be in, you should
 530apply the same criteria you would apply for determining which package
 531a function name should be in; if a program
 532defines its own condition names, they should 2not* be on the
 533keyword package. For example, the condition names 3chaos:bad-packet-format*
 534and 3arpa:bad-packet-format* should be distinct.  For further
 535discussion, see (package).
 536
 537	The following table lists all standard conditions and the
 538parameters they take; more will be added in the future.
 539These are all error-conditions, so in addition to the condition name
 540and the parameters, the handler receives the other arguments described above.
 541
 542.table 3
 543.item :wrong-type-argument  2type-name*  2value*
 5442value* is the offending argument, and 2type-name* is
 545a symbol for what type is required.  Often, 2type-name*
 546is a predicate which returns non-3nil* if applied to an acceptable value.
 547If the error is proceeded, the value returned by the handler
 548should be a new value for the argument to be used instead of
 549the one which was of the wrong type.
 550
 551.item :inconsistent-arguments  2list-of-inconsistent-argument-values*
 552These arguments were inconsistent with each other, but the fault
 553does not belong to any particular one of them.
 554This is a catch-all, and it would be good to identify subcases
 555in which a more specific categorization can be made.
 556If the error is proceeded, the value returned by the
 557handler will be returned by the function whose arguments were inconsistent.
 558
 559.item :wrong-number-of-arguments  2function*  2number-of-args-supplied*  2list-of-args-supplied*
 5602function* was invoked with the wrong number of arguments.
 561The elements of 2list-of-args-supplied* have already been evaluated.
 562If the error is proceeded, the value returned should be
 563a value to be returned by 2function*.
 564
 565.item :invalid-function  2function-name*
 566The name had a function definition but it was no good for calling.
 567You can proceed, supplying a value to return as the value of the
 568call to the function.
 569
 570.item :invalid-form  2form*
 571The so-called 2form* was not a meaningful form for 3eval*.
 572Probably it was of a bad data type.
 573If the error is proceeded, the value returned
 574should be a new form; 3eval* will use it instead.
 575
 576.item :undefined-function  2function-name*
 577The symbol 2function-name* was not defined as a function.
 578If the error is proceeded, then the value returned will be used instead
 579of the (non-existent) definition of 2function-name*.
 580
 581.item :unbound-variable  2variable-name*
 582The symbol 2variable-name* had no value.
 583If the error is proceeded, then the value returned will be used instead
 584of the (non-existent) value of 2variable-name*.
 585.end_table
 586
 587.subsection "Errset"
 588
 589As in Maclisp, there is an 3errset* facility which allows a very simple
 590form of error handling.  If an error occurs inside an errset, and no condition
 591handler handles it, i.e. the debugger would be entered, control is
 592returned (2thrown*) to the errset.  The errset can control whether or
 593not the debugger's error message is printed.  All errors are caught by
 5943errset*, whether they are signalled by 3ferror*, 3cerror*, 3error*,
 595or the Lisp system itself.
 596
 597	A problem with 3errset* is that it is 2too* powerful;
 598it will apply to any unhandled error at all.  If you are writing code
 599that anticipates some specific error, you should find out what condition
 600that error signals and set up a handler.  If you use 3errset* and
 601some unanticipated error crops up, you may not be told--this can cause
 602very strange bugs.  Note that the variable 3errset* allows all 3errset*s
 603to be disabled for debugging purposes.
 604
 605.defspec errset form [flag]
 606The 3errset* special form catches errors during
 607the evaluation of 2form*.  If an error occurs, the usual error message
 608is printed unless 2flag* is 3nil*.  Then control is thrown and the errset-form
 609returns 3nil*.  2flag* is evaluated first and is optional, defaulting to 3t*.
 610If no error occurs, the value of the errset-form is a list of one element,
 611the value of 2form*.
 612.end_defspec
 613
 614.defspec catch-error form [flag]
 6153catch-error* is a variant of 3errset*.  This special form
 616catches errors during the evaluation of
 6172form*, and returns two values.  Normally the first value is the value of
 6182form* and the second value is 3nil*.  If an error occurs, the usual
 619error message is printed unless 2flag* is 3nil*, and then control is thrown
 620out of the 3catch-error* form, which returns two values: first 3nil* and second a
 621non-3nil* value that indicates the occurrence of an error.  2flag* is
 622evaluated first and is optional, defaulting to 3t*.
 623.end_defspec
 624
 625.defvar errset
 626If this variable is non-3nil*, 3errset* forms are not allowed to trap errors.
 627The debugger is entered just as if there were no errset.  This is intended mainly
 628for debugging.  The initial value of 3errset* is 3nil*.
 629.end_defvar
 630
 631.defspec err
 632This is for Maclisp compatibility only and should not be used.
 633
 6343(err)* is a dumb way to cause an error.  If executed inside an errset,
 635that errset returns 3nil*, and no message is printed.
 636Otherwise an unseen throw-tag error occurs.
 637
 6383(err 2form*)* evaluates 2form* and causes the containing errset
 639to return the result.  If executed when not inside an errset, an unseen
 640throw-tag error occurs.
 641
 6423(err 2form* 2flag*)*, which exists in Maclisp, is not supported.
 643.end_defspec
 644
 645.section The Debugger
 646.cindex debugger
 647.setq debugger section-page
 648
 649	When an error condition is signalled and no handlers decide to
 650handle the error, an interactive debugger is entered to allow the user to
 651look around and see what went wrong, and to help him continue the program
 652or abort it.  This section describes how to use the debugger.
 653
 654.subsection Entering the Debugger
 655
 656	There are two kinds of errors; those generated by the Lisp Machine's
 657microcode, and those generated by Lisp programs (by using 3ferror* or
 658related functions).  When there
 659is a microcode error, the debugger prints out a message such as the following:
 660.lisp
 661>>TRAP 5543 (TRANS-TRAP)
 662The symbol FOOBAR is unbound.
 663While in the function *EVAL  SI:LISP-TOP-LEVEL1
 664.end_lisp
 665
 666	The first line of this error message indicates entry to
 667the debugger and contains some mysterious internal microcode information:
 668the micro program address, the microcode trap name and parameters, and a microcode backtrace.
 669Users can ignore this line in most cases.  The second line contains a description
 670of the error in English.  The third line indicates where the error
 671happened by printing a very abbreviated "backtrace" of the stack (see
 672below); in the example, it is saying that the error was signalled inside the
 673function 3*eval*, which was called by 3si:lisp-top-level1*.
 674
 675	Here is an example of an error from Lisp code:
 676.lisp
 677>>ERROR: The argument X was 1, which is not a symbol,
 678While in the function FOO  *EVAL  SI:LISP-TOP-LEVEL1
 679.end_lisp
 680
 681	Here the first line contains the English description of the
 682error message, and the second line contains the abbreviated backtrace.
 6833foo* signalled the error by calling 3ferror*, however 3ferror*
 684is censored out of the backtrace.
 685
 686	After the debugger's initial message it prints the function that
 687got the error and its arguments.
 688
 689	The debugger can be manually entered either by causing an error
 690(e.g. by typing a ridiculous symbol name such as 3ahsdgf* at the Lisp
 691read-eval-print loop) or by typing the 3BREAK* key with the 3META* shift
 692held down while the program is reading from the terminal.  Typing the 3BREAK*
 693key with both 3CONTROL* and 3META* held down will force the program
 694into the debugger immediately, even if it is running.  If the 3BREAK*
 695key is typed without 3META*, it puts you into a read-eval-print loop
 696using the 3break* function (see (break-fun)) rather into the debugger.
 697
 698.defun eh process
 699Stops 2process* and calls the debugger on it so that you can look at its
 700current state.  Exit the debugger with the Control-Z command and 3eh*
 701will release the process and return.  2process* can be a window, in which
 702case the window's process will be used.
 703
 704If 2process* is not a process but a stack group, the current state of the
 705stack group will be examined.  The caller should ensure that no one tries
 706to resume that stack group while the debugger is looking at it.
 707.end_defun
 708
 709.subsection How to Use the Debugger
 710
 711	Once inside the debugger, the user may give a wide variety
 712of commands.  This section describes how to give the commands, and then
 713explains them in approximate order of usefulness.  A summary is provided
 714at the end of the listing.
 715
 716	When the error hander is waiting for a command, it prompts
 717with an arrow:
 718
 719.lisp
 720
 721.end_lisp
 722
 723At this point, you may either type in a Lisp expression, or type a
 724command (a Control or Meta character is interpreted as a command,
 725whereas most normal characters are interpreted as the first character of
 726an expression).  If you type the 3HELP* key or the 3?* key, you will
 727get some introductory help with the error handler.
 728
 729If you type a Lisp expression, it will be interpreted as a Lisp form,
 730and will be evaluated in the context of the function which got the
 731error.  That is, all bindings which were in effect at the time of the
 732error will be in effect when your form is evaluated, with certain
 733exceptions explained below.  The result of the evaluation will be
 734printed, and the debugger will prompt again with an arrow.  If, during
 735the typing of the form, you change your mind and want to get back to the
 736debugger's command level, type the 3ABORT* key or a Control-G; the debugger will respond
 737with an arrow prompt.  In fact, at any time that typein is expected from
 738you, while you are in the debugger, you may type 3ABORT* or Control-G to flush
 739what you are doing and get back to command level.  This
 7403read-eval-print* loop maintains the values of 3+*, 3**, and
 7413-* just as the top-level one does.
 742
 743If an error occurs in the evaluation of the Lisp expression you type,
 744you will get into a second error handler looking at the new error.  You
 745can abort the computation and get back to the first error by typing the
 7463ABORT* key (see below).  However, if the error is trivial the abort
 747will be done automatically and the original error message will be reprinted.
 748
 749Various debugger commands ask for Lisp objects, such as an
 750object to return, or the name of a catch-tag.  Whenever it tries to get
 751a Lisp object from you, it expects you to type in a 2form*; it will
 752evaluate what you type in.  This provides greater generality, since
 753there are objects to which you might want to refer that cannot be
 754typed in (such as arrays).  If the form you type is non-trivial (not
 755just a constant form), the debugger will show you the result of
 756the evaluation, and ask you if it is what you intended.  It expects a Y
 757or N answer (see the function 3y-or-n-p*, (y-or-n-p-fun)), and if you answer negatively
 758it will ask you for another form.  To quit out of the command, just type
 7593ABORT* or Control-G.
 760
 761When the debugger evaluates a form, the variable bindings at the point of error
 762are in effect with the following exceptions:
 763
 7643terminal-io* is rebound to the stream the error handler is using.  3eh:old-terminal-io*
 765is bound to the value 3terminal-io* had at the point of error.
 766
 7673standard-input* and 3standard-output* are rebound to be synonymous with
 7683terminal-io*; their old bindings are saved in 3eh:old-standard-input*
 769and 3eh:old-standard-output*.
 770
 7713+* and 3** are rebound to the error handler's previous form and previous value.
 772When the debugger is first entered, 3+* is the last form typed, which is typically
 773the one that caused the error, and 3** is the value of the 2previous* form.
 774
 7753evalhook* (see (evalhook-var)) is rebound to 3nil*, turning off
 776the 3step* facility if it had been in use when the error occurred.
 777
 778Note that the variable bindings are those in effect at the point of
 779error, 2not* those of the current frame being looked at.  This may be
 780changed in the future.
 781
 782.subsection "Debugger Commands"
 783
 784All debugger commands are single characters, usually with the Control or
 785Meta bits.  The single most useful command is 3ABORT* (or Control-Z),
 786which exits from the debugger and throws out of the computation that got
 787the error.  This is the 3ABORT* key, not a 5-letter command.  ITS
 788users should note that Control-Z is not 3CALL*.  Often you are not
 789interested in using the debugger at all and just want to get back to
 790Lisp top level; so you can do this in one character.  
 791
 792The 3ABORT* command returns control to the most recent read-eval-print loop.
 793This can be Lisp top level, a 3break*, or the debugger command loop
 794associated with another error.  Typing 3ABORT* multiple times will throw
 795back to successively older read-eval-print or command loops until top level
 796is reached.  Typing Control-Meta-3ABORT*, on the other hand, will always throw
 797to top level.  Control-Meta-3ABORT* is not a debugger command, but a system
 798command which is always available no matter what program you are in.
 799
 800Note that typing 3ABORT* in the middle of typing a form to be evaluated
 801by the debugger aborts that form, and returns to the debugger's command level,
 802while typing 3ABORT* as a debugger command returns out of the debugger
 803and the erring program, to the 2previous* command level.
 804
 805Self-documentation is provided by the 3HELP* or 3?* command,
 806which types out some documentation on the debugger commands, including any
 807special commands which apply to the particular error currently being handled.
 808
 809Often you want to try to proceed from the error.  To do this,
 810use the 3RESUME* (or Control-C) command.  The exact way 3RESUME* works depends on
 811the kind of error that happened.  For some errors, there is no standard
 812way to proceed at all, and 3RESUME* will just tell you this and
 813return to the debugger's command level.  For the very common "unbound variable" error,
 814it will get a Lisp object from you, which will be used in place of the (nonexistent) value
 815of the symbol.  For unbound-variable or undefined-function
 816errors, you can also just type Lisp forms to set the variable or define
 817the function, and then type 3RESUME*; it will proceed without asking
 818anything.
 819
 820The debugger knows about a "current stack frame", and there
 821are several commands which use it.  The initially "current" stack frame
 822is the one which signalled the error; either the one which got the microcode-detected
 823error, or the one which called 3ferror*, 3cerror*, or 3error*.
 824When the debugger starts it up it shows you this frame in the following format:
 825.lisp
 826FOO:
 827   Arg 0 (X): 13
 828   Arg 1 (Y): 1
 829.end_lisp
 830and so on.  This means that 3foo* was called
 831with two arguments, whose names (in the Lisp source code) are 3x* and 3y*.
 832The current values of 3x* and 3y* are 313* and 31* respectively.  These
 833may not be the original arguments if 3foo* happens to 3setq* its argument variables.
 834
 835The 3CLEAR-SCREEN* (or Control-L) command clears the screen, retypes
 836the error message that was initially printed when the debugger was
 837entered, and then prints out a description of the current frame, in the
 838above format.
 839
 840Several commands are provided to allow you to examine the Lisp control
 841stack and to make other frames current than the one which got the error.
 842The control stack (or "regular pdl") keeps a record of all functions which are currently
 843active.  If you call 3foo* at Lisp's top level, and it calls 3bar*,
 844which in turn calls 3baz*, and 3baz* gets an error, then a
 845backtrace (a backwards trace of the stack) would show all of this
 846information.  The debugger has two backtrace commands.  Control-B
 847simply prints out the names of the functions on the stack; in the above
 848example it would print
 849.lisp
 850BAZ  BAR  FOO  SI:*EVAL  SI:LISP-TOP-LEVEL1  SI:LISP-TOP-LEVEL
 851.end_lisp
 852The arrows indicate the direction of calling.  The Meta-B command prints
 853a more extensive backtrace, indicating the names of the arguments to the functions
 854and their current values; for the example above it might look like:
 855.lisp
 856BAZ:
 857   Arg 0 (X): 13
 858   Arg 1 (Y): 1
 859
 860BAR:
 861   Arg 0 (ADDEND): 13
 862
 863FOO:
 864   Arg 0 (FROB): (A B C . D)
 865.end_lisp
 866and so on.
 867
 868The Control-N command moves "down" to the "next" frame (that is, it
 869changes the current frame to be the frame which called it), and prints
 870out the frame in this same format.  Control-P moves "up" to the
 871"previous" frame (the one which this one called), and prints out the
 872frame in the same format.  Meta-< moves to the top of the stack, and
 873Meta-> to the bottom; both print out the new current frame.  Control-S
 874asks you for a string, and searches the stack for a frame whose
 875executing function's name contains that string.  That frame becomes
 876current and is printed out.  These commands are easy to remember since
 877they are analogous to editor commands.
 878
 879Meta-L prints out the current frame in "full screen" format, which shows
 880the arguments and their values, the local variables and their values,
 881and the machine code with an arrow pointing to the next instruction to
 882be executed.  Refer to (understanding-compiled-code) for help in reading
 883this machine code.
 884
 885Meta-N moves to the next frame and prints it out in
 886full-screen format, and Meta-P moves to the previous frame and prints it
 887out in full-screen format.  Meta-S is like Control-S but does a
 888full-screen display.
 889
 890Commands such as Control-N and Meta-N, which are meaningful to repeat,
 891take a prefix numeric argument and repeat that many types.  The numeric argument
 892is typed by using Control- or Meta- and the number keys, as in the editor.
 893
 894Control-E puts you into the editor, looking at the source code for the
 895function in the current frame.  This is useful when you have found a function
 896which caused the error and needs to be fixed.  The editor command Control-Z
 897will return to the error handler, if it is still there.
 898
 899Meta-C is similar to Control-C, but in the case of an unbound variable or undefined
 900function, actually 3setq*s the variable or defines the function, so that the error
 901will not happen again.  Control-C (or 3RESUME*) provides a replacement value
 902but does not actually change the variable.
 903
 904Control-R is used to return a value from the current frame; the frame
 905that called that frame continues running as if the function of the current frame
 906had returned.  This command prompts you for a form, which it will evaluate;
 907it returns the resulting value, possibly after confirming it with you.
 908
 909The Control-T command does a 3*throw* to a given tag with a given value; you
 910are prompted for the tag and the value.
 911
 912Control-Meta-R is a variation of Control-R; it starts the current frame over with
 913the same function and arguments.  If the function has been redefined in the meantime
 914(perhaps you edited it and fixed its bug) the new definition is used.  Control-Meta-R
 915asks for confirmation before doing it.
 916
 917The Control-Meta-N, Control-Meta-P, and Control-Meta-B commands are like the
 918corresponding Control- commands but don't censor the stack.  When running interpreted
 919code, the error handler tries to skip over frames that belong to functions of
 920the interpreter, such as 3*eval*, 3prog*, and 3cond*, and only show
 921"interesting" functions.  The Control-Meta-U command goes up the stack
 922to the next interesting function, and makes that the current frame.
 923
 924Control-Meta-A takes a numeric argument 2n*, and prints out
 925the value of the 2n*th argument of the current frame.  It leaves 3**
 926set to the value of the argument, so that you can use the Lisp 3read-eval-print*
 927loop to examine it.  It also leaves 3+* set to a locative pointing to the
 928argument on the stack, so that you can change that argument (by calling
 9293rplacd* on the locative).  Control-Meta-L is similar,
 930but refers to the 2n*th local variable of the frame.  Control-Meta-F is similar
 931but refers to the function executing in the frame; it ignores its numeric argument
 932and doesn't allow you to change the function.
 933
 934Control-Meta-W calls the window error handler, a display-oriented debugger which
 935is not documented in this manual.  It should, however, be usable without further
 936documentation.
 937
 938.subsection "Summary of Commands"
 939
 940.table 1 0 1500
 941.item Control-A
 942Print argument list of function in current frame.
 943.item Control-Meta-A
 944Examine or change the 2n*th argument of the current frame.
 945.item Control-B
 946Print brief backtrace.
 947.item Meta-B
 948Print longer backtrace.
 949.item Control-Meta-B
 950Print longer backtrace with no censoring of interpreter functions.
 951.item Control-C or 3RESUME*
 952Attempt to continue.
 953.item Meta-C
 954Attempt to continue, 3setq*ing the unbound variable or otherwise
 955"permanently" fixing the error.
 956.item Control-Meta-C
 957Attempt to restart (see the 3error-restart* special form, (error-restart-fun)).
 958.item Control-E
 959Edit the source code for the function in the current frame.
 960.item Control-Meta-F
 961Set 3** to the function in the current frame.
 962.item Control-G or ABORT
 963Quit to command level.  This is not a command, but something you can type to escape from
 964typing in a form.
 965.item Control-L or 3CLEAR SCREEN*
 966Redisplay error message and current frame.
 967.item Meta-L
 968Full-screen typeout of current frame.
 969.item Control-Meta-L
 970Get local variable 2n*.
 971.item Control-N or 3LINE*
 972Move to next frame.  With argument, move down 2n* frames.
 973.item Meta-N
 974Move to next frame with full-screen typeout.  With argument, move down 2n* frames.
 975.item Control-Meta-N
 976Move to next frame even if it is "uninteresting".  With argument, move down 2n* frames.
 977.item Control-P or 3RETURN*
 978Move to previous frame.  With argument, move up 2n* frames.
 979.item Meta-P
 980Move to previous frame with full-screen typeout.  With argument, move up 2n* frames.
 981.item Control-Meta-N
 982Move to previous frame even if it is "uninteresting".  With argument, move up 2n* frames.
 983.item Control-R
 984Return a value from the current frame.
 985.item Meta-R
 986Return multiple values from the current frame (doesn't work currently).
 987.item Control-Meta-R
 988Reinvoke the function in the current frame (throw back to it and start it over
 989at its beginning.)
 990.item Control-S
 991Search for a frame containing a specified function.
 992.item Meta-S
 993Same as control-S but does a full display.
 994.item Control-T
 995Throw a value to a tag.
 996.item Control-Meta-U
 997Move up the stack to the previous "interesting" frame.
 998.item Control-Meta-W
 999Call the window error handler.
1000.item Control-Z or 3ABORT*
1001Abort the computation and throw back to the most recent
10023break* or debugger, to the program's "command level",
1003or to Lisp top level.
1004.item ? or Help
1005Print a help message.
1006.item Meta-<
1007Go to top of stack.
1008.item Meta->
1009Go to bottom of stack.
1010.item Control-0 through Control-Meta-9
1011Numeric arguments to the following command are specified by typing a decimal number
1012with Control and/or Meta held down.
1013.end_table