PageRenderTime 342ms CodeModel.GetById 24ms RepoModel.GetById 0ms app.codeStats 1ms

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