/errors.62
Unknown | 1013 lines | 886 code | 127 blank | 0 comment | 0 complexity | ff661982a828c84062f507a7d9e278a1 MD5 | raw file
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