2 @comment node-name, next, previous, up
6 The SBCL debugger (as the CMUCL debugger it was derived from) has very
7 good support for source-level debugging of compiled code. Although
8 some other debuggers allow access of variables by name, this seems to
9 be the first Lisp debugger that:
14 Tells you when a variable doesn't have a value because it hasn't been
15 initialized yet or has already been deallocated, or
18 Can display the precise source location corresponding to a code
19 location in the debugged program.
23 These features allow the debugging of compiled code to be made almost
24 indistinguishable from interpreted code debugging.
28 * Starting the Debugger::
29 * The Debugger Command Loop::
30 * Controlling Printing in the Debugger::
33 * Source Location Printing::
34 * Debugger Policy Control::
36 * Information Commands::
40 @node Starting the Debugger
41 @comment node-name, next, previous, up
42 @section Starting the Debugger
44 The debugger is an interactive command loop that allows a user to examine
45 the function call stack. The debugger is invoked when:
50 A @code{serious-condition} is signaled, and it is not handled, or
53 @code{error} is called, and the condition it signals is not handled,
57 the debugger is explicitly entered with the Lisp @code{break} or
58 @code{debug} functions.
62 When you enter the TTY debugger, it looks something like this:
65 debugger invoked on a TYPE-ERROR in thread 11184:
66 The value 3 is not of type LIST.
67 restarts (invokable by number or by possibly-abbreviated name):
68 0: [ABORT ] Reduce debugger level (leaving debugger, returning to toplevel).
69 1: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
74 The first group of lines describe what the error was that put us in
75 the debugger. In this case @code{car} was called on @code{3}. After
76 @samp{restarts} is a list of all the ways that we can restart
77 execution after this error. In this case, both options return to
78 top-level. After printing its banner, the debugger prints the current
79 frame and the debugger prompt.
82 @node The Debugger Command Loop
83 @comment node-name, next, previous, up
84 @section The Debugger Command Loop
85 @cindex Evaluation, in the debugger
87 The debugger is an interactive read-eval-print loop much like the normal
88 top-level, but some symbols are interpreted as debugger commands instead
89 of being evaluated. A debugger command starts with the symbol name of
90 the command, possibly followed by some arguments on the same line. Some
91 commands prompt for additional input. Debugger commands can be
92 abbreviated by any unambiguous prefix: @command{help} can be typed as
93 @samp{h}, @samp{he}, etc. For convenience, some commands have
94 ambiguous one-letter abbreviations: @samp{f} for @command{frame}.
95 @comment FIXME: what does that last bit mean?
97 The package is not significant in debugger commands; any symbol with the
98 name of a debugger command will work. If you want to show the value of
99 a variable that happens also to be the name of a debugger command, you
100 can use the @command{list-locals} command or the @code{sb-debug:var}
101 function, or you can wrap the variable in a @code{progn} to hide it from
104 The debugger prompt is ``@code{@var{frame}]}'', where @var{frame} is
105 the number of the current frame. Frames are numbered starting from
106 zero at the top (most recent call), increasing down to the bottom.
107 The current frame is the frame that commands refer to. The current
108 frame also provides the lexical environment for evaluation of
111 The debugger evaluates forms in the lexical environment of the
112 functions being debugged. The debugger can only access variables.
113 You can't @code{go} or @code{return-from} into a function, and you
114 can't call local functions. Special variable references are evaluated
115 with their current value (the innermost binding around the debugger
116 invocation) -- you don't get the value that the special had in the
117 current frame. For more information on debugger variable access, see
118 @ref{Variable Access}.
121 @node Controlling Printing in the Debugger
122 @comment node-name, next, previous, up
123 @section Controlling Printing in the Debugger
125 In the debugger, it is possible to override the printing behaviour of
128 @defvr {Variable} *debug-print-variable-alist*
130 An association list describing new bindings for special variables
131 (typically *PRINT-FOO* variables) to be used within the debugger, e.g.
133 ((*PRINT-LENGTH* . 10) (*PRINT-LEVEL* . 6) (*PRINT-PRETTY* . NIL))
135 The variables in the @code{car} position are bound to the values in
136 the @code{cdr} during the execution of some debug commands. When
137 evaluating arbitrary expressions in the debugger, the normal values of
138 the printer control variables are in effect. @c FIXME: is this correct?
139 @code{*debug-print-variable-alist*} does not contain any bindings
145 @comment node-name, next, previous, up
146 @section Stack Frames
149 A @dfn{stack frame} is the run-time representation of a call to a
150 function; the frame stores the state that a function needs to remember
151 what it is doing. Frames have:
156 @dfn{variables} (@pxref{Variable Access}), which are the values being operated
160 @dfn{arguments} to the call (which are really just particularly
161 interesting variables), and
164 a current location (@pxref{Source Location Printing}), which is the place in
165 the program where the function was running when it stopped to call
166 another function, or because of an interrupt or error.
173 * How Arguments are Printed::
176 * Debug Tail Recursion::
177 * Unknown Locations and Interrupts::
181 @comment node-name, next, previous, up
182 @subsection Stack Motion
184 These commands move to a new stack frame and print the name of the
185 function and the values of its arguments in the style of a Lisp
188 @deffn {Debugger Command} up
189 Move up to the next higher frame. More recent function calls are
190 considered to be higher on the stack.
193 @deffn {Debugger Command} down
194 Move down to the next lower frame.
197 @deffn {Debugger Command} top
198 Move to the highest frame, that is, the frame where the debugger was
202 @deffn {Debugger Command} bottom
203 Move to the lowest frame.
206 @deffn {Debugger Command} frame [@var{n}]
207 Move to the frame with the specified number. Prompts for the number if not
208 supplied. The frame with number 0 is the frame where the debugger
213 @node How Arguments are Printed
214 @comment node-name, next, previous, up
215 @subsection How Arguments are Printed
217 A frame is printed to look like a function call, but with the actual
218 argument values in the argument positions. So the frame for this call
225 would look like this:
231 All keyword and optional arguments are displayed with their actual
232 values; if the corresponding argument was not supplied, the value will
233 be the default. So this call:
239 would look like this:
248 (string-upcase "test case")
251 would look like this:
254 (STRING-UPCASE "test case" :START 0 :END NIL)
257 The arguments to a function call are displayed by accessing the
258 argument variables. Although those variables are initialized to the
259 actual argument values, they can be set inside the function; in this
260 case the new value will be displayed.
262 @code{&rest} arguments are handled somewhat differently. The value of
263 the rest argument variable is displayed as the spread-out arguments to
267 (format t "~A is a ~A." "This" 'test)
270 would look like this:
273 (FORMAT T "~A is a ~A." "This" 'TEST)
276 Rest arguments cause an exception to the normal display of keyword
277 arguments in functions that have both @code{&rest} and @code{&key}
278 arguments. In this case, the keyword argument variables are not
279 displayed at all; the rest arg is displayed instead. So for these
280 functions, only the keywords actually supplied will be shown, and the
281 values displayed will be the argument values, not values of the
282 (possibly modified) variables.
284 If the variable for an argument is never referenced by the function,
285 it will be deleted. The variable value is then unavailable, so the
286 debugger prints @samp{#<unused-arg>} instead of the value. Similarly,
287 if for any of a number of reasons the value of the variable is
288 unavailable or not known to be available (@pxref{Variable Access}),
289 then @samp{#<unavailable-arg>} will be printed instead of the argument
292 @vindex *debug-print-variable-alist*
293 Printing of argument values is controlled by
294 @code{*debug-print-variable-alist*}. @xref{Controlling Printing in
299 @comment node-name, next, previous, up
300 @subsection Function Names
302 If a function is defined by @code{defun}, @code{labels}, or
303 @code{flet}, then the debugger will print the actual function name
304 after the open parenthesis, like:
307 (STRING-UPCASE "test case" :START 0 :END NIL)
308 ((SETF AREF) #\a "for" 1)
311 Otherwise, the function name is a string, and will be printed in
316 ("DEFMACRO DO" (DO ((I 0 (1+ I))) ((= I 13))) NIL)
317 ("SETQ *GC-NOTIFY-BEFORE*")
320 This string name is derived from the @code{def@var{mumble}} form
321 that encloses or expanded into the lambda, or the outermost enclosing
322 form if there is no @code{def@var{mumble}}.
326 @comment node-name, next, previous, up
327 @subsection Funny Frames
328 @cindex External entry points
329 @cindex Entry points, external
330 @cindex Block compilation, debugger implications
331 @cindex External, stack frame kind
332 @cindex Optional, stack frame kind
333 @cindex Cleanup, stack frame kind
335 Sometimes the evaluator introduces new functions that are used to
336 implement a user function, but are not directly specified in the
337 source. The main place this is done is for checking argument type and
338 syntax. Usually these functions do their thing and then go away, and
339 thus are not seen on the stack in the debugger. But when you get some
340 sort of error during lambda-list processing, you end up in the
341 debugger on one of these funny frames.
343 These funny frames are flagged by printing
344 ``@code{[@var{keyword}]}'' after the parentheses. For example,
360 (string-upcase "test case" :end)
363 would look like this:
366 ("SB!INT:&MORE processing" "test case" 1053984 1)[:OPTIONAL]
369 As you can see, these frames have only a vague resemblance to the
370 original call. Fortunately, the error message displayed when you
371 enter the debugger will usually tell you what problem is (in these
372 cases, too many arguments and odd keyword arguments.) Also, if you go
373 down the stack to the frame for the calling function, you can display
374 the original source. @xref{Source Location Printing}.
376 @c FIXME: is the block-compilation part correct for SBCL?
378 With recursive or block compiled functions, an @code{:EXTERNAL} frame
379 may appear before the frame representing the first call to the
380 recursive function or entry to the compiled block. This is a
381 consequence of the way the compiler does block compilation: there is
382 nothing odd with your program. You will also see @code{:CLEANUP}
383 frames during the execution of @code{unwind-protect} cleanup
384 code. Note that inline expansion and open-coding affect what frames
385 are present in the debugger, see @ref{Debugger Policy Control}.
386 @comment FIXME: link here to section about open coding once it exists.
390 @node Debug Tail Recursion
391 @comment node-name, next, previous, up
392 @subsection Debug Tail Recursion
393 @cindex Tail recursion
394 @cindex Recursion, tail
396 Both the compiler and the interpreter are ``properly tail recursive.''
397 If a function call is in a tail-recursive position, the stack frame
398 will be deallocated @emph{at the time of the call}, rather than after
399 the call returns. Consider this backtrace:
406 Because of tail recursion, it is not necessarily the case that
407 @code{FOO} directly called @code{BAR}. It may be that @code{FOO}
408 called some other function @code{FOO2} which then called @code{BAR}
409 tail-recursively, as in this example:
425 Usually the elimination of tail-recursive frames makes debugging more
426 pleasant, since theses frames are mostly uninformative. If there is
427 any doubt about how one function called another, it can usually be
428 eliminated by finding the source location in the calling frame.
429 @xref{Source Location Printing}.
431 The elimination of tail-recursive frames can be prevented by disabling
432 tail-recursion optimization, which happens when the @code{debug}
433 optimization quality is greater than @code{2}.
434 @xref{Debugger Policy Control}.
436 @comment FIXME: reinstate this link once the chapter is in the manual.
437 @c For a more thorough discussion of tail recursion, @ref{tail-recursion}.
440 @node Unknown Locations and Interrupts
441 @comment node-name, next, previous, up
442 @subsection Unknown Locations and Interrupts
443 @cindex Unknown code locations
444 @cindex Locations, unknown
446 @cindex Errors, run-time
448 The debugger operates using special debugging information attached to
449 the compiled code. This debug information tells the debugger what it
450 needs to know about the locations in the code where the debugger can
451 be invoked. If the debugger somehow encounters a location not
452 described in the debug information, then it is said to be
453 @dfn{unknown}. If the code location for a frame is unknown, then some
454 variables may be inaccessible, and the source location cannot be
457 There are three reasons why a code location could be unknown:
462 There is inadequate debug information due to the value of the @code{debug}
463 optimization quality. @xref{Debugger Policy Control}.
466 The debugger was entered because of an interrupt such as @key{C-c}.
469 A hardware error such as ``@samp{bus error}'' occurred in code that was
470 compiled unsafely due to the value of the @code{safety} optimization
472 @comment FIXME: reinstate link when section on optimize qualities exists.
473 @c @xref{optimize-declaration}.
477 In the last two cases, the values of argument variables are
478 accessible, but may be incorrect. For more details on when variable
479 values are accessible, @ref{Variable Value Availability}.
481 It is possible for an interrupt to happen when a function call or
482 return is in progress. The debugger may then flame out with some
483 obscure error or insist that the bottom of the stack has been reached,
484 when the real problem is that the current stack frame can't be
485 located. If this happens, return from the interrupt and try again.
488 @node Variable Access
489 @comment node-name, next, previous, up
490 @section Variable Access
491 @cindex Debug variables
492 @cindex Variables, debugger access
494 There are two ways to access the current frame's local variables in
495 the debugger: @command{list-locals} and @code{sb-debug:var}.
497 The debugger doesn't really understand lexical scoping; it has just
498 one namespace for all the variables in the current stack frame. If a
499 symbol is the name of multiple variables in the same function, then
500 the reference appears ambiguous, even though lexical scoping specifies
501 which value is visible at any given source location. If the scopes of
502 the two variables are not nested, then the debugger can resolve the
503 ambiguity by observing that only one variable is accessible.
505 When there are ambiguous variables, the evaluator assigns each one a
506 small integer identifier. The @code{sb-debug:var} function uses this
507 identifier to distinguish between ambiguous variables. The
508 @command{list-locals} command prints the identifier. In the
509 following example, there are two variables named @code{X}. The first
510 one has identifier 0 (which is not printed), the second one has
518 @deffn {Debugger Command} list-locals [@var{prefix}]
519 This command prints the name and value of all variables in the current
520 frame whose name has the specified @var{prefix}. @var{prefix} may be
521 a string or a symbol. If no @var{prefix} is given, then all available
522 variables are printed. If a variable has a potentially ambiguous
523 name, then the name is printed with a ``@code{#@var{identifier}}''
524 suffix, where @var{identifier} is the small integer used to make the
528 @defun sb-debug:var @var{name} &optional @var{identifier}
529 This function returns the value of the variable in the current frame
530 with the specified @var{name}. If supplied, @var{identifier}
531 determines which value to return when there are ambiguous variables.
533 When @var{name} is a symbol, it is interpreted as the symbol name of
534 the variable, i.e. the package is significant. If @var{name} is an
535 uninterned symbol (gensym), then return the value of the uninterned
536 variable with the same name. If @var{name} is a string,
537 @code{sb-debug:var} interprets it as the prefix of a variable name
538 that must unambiguously complete to the name of a valid variable.
540 @var{identifier} is used to disambiguate the variable name; use
541 @command{list-locals} to find out the identifiers.
546 * Variable Value Availability::
547 * Note On Lexical Variable Access::
550 @node Variable Value Availability
551 @comment node-name, next, previous, up
552 @subsection Variable Value Availability
553 @cindex Availability of debug variables
554 @cindex Validity of debug variables
555 @cindex Debug optimization quality
557 The value of a variable may be unavailable to the debugger in portions
558 of the program where Lisp says that the variable is defined. If a
559 variable value is not available, the debugger will not let you read or
560 write that variable. With one exception, the debugger will never
561 display an incorrect value for a variable. Rather than displaying
562 incorrect values, the debugger tells you the value is unavailable.
564 The one exception is this: if you interrupt (e.g., with @key{C-c}) or
565 if there is an unexpected hardware error such as ``@samp{bus error}''
566 (which should only happen in unsafe code), then the values displayed
567 for arguments to the interrupted frame might be
568 incorrect.@footnote{Since the location of an interrupt or hardware
569 error will always be an unknown location, non-argument variable values
570 will never be available in the interrupted frame. @xref{Unknown
571 Locations and Interrupts}.} This exception applies only to the
572 interrupted frame: any frame farther down the stack will be fine.
574 The value of a variable may be unavailable for these reasons:
579 The value of the @code{debug} optimization quality may have omitted debug
580 information needed to determine whether the variable is available.
581 Unless a variable is an argument, its value will only be available when
582 @code{debug} is at least @code{2}.
585 The compiler did lifetime analysis and determined that the value was no longer
586 needed, even though its scope had not been exited. Lifetime analysis is
587 inhibited when the @code{debug} optimization quality is @code{3}.
590 The variable's name is an uninterned symbol (gensym). To save space, the
591 compiler only dumps debug information about uninterned variables when the
592 @code{debug} optimization quality is @code{3}.
595 The frame's location is unknown (@pxref{Unknown Locations and
596 Interrupts}) because the debugger was entered due to an interrupt or
597 unexpected hardware error. Under these conditions the values of
598 arguments will be available, but might be incorrect. This is the
599 exception mentioned above.
602 The variable (or the code referencing it) was optimized out
603 of existence. Variables with no reads are always optimized away. The
604 degree to which the compiler deletes variables will depend on the
605 value of the @code{compilation-speed} optimization quality, but most
606 source-level optimizations are done under all compilation policies.
609 The variable is never set and its definition looks like
614 In this case, @code{var1} is substituted with @code{var2}.
617 The variable is never set and is referenced exactly once. In this
618 case, the reference is substituted with the variable initial value.
622 Since it is especially useful to be able to get the arguments to a
623 function, argument variables are treated specially when the
624 @code{speed} optimization quality is less than @code{3} and the
625 @code{debug} quality is at least @code{1}. With this compilation
626 policy, the values of argument variables are almost always available
627 everywhere in the function, even at unknown locations. For
628 non-argument variables, @code{debug} must be at least @code{2} for
629 values to be available, and even then, values are only available at
633 @node Note On Lexical Variable Access
634 @comment node-name, next, previous, up
635 @subsection Note On Lexical Variable Access
637 When the debugger command loop establishes variable bindings for
638 available variables, these variable bindings have lexical scope and
639 dynamic extent.@footnote{The variable bindings are actually created
640 using the Lisp @code{symbol-macrolet} special form.} You can close
641 over them, but such closures can't be used as upward funargs.
643 You can also set local variables using @code{setq}, but if the
644 variable was closed over in the original source and never set, then
645 setting the variable in the debugger may not change the value in all
646 the functions the variable is defined in. Another risk of setting
647 variables is that you may assign a value of a type that the compiler
648 proved the variable could never take on. This may result in bad
652 @node Source Location Printing
653 @comment node-name, next, previous, up
654 @section Source Location Printing
655 @cindex Source location printing, debugger
657 One of the debugger's capabilities is source level debugging of
658 compiled code. These commands display the source location for the
661 @deffn {Debugger Command} source [@var{context}]
662 This command displays the file that the current frame's function was
663 defined from (if it was defined from a file), and then the source form
664 responsible for generating the code that the current frame was
665 executing. If @var{context} is specified, then it is an integer
666 specifying the number of enclosing levels of list structure to print.
669 The source form for a location in the code is the innermost list present
670 in the original source that encloses the form responsible for generating
671 that code. If the actual source form is not a list, then some enclosing
672 list will be printed. For example, if the source form was a reference
673 to the variable @code{*some-random-special*}, then the innermost
674 enclosing evaluated form will be printed. Here are some possible
678 (let ((a *some-random-special*))
681 (+ *some-random-special* ...)
684 If the code at a location was generated from the expansion of a macro
685 or a source-level compiler optimization, then the form in the original
686 source that expanded into that code will be printed. Suppose the file
687 @file{/usr/me/mystuff.lisp} looked like this:
698 If @code{foo} has called @code{myfun}, and is waiting for it to
699 return, then the @command{source} command would print:
702 ; File: /usr/me/mystuff.lisp
707 Note that the macro use was printed, not the actual function call form,
710 If enclosing source is printed by giving an argument to
711 @command{source} or @command{vsource}, then the actual source form is
712 marked by wrapping it in a list whose first element is
713 @samp{#:***HERE***}. In the previous example, @code{source 1} would
717 ; File: /usr/me/mystuff.lisp
727 * How the Source is Found::
728 * Source Location Availability::
731 @node How the Source is Found
732 @comment node-name, next, previous, up
733 @subsection How the Source is Found
735 If the code was defined from Lisp by @code{compile} or
736 @code{eval}, then the source can always be reliably located. If the
737 code was defined from a @file{fasl} file created by
738 @code{compile-file}, then the debugger gets the source forms it
739 prints by reading them from the original source file. This is a
740 potential problem, since the source file might have moved or changed
741 since the time it was compiled.
743 The source file is opened using the @code{truename} of the source file
744 pathname originally given to the compiler. This is an absolute pathname
745 with all logical names and symbolic links expanded. If the file can't
746 be located using this name, then the debugger gives up and signals an
749 If the source file can be found, but has been modified since the time it was
750 compiled, the debugger prints this warning:
753 ; File has been modified since compilation:
755 ; Using form offset instead of character position.
758 where @var{filename} is the name of the source file. It then proceeds
759 using a robust but not foolproof heuristic for locating the source.
760 This heuristic works if:
765 No top-level forms before the top-level form containing the source
766 have been added or deleted, and
769 The top-level form containing the source has not been modified much.
770 (More precisely, none of the list forms beginning before the source
771 form have been added or deleted.)
775 If the heuristic doesn't work, the displayed source will be wrong, but will
776 probably be near the actual source. If the ``shape'' of the top-level form in
777 the source file is too different from the original form, then an error will be
778 signaled. When the heuristic is used, the the source location commands are
781 Source location printing can also be confused if (after the source was
782 compiled) a read-macro you used in the code was redefined to expand
783 into something different, or if a read-macro ever returns the same
784 @code{eq} list twice. If you don't define read macros and don't use
785 @code{##} in perverted ways, you don't need to worry about this.
788 @node Source Location Availability
789 @comment node-name, next, previous, up
790 @subsection Source Location Availability
791 @cindex Debug optimization quality
793 @cindex Block, start location
795 Source location information is only available when the @code{debug}
796 optimization quality is at least @code{2}. If source location
797 information is unavailable, the source commands will give an error
800 If source location information is available, but the source location
801 is unknown because of an interrupt or unexpected hardware error
802 (@pxref{Unknown Locations and Interrupts}), then the command will
806 Unknown location: using block start.
809 and then proceed to print the source location for the start of the
810 @emph{basic block} enclosing the code location. It's a bit
811 complicated to explain exactly what a basic block is, but here are
812 some properties of the block start location:
816 @item The block start location may be the same as the true location.
818 @item The block start location will never be later in the the
819 program's flow of control than the true location.
821 @item No conditional control structures (such as @code{if},
822 @code{cond}, @code{or}) will intervene between the block start and the
823 true location (but note that some conditionals present in the original
824 source could be optimized away.) Function calls @emph{do not} end
827 @item The head of a loop will be the start of a block.
829 @item The programming language concept of ``block structure'' and the
830 Lisp @code{block} special form are totally unrelated to the compiler's
835 In other words, the true location lies between the printed location and the
836 next conditional (but watch out because the compiler may have changed the
840 @node Debugger Policy Control
841 @comment node-name, next, previous, up
842 @section Debugger Policy Control
843 @cindex Policy, debugger
844 @cindex Debug optimization quality
845 @cindex Optimize declaration
846 @cindex Inline expansion
847 @cindex Semi-inline expansion
849 The compilation policy specified by @code{optimize} declarations
850 affects the behavior seen in the debugger. The @code{debug} quality
851 directly affects the debugger by controlling the amount of debugger
852 information dumped. Other optimization qualities have indirect but
853 observable effects due to changes in the way compilation is done.
855 Unlike the other optimization qualities (which are compared in relative value
856 to evaluate tradeoffs), the @code{debug} optimization quality is directly
857 translated to a level of debug information. This absolute interpretation
858 allows the user to count on a particular amount of debug information being
859 available even when the values of the other qualities are changed during
860 compilation. These are the levels of debug information that correspond to the
861 values of the @code{debug} quality:
866 Only the function name and enough information to allow the stack to
870 Any level greater than @code{0} gives level @code{0} plus all argument
871 variables. Values will only be accessible if the argument variable is
872 never set and @code{speed} is not @code{3}. SBCL allows any real
873 value for optimization qualities. It may be useful to specify
874 @code{0.5} to get backtrace argument display without argument
878 Level @code{1} provides argument documentation (printed arglists) and
879 derived argument/result type information. This makes @code{describe}
880 more informative, and allows the compiler to do compile-time argument
881 count and type checking for any calls compiled at run-time. This is
885 Level @code{1} plus all interned local variables, source location
886 information, and lifetime information that tells the debugger when
887 arguments are available (even when @code{speed} is @code{3} or the
891 Any level greater than @code{2} gives level @code{2} and in addition
892 disables tail-call optimization, so that the backtrace will contain
893 frames for all invoked functions, even those in tail positions.
896 Level @code{2} plus all uninterned variables. In addition, lifetime
897 analysis is disabled (even when @code{speed} is @code{3}), ensuring
898 that all variable values are available at any known location within
899 the scope of the binding. This has a speed penalty in addition to the
900 obvious space penalty.
902 @item > (max speed space)
903 If @code{debug} is greater than both @code{speed} and @code{space},
904 the command @command{return} can be used to continue execution by
905 returning a value from the current stack frame.
909 As you can see, if the @code{speed} quality is @code{3}, debugger performance is
910 degraded. This effect comes from the elimination of argument variable
911 special-casing (@pxref{Variable Value Availability}). Some degree of
912 speed/debuggability tradeoff is unavoidable, but the effect is not too drastic
913 when @code{debug} is at least @code{2}.
915 In addition to @code{inline} and @code{notinline} declarations, the
916 relative values of the @code{speed} and @code{space} qualities also
917 change whether functions are inline expanded.
918 @comment FIXME: link to section about inline expansion when it exists
919 @c (\pxlref{inline-expansion}.)
920 If a function is inline expanded, then
921 there will be no frame to represent the call, and the arguments will
922 be treated like any other local variable. Functions may also be
923 ``semi-inline'', in which case there is a frame to represent the call,
924 but the call is to an optimized local version of the function, not to
925 the original function.
928 @node Exiting Commands
929 @comment node-name, next, previous, up
930 @section Exiting Commands
932 These commands get you out of the debugger.
934 @deffn {Debugger Command} toplevel
938 @deffn {Debugger Command} restart [@var{n}]
939 Invokes the @var{n}th restart case as displayed by the @code{error}
940 command. If @var{n} is not specified, the available restart cases are
944 @deffn {Debugger Command} continue
945 Calls @code{continue} on the condition given to @code{debug}. If there is no
946 restart case named @var{continue}, then an error is signaled.
949 @deffn {Debugger Command} abort
950 Calls @code{abort} on the condition given to @code{debug}. This is
951 useful for popping debug command loop levels or aborting to top level,
955 @deffn {Debugger Command} return @var{value}
956 Returns @var{value} from the current stack frame. This command is
957 available when the @code{debug} optimization quality is greater than
958 both @code{speed} and @code{space}. Care must be taken that the value
959 is of the same type as SBCL expects the stack frame to return.
963 @node Information Commands
964 @comment node-name, next, previous, up
965 @section Information Commands
967 Most of these commands print information about the current frame or
968 function, but a few show general information.
970 @deffn {Debugger Command} help
971 @deffnx {Debugger Command} ?
972 Displays a synopsis of debugger commands.
975 @deffn {Debugger Command} describe
976 Calls @code{describe} on the current function and displays the number of
980 @deffn {Debugger Command} print
981 Displays the current function call as it would be displayed by moving to
985 @deffn {Debugger Command} error
986 Prints the condition given to @code{invoke-debugger} and the active
990 @deffn {Debugger Command} backtrace [@var{n}]
991 Displays all the frames from the current to the bottom. Only shows
992 @var{n} frames if specified. The printing is controlled by @code{*debug-print-variable-alist*}.
995 @comment FIXME (rudi 2004-03-31): sbcl doesn't support breakpoints
996 @comment and stepping as of version 0.8.9. The `list-locations'
997 @comment command works, but executing a function leads to an error
998 @comment when a breakpoint is hit. When stepping works, the
999 @comment commented-out section below should be reinstated and the
1000 @comment example output updated to correspont to sbcl's behaviour.
1002 @c @node Breakpoint Commands, , Information Commands, The Debugger
1003 @c @comment node-name, next, previous, up
1004 @c @section Breakpoint Commands
1005 @c @cindex Breakpoints
1007 @c SBCL supports setting of breakpoints inside compiled functions and
1008 @c stepping of compiled code. Breakpoints can only be set at at known
1009 @c locations (@pxref{Unknown Locations and Interrupts}), so these
1010 @c commands are largely useless unless the @code{debug} optimize quality
1011 @c is at least @code{2} (@pxref{Debugger Policy Control}). These
1012 @c commands manipulate breakpoints:
1014 @c @deffn {Debugger Command} breakpoint @var{location} [@var{option} @var{value}]*
1015 @c Set a breakpoint in some function. @var{location} may be an integer
1016 @c code location number (as displayed by @command{list-locations}) or a
1017 @c keyword. The keyword can be used to indicate setting a breakpoint at
1018 @c the function start (@code{:start}, @code{:s}) or function end
1019 @c (@code{:end}, @code{:e}). The @command{breakpoint} command has
1020 @c @code{:condition}, @code{:break}, @code{:print} and @code{:function}
1021 @c options which work similarly to the @code{trace} options.
1024 @c @deffn {Debugger Command} list-locations [@var{function}]
1025 @c @deffnx {Debugger Command} ll [@var{function}]
1026 @c List all the code locations in the current frame's function, or in
1027 @c @var{function} if it is supplied. The display format is the code
1028 @c location number, a colon and then the source form for that location:
1034 @c If consecutive locations have the same source, then a numeric range
1035 @c like @code{3-5:} will be printed. For example, a default function
1036 @c call has a known location both immediately before and after the call,
1037 @c which would result in two code locations with the same source. The
1038 @c listed function becomes the new default function for breakpoint
1039 @c setting (via the @command{breakpoint}) command.
1042 @c @deffn {Debugger Command} list-breakpoints
1043 @c @deffnx {Debugger Command} lb
1044 @c List all currently active breakpoints with their breakpoint number.
1047 @c @deffn {Debugger Command} delete-breakpoint [@var{number}]
1048 @c @deffnx {Debugger Command} db [@var{number}]
1049 @c Delete a breakpoint specified by its breakpoint number. If no number
1050 @c is specified, delete all breakpoints.
1053 @c @deffn {Debugger Command} step
1054 @c Step to the next possible breakpoint location in the current function.
1055 @c This always steps over function calls, instead of stepping into them.
1060 @c * Breakpoint Example::
1063 @c @node Breakpoint Example, , Breakpoint Commands, Breakpoint Commands
1064 @c @comment node-name, next, previous, up
1065 @c @subsection Breakpoint Example
1067 @c Consider this definition of the factorial function:
1073 @c (* n (! (1- n)))))
1076 @c This debugger session demonstrates the use of breakpoints:
1079 @c * (break) ; invoke debugger
1081 @c debugger invoked on a SIMPLE-CONDITION in thread 11184: break
1083 @c restarts (invokable by number or by possibly-abbreviated name):
1084 @c 0: [CONTINUE] Return from BREAK.
1085 @c 1: [ABORT ] Reduce debugger level (leaving debugger, returning to toplevel).
1086 @c 2: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
1087 @c ("varargs entry for top level local call BREAK" "break")
1090 @c 0-1: (SB-INT:NAMED-LAMBDA ! (N) (BLOCK ! (IF (ZEROP N) 1 (* N (! #)))))
1091 @c 2: (BLOCK ! (IF (ZEROP N) 1 (* N (! (1- N)))))
1093 @c 4: (* N (! (1- N)))
1096 @c 7-8: (* N (! (1- N)))
1097 @c 9-10: (IF (ZEROP N) 1 (* N (! (1- N))))
1105 @c FIXME: SBCL errored out, and not in the expected way ... Copying the
1106 @c output verbatim from the CMUCL manual for now.
1108 @c common-lisp-user> (! 10) ; Call the function
1113 @c 0: [CONTINUE] Return from BREAK.
1114 @c 1: [ABORT ] Return to Top-Level.
1116 @c Debug (type H for help)
1118 @c (! 10) ; We are now in first call (arg 10) before the multiply
1119 @c Source: (* N (! (1- N)))
1124 @c (! 10) ; We have finished evaluation of (1- n)
1131 @c 0: [CONTINUE] Return from BREAK.
1132 @c 1: [ABORT ] Return to Top-Level.
1134 @c Debug (type H for help)
1136 @c (! 9) ; We hit the breakpoint in the recursive call
1137 @c Source: (* N (! (1- N)))
1142 @node Function Tracing
1143 @comment node-name, next, previous, up
1144 @section Function Tracing
1146 @cindex Function, tracing
1148 The tracer causes selected functions to print their arguments and
1149 their results whenever they are called. Options allow conditional
1150 printing of the trace information and conditional breakpoints on
1151 function entry or exit.
1153 @include macro-common-lisp-trace.texinfo
1155 @include macro-common-lisp-untrace.texinfo
1157 @include var-sb-debug-star-trace-indentation-step-star.texinfo
1159 @include var-sb-debug-star-max-trace-indentation-star.texinfo
1161 @include var-sb-debug-star-trace-encapsulate-default-star.texinfo
1163 @include var-sb-debug-star-trace-values-star.texinfo
1165 @comment FIXME rudi 2004-03-26: encapsulate is (per TODO file as of
1166 @comment 0.8.9) in a state of flux. When it's sorted out, revive the
1167 @comment cmucl documentation.