3 The SBCL debugger (as the CMUCL debugger it was derived from) has very
4 good support for source-level debugging of compiled code. Although
5 some other debuggers allow access of variables by name, this seems to
6 be the first Lisp debugger that:
11 Tells you when a variable doesn't have a value because it hasn't been
12 initialized yet or has already been deallocated, or
15 Can display the precise source location corresponding to a code
16 location in the debugged program.
20 These features allow the debugging of compiled code to be made almost
21 indistinguishable from interpreted code debugging.
25 * Starting the Debugger::
26 * The Debugger Command Loop::
27 * Controlling Printing in the Debugger::
30 * Source Location Printing::
31 * Debugger Policy Control::
33 * Information Commands::
37 @node Starting the Debugger
38 @comment node-name, next, previous, up
39 @section Starting the Debugger
41 The debugger is an interactive command loop that allows a user to examine
42 the function call stack. The debugger is invoked when:
47 A @code{serious-condition} is signaled, and it is not handled, or
50 @code{error} is called, and the condition it signals is not handled,
54 the debugger is explicitly entered with the Lisp @code{break} or
55 @code{invoke-debugger} functions.
59 When you enter the TTY debugger, it looks something like this:
62 debugger invoked on a TYPE-ERROR in thread 11184:
63 The value 3 is not of type LIST.
64 restarts (invokable by number or by possibly-abbreviated name):
65 0: [ABORT ] Reduce debugger level (leaving debugger, returning to toplevel).
66 1: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
71 The first group of lines describe what the error was that put us in
72 the debugger. In this case @code{car} was called on @code{3}. After
73 @samp{restarts} is a list of all the ways that we can restart
74 execution after this error. In this case, both options return to
75 top-level. After printing its banner, the debugger prints the current
76 frame and the debugger prompt.
78 When the debugger is invoked by a condition, ANSI mandates that the
79 value of @code{*debugger-hook*}, if any, be called with two arguments:
80 the condition that caused the debugger to be invoked and the previous
81 value of @code{*debugger-hook*}. When this happens,
82 @code{*debugger-hook*} is bound to NIL to prevent recursive
83 errors. However, ANSI also mandates that @code{*debugger-hook*} not be
84 invoked when the debugger is to be entered by the @code{break}
85 function. For users who wish to provide an alternate debugger
86 interface (and thus catch @code{break} entries into the debugger),
87 SBCL provides @code{sb-ext:*invoke-debugger-hook*}, which is invoked
88 during any entry into the debugger.
90 @include var-sb-ext-star-invoke-debugger-hook-star.texinfo
93 @node The Debugger Command Loop
94 @comment node-name, next, previous, up
95 @section The Debugger Command Loop
96 @cindex Evaluation, in the debugger
98 The debugger is an interactive read-eval-print loop much like the normal
99 top-level, but some symbols are interpreted as debugger commands instead
100 of being evaluated. A debugger command starts with the symbol name of
101 the command, possibly followed by some arguments on the same line. Some
102 commands prompt for additional input. Debugger commands can be
103 abbreviated by any unambiguous prefix: @command{help} can be typed as
104 @samp{h}, @samp{he}, etc. For convenience, some commands have
105 ambiguous one-letter abbreviations: @samp{f} for @command{frame}.
106 @comment FIXME: what does that last bit mean?
108 The package is not significant in debugger commands; any symbol with the
109 name of a debugger command will work. If you want to show the value of
110 a variable that happens also to be the name of a debugger command, you
111 can use the @command{list-locals} command or the @code{sb-debug:var}
112 function, or you can wrap the variable in a @code{progn} to hide it from
115 The debugger prompt is ``@code{@var{frame}]}'', where @var{frame} is
116 the number of the current frame. Frames are numbered starting from
117 zero at the top (most recent call), increasing down to the bottom.
118 The current frame is the frame that commands refer to. The current
119 frame also provides the lexical environment for evaluation of
122 The debugger evaluates forms in the lexical environment of the
123 functions being debugged. The debugger can only access variables.
124 You can't @code{go} or @code{return-from} into a function, and you
125 can't call local functions. Special variable references are evaluated
126 with their current value (the innermost binding around the debugger
127 invocation) -- you don't get the value that the special had in the
128 current frame. For more information on debugger variable access, see
129 @ref{Variable Access}.
132 @node Controlling Printing in the Debugger
133 @comment node-name, next, previous, up
134 @section Controlling Printing in the Debugger
136 In the debugger, it is possible to override the printing behaviour of
139 @defvr {Variable} sb-debug:*debug-print-variable-alist*
141 An association list describing new bindings for special variables
142 (typically *PRINT-FOO* variables) to be used within the debugger, e.g.
144 ((*PRINT-LENGTH* . 10) (*PRINT-LEVEL* . 6) (*PRINT-PRETTY* . NIL))
146 The variables in the @code{car} position are bound to the values in
147 the @code{cdr} during the execution of some debug commands. When
148 evaluating arbitrary expressions in the debugger, the normal values of
149 the printer control variables are in effect. @c FIXME: is this correct?
150 @code{*debug-print-variable-alist*} does not contain any bindings
156 @comment node-name, next, previous, up
157 @section Stack Frames
160 A @dfn{stack frame} is the run-time representation of a call to a
161 function; the frame stores the state that a function needs to remember
162 what it is doing. Frames have:
167 @dfn{variables} (@pxref{Variable Access}), which are the values being operated
171 @dfn{arguments} to the call (which are really just particularly
172 interesting variables), and
175 a current location (@pxref{Source Location Printing}), which is the place in
176 the program where the function was running when it stopped to call
177 another function, or because of an interrupt or error.
184 * How Arguments are Printed::
187 * Debug Tail Recursion::
188 * Unknown Locations and Interrupts::
192 @comment node-name, next, previous, up
193 @subsection Stack Motion
195 These commands move to a new stack frame and print the name of the
196 function and the values of its arguments in the style of a Lisp
199 @deffn {Debugger Command} up
200 Move up to the next higher frame. More recent function calls are
201 considered to be higher on the stack.
204 @deffn {Debugger Command} down
205 Move down to the next lower frame.
208 @deffn {Debugger Command} top
209 Move to the highest frame, that is, the frame where the debugger was
213 @deffn {Debugger Command} bottom
214 Move to the lowest frame.
217 @deffn {Debugger Command} frame [@var{n}]
218 Move to the frame with the specified number. Prompts for the number if not
219 supplied. The frame with number 0 is the frame where the debugger
224 @node How Arguments are Printed
225 @comment node-name, next, previous, up
226 @subsection How Arguments are Printed
228 A frame is printed to look like a function call, but with the actual
229 argument values in the argument positions. So the frame for this call
236 would look like this:
242 All keyword and optional arguments are displayed with their actual
243 values; if the corresponding argument was not supplied, the value will
244 be the default. So this call:
250 would look like this:
259 (string-upcase "test case")
262 would look like this:
265 (STRING-UPCASE "test case" :START 0 :END NIL)
268 The arguments to a function call are displayed by accessing the
269 argument variables. Although those variables are initialized to the
270 actual argument values, they can be set inside the function; in this
271 case the new value will be displayed.
273 @code{&rest} arguments are handled somewhat differently. The value of
274 the rest argument variable is displayed as the spread-out arguments to
278 (format t "~A is a ~A." "This" 'test)
281 would look like this:
284 (FORMAT T "~A is a ~A." "This" 'TEST)
287 Rest arguments cause an exception to the normal display of keyword
288 arguments in functions that have both @code{&rest} and @code{&key}
289 arguments. In this case, the keyword argument variables are not
290 displayed at all; the rest arg is displayed instead. So for these
291 functions, only the keywords actually supplied will be shown, and the
292 values displayed will be the argument values, not values of the
293 (possibly modified) variables.
295 If the variable for an argument is never referenced by the function,
296 it will be deleted. The variable value is then unavailable, so the
297 debugger prints @samp{#<unused-arg>} instead of the value. Similarly,
298 if for any of a number of reasons the value of the variable is
299 unavailable or not known to be available (@pxref{Variable Access}),
300 then @samp{#<unavailable-arg>} will be printed instead of the argument
303 @vindex *debug-print-variable-alist*
304 Printing of argument values is controlled by
305 @code{*debug-print-variable-alist*}. @xref{Controlling Printing in
310 @comment node-name, next, previous, up
311 @subsection Function Names
313 If a function is defined by @code{defun}, @code{labels}, or
314 @code{flet}, then the debugger will print the actual function name
315 after the open parenthesis, like:
318 (STRING-UPCASE "test case" :START 0 :END NIL)
319 ((SETF AREF) #\a "for" 1)
322 Otherwise, the function name is a string, and will be printed in
327 ("DEFMACRO DO" (DO ((I 0 (1+ I))) ((= I 13))) NIL)
328 ("SETQ *GC-NOTIFY-BEFORE*")
331 This string name is derived from the @code{def@var{mumble}} form
332 that encloses or expanded into the lambda, or the outermost enclosing
333 form if there is no @code{def@var{mumble}}.
337 @comment node-name, next, previous, up
338 @subsection Funny Frames
339 @cindex External entry points
340 @cindex Entry points, external
341 @cindex Block compilation, debugger implications
342 @cindex External, stack frame kind
343 @cindex Optional, stack frame kind
344 @cindex Cleanup, stack frame kind
346 Sometimes the evaluator introduces new functions that are used to
347 implement a user function, but are not directly specified in the
348 source. The main place this is done is for checking argument type and
349 syntax. Usually these functions do their thing and then go away, and
350 thus are not seen on the stack in the debugger. But when you get some
351 sort of error during lambda-list processing, you end up in the
352 debugger on one of these funny frames.
354 These funny frames are flagged by printing
355 ``@code{[@var{keyword}]}'' after the parentheses. For example,
371 (string-upcase "test case" :end)
374 would look like this:
377 ("SB!INT:&MORE processing" "test case" 1053984 1)[:OPTIONAL]
380 As you can see, these frames have only a vague resemblance to the
381 original call. Fortunately, the error message displayed when you
382 enter the debugger will usually tell you what problem is (in these
383 cases, too many arguments and odd keyword arguments.) Also, if you go
384 down the stack to the frame for the calling function, you can display
385 the original source. @xref{Source Location Printing}.
387 @c FIXME: is the block-compilation part correct for SBCL?
389 With recursive or block compiled functions, an @code{:EXTERNAL} frame
390 may appear before the frame representing the first call to the
391 recursive function or entry to the compiled block. This is a
392 consequence of the way the compiler does block compilation: there is
393 nothing odd with your program. You will also see @code{:CLEANUP}
394 frames during the execution of @code{unwind-protect} cleanup
395 code. Note that inline expansion and open-coding affect what frames
396 are present in the debugger, see @ref{Debugger Policy Control}.
397 @comment FIXME: link here to section about open coding once it exists.
401 @node Debug Tail Recursion
402 @comment node-name, next, previous, up
403 @subsection Debug Tail Recursion
404 @cindex Tail recursion
405 @cindex Recursion, tail
407 Both the compiler and the interpreter are ``properly tail recursive.''
408 If a function call is in a tail-recursive position, the stack frame
409 will be deallocated @emph{at the time of the call}, rather than after
410 the call returns. Consider this backtrace:
417 Because of tail recursion, it is not necessarily the case that
418 @code{FOO} directly called @code{BAR}. It may be that @code{FOO}
419 called some other function @code{FOO2} which then called @code{BAR}
420 tail-recursively, as in this example:
436 Usually the elimination of tail-recursive frames makes debugging more
437 pleasant, since theses frames are mostly uninformative. If there is
438 any doubt about how one function called another, it can usually be
439 eliminated by finding the source location in the calling frame.
440 @xref{Source Location Printing}.
442 The elimination of tail-recursive frames can be prevented by disabling
443 tail-recursion optimization, which happens when the @code{debug}
444 optimization quality is greater than @code{2}.
445 @xref{Debugger Policy Control}.
447 @comment FIXME: reinstate this link once the chapter is in the manual.
448 @c For a more thorough discussion of tail recursion, @ref{tail-recursion}.
451 @node Unknown Locations and Interrupts
452 @comment node-name, next, previous, up
453 @subsection Unknown Locations and Interrupts
454 @cindex Unknown code locations
455 @cindex Locations, unknown
457 @cindex Errors, run-time
459 The debugger operates using special debugging information attached to
460 the compiled code. This debug information tells the debugger what it
461 needs to know about the locations in the code where the debugger can
462 be invoked. If the debugger somehow encounters a location not
463 described in the debug information, then it is said to be
464 @dfn{unknown}. If the code location for a frame is unknown, then some
465 variables may be inaccessible, and the source location cannot be
468 There are three reasons why a code location could be unknown:
473 There is inadequate debug information due to the value of the @code{debug}
474 optimization quality. @xref{Debugger Policy Control}.
477 The debugger was entered because of an interrupt such as @key{C-c}.
480 A hardware error such as ``@samp{bus error}'' occurred in code that was
481 compiled unsafely due to the value of the @code{safety} optimization
483 @comment FIXME: reinstate link when section on optimize qualities exists.
484 @c @xref{optimize-declaration}.
488 In the last two cases, the values of argument variables are
489 accessible, but may be incorrect. For more details on when variable
490 values are accessible, @ref{Variable Value Availability}.
492 It is possible for an interrupt to happen when a function call or
493 return is in progress. The debugger may then flame out with some
494 obscure error or insist that the bottom of the stack has been reached,
495 when the real problem is that the current stack frame can't be
496 located. If this happens, return from the interrupt and try again.
499 @node Variable Access
500 @comment node-name, next, previous, up
501 @section Variable Access
502 @cindex Debug variables
503 @cindex Variables, debugger access
505 There are two ways to access the current frame's local variables in
506 the debugger: @command{list-locals} and @code{sb-debug:var}.
508 The debugger doesn't really understand lexical scoping; it has just
509 one namespace for all the variables in the current stack frame. If a
510 symbol is the name of multiple variables in the same function, then
511 the reference appears ambiguous, even though lexical scoping specifies
512 which value is visible at any given source location. If the scopes of
513 the two variables are not nested, then the debugger can resolve the
514 ambiguity by observing that only one variable is accessible.
516 When there are ambiguous variables, the evaluator assigns each one a
517 small integer identifier. The @code{sb-debug:var} function uses this
518 identifier to distinguish between ambiguous variables. The
519 @command{list-locals} command prints the identifier. In the
520 following example, there are two variables named @code{X}. The first
521 one has identifier 0 (which is not printed), the second one has
529 @deffn {Debugger Command} list-locals [@var{prefix}]
530 This command prints the name and value of all variables in the current
531 frame whose name has the specified @var{prefix}. @var{prefix} may be
532 a string or a symbol. If no @var{prefix} is given, then all available
533 variables are printed. If a variable has a potentially ambiguous
534 name, then the name is printed with a ``@code{#@var{identifier}}''
535 suffix, where @var{identifier} is the small integer used to make the
539 @defun sb-debug:var @var{name} &optional @var{identifier}
540 This function returns the value of the variable in the current frame
541 with the specified @var{name}. If supplied, @var{identifier}
542 determines which value to return when there are ambiguous variables.
544 When @var{name} is a symbol, it is interpreted as the symbol name of
545 the variable, i.e. the package is significant. If @var{name} is an
546 uninterned symbol (gensym), then return the value of the uninterned
547 variable with the same name. If @var{name} is a string,
548 @code{sb-debug:var} interprets it as the prefix of a variable name
549 that must unambiguously complete to the name of a valid variable.
551 @var{identifier} is used to disambiguate the variable name; use
552 @command{list-locals} to find out the identifiers.
557 * Variable Value Availability::
558 * Note On Lexical Variable Access::
561 @node Variable Value Availability
562 @comment node-name, next, previous, up
563 @subsection Variable Value Availability
564 @cindex Availability of debug variables
565 @cindex Validity of debug variables
566 @cindex Debug optimization quality
568 The value of a variable may be unavailable to the debugger in portions
569 of the program where Lisp says that the variable is defined. If a
570 variable value is not available, the debugger will not let you read or
571 write that variable. With one exception, the debugger will never
572 display an incorrect value for a variable. Rather than displaying
573 incorrect values, the debugger tells you the value is unavailable.
575 The one exception is this: if you interrupt (e.g., with @key{C-c}) or
576 if there is an unexpected hardware error such as ``@samp{bus error}''
577 (which should only happen in unsafe code), then the values displayed
578 for arguments to the interrupted frame might be
579 incorrect.@footnote{Since the location of an interrupt or hardware
580 error will always be an unknown location, non-argument variable values
581 will never be available in the interrupted frame. @xref{Unknown
582 Locations and Interrupts}.} This exception applies only to the
583 interrupted frame: any frame farther down the stack will be fine.
585 The value of a variable may be unavailable for these reasons:
590 The value of the @code{debug} optimization quality may have omitted debug
591 information needed to determine whether the variable is available.
592 Unless a variable is an argument, its value will only be available when
593 @code{debug} is at least @code{2}.
596 The compiler did lifetime analysis and determined that the value was no longer
597 needed, even though its scope had not been exited. Lifetime analysis is
598 inhibited when the @code{debug} optimization quality is @code{3}.
601 The variable's name is an uninterned symbol (gensym). To save space, the
602 compiler only dumps debug information about uninterned variables when the
603 @code{debug} optimization quality is @code{3}.
606 The frame's location is unknown (@pxref{Unknown Locations and
607 Interrupts}) because the debugger was entered due to an interrupt or
608 unexpected hardware error. Under these conditions the values of
609 arguments will be available, but might be incorrect. This is the
610 exception mentioned above.
613 The variable (or the code referencing it) was optimized out
614 of existence. Variables with no reads are always optimized away. The
615 degree to which the compiler deletes variables will depend on the
616 value of the @code{compilation-speed} optimization quality, but most
617 source-level optimizations are done under all compilation policies.
620 The variable is never set and its definition looks like
625 In this case, @code{var1} is substituted with @code{var2}.
628 The variable is never set and is referenced exactly once. In this
629 case, the reference is substituted with the variable initial value.
633 Since it is especially useful to be able to get the arguments to a
634 function, argument variables are treated specially when the
635 @code{speed} optimization quality is less than @code{3} and the
636 @code{debug} quality is at least @code{1}. With this compilation
637 policy, the values of argument variables are almost always available
638 everywhere in the function, even at unknown locations. For
639 non-argument variables, @code{debug} must be at least @code{2} for
640 values to be available, and even then, values are only available at
644 @node Note On Lexical Variable Access
645 @comment node-name, next, previous, up
646 @subsection Note On Lexical Variable Access
648 When the debugger command loop establishes variable bindings for
649 available variables, these variable bindings have lexical scope and
650 dynamic extent.@footnote{The variable bindings are actually created
651 using the Lisp @code{symbol-macrolet} special form.} You can close
652 over them, but such closures can't be used as upward funargs.
654 You can also set local variables using @code{setq}, but if the
655 variable was closed over in the original source and never set, then
656 setting the variable in the debugger may not change the value in all
657 the functions the variable is defined in. Another risk of setting
658 variables is that you may assign a value of a type that the compiler
659 proved the variable could never take on. This may result in bad
663 @node Source Location Printing
664 @comment node-name, next, previous, up
665 @section Source Location Printing
666 @cindex Source location printing, debugger
668 One of the debugger's capabilities is source level debugging of
669 compiled code. These commands display the source location for the
672 @deffn {Debugger Command} source [@var{context}]
673 This command displays the file that the current frame's function was
674 defined from (if it was defined from a file), and then the source form
675 responsible for generating the code that the current frame was
676 executing. If @var{context} is specified, then it is an integer
677 specifying the number of enclosing levels of list structure to print.
680 The source form for a location in the code is the innermost list present
681 in the original source that encloses the form responsible for generating
682 that code. If the actual source form is not a list, then some enclosing
683 list will be printed. For example, if the source form was a reference
684 to the variable @code{*some-random-special*}, then the innermost
685 enclosing evaluated form will be printed. Here are some possible
689 (let ((a *some-random-special*))
692 (+ *some-random-special* ...)
695 If the code at a location was generated from the expansion of a macro
696 or a source-level compiler optimization, then the form in the original
697 source that expanded into that code will be printed. Suppose the file
698 @file{/usr/me/mystuff.lisp} looked like this:
709 If @code{foo} has called @code{myfun}, and is waiting for it to
710 return, then the @command{source} command would print:
713 ; File: /usr/me/mystuff.lisp
718 Note that the macro use was printed, not the actual function call form,
721 If enclosing source is printed by giving an argument to
722 @command{source} or @command{vsource}, then the actual source form is
723 marked by wrapping it in a list whose first element is
724 @samp{#:***HERE***}. In the previous example, @code{source 1} would
728 ; File: /usr/me/mystuff.lisp
738 * How the Source is Found::
739 * Source Location Availability::
742 @node How the Source is Found
743 @comment node-name, next, previous, up
744 @subsection How the Source is Found
746 If the code was defined from Lisp by @code{compile} or
747 @code{eval}, then the source can always be reliably located. If the
748 code was defined from a @file{fasl} file created by
749 @code{compile-file}, then the debugger gets the source forms it
750 prints by reading them from the original source file. This is a
751 potential problem, since the source file might have moved or changed
752 since the time it was compiled.
754 The source file is opened using the @code{truename} of the source file
755 pathname originally given to the compiler. This is an absolute pathname
756 with all logical names and symbolic links expanded. If the file can't
757 be located using this name, then the debugger gives up and signals an
760 If the source file can be found, but has been modified since the time it was
761 compiled, the debugger prints this warning:
764 ; File has been modified since compilation:
766 ; Using form offset instead of character position.
769 where @var{filename} is the name of the source file. It then proceeds
770 using a robust but not foolproof heuristic for locating the source.
771 This heuristic works if:
776 No top-level forms before the top-level form containing the source
777 have been added or deleted, and
780 The top-level form containing the source has not been modified much.
781 (More precisely, none of the list forms beginning before the source
782 form have been added or deleted.)
786 If the heuristic doesn't work, the displayed source will be wrong, but will
787 probably be near the actual source. If the ``shape'' of the top-level form in
788 the source file is too different from the original form, then an error will be
789 signaled. When the heuristic is used, the the source location commands are
792 Source location printing can also be confused if (after the source was
793 compiled) a read-macro you used in the code was redefined to expand
794 into something different, or if a read-macro ever returns the same
795 @code{eq} list twice. If you don't define read macros and don't use
796 @code{##} in perverted ways, you don't need to worry about this.
799 @node Source Location Availability
800 @comment node-name, next, previous, up
801 @subsection Source Location Availability
802 @cindex Debug optimization quality
804 @cindex Block, start location
806 Source location information is only available when the @code{debug}
807 optimization quality is at least @code{2}. If source location
808 information is unavailable, the source commands will give an error
811 If source location information is available, but the source location
812 is unknown because of an interrupt or unexpected hardware error
813 (@pxref{Unknown Locations and Interrupts}), then the command will
817 Unknown location: using block start.
820 and then proceed to print the source location for the start of the
821 @emph{basic block} enclosing the code location. It's a bit
822 complicated to explain exactly what a basic block is, but here are
823 some properties of the block start location:
827 @item The block start location may be the same as the true location.
829 @item The block start location will never be later in the the
830 program's flow of control than the true location.
832 @item No conditional control structures (such as @code{if},
833 @code{cond}, @code{or}) will intervene between the block start and the
834 true location (but note that some conditionals present in the original
835 source could be optimized away.) Function calls @emph{do not} end
838 @item The head of a loop will be the start of a block.
840 @item The programming language concept of ``block structure'' and the
841 Lisp @code{block} special form are totally unrelated to the compiler's
846 In other words, the true location lies between the printed location and the
847 next conditional (but watch out because the compiler may have changed the
851 @node Debugger Policy Control
852 @comment node-name, next, previous, up
853 @section Debugger Policy Control
854 @cindex Policy, debugger
855 @cindex Debug optimization quality
856 @cindex Optimize declaration
857 @cindex Inline expansion
858 @cindex Semi-inline expansion
860 The compilation policy specified by @code{optimize} declarations
861 affects the behavior seen in the debugger. The @code{debug} quality
862 directly affects the debugger by controlling the amount of debugger
863 information dumped. Other optimization qualities have indirect but
864 observable effects due to changes in the way compilation is done.
866 Unlike the other optimization qualities (which are compared in relative value
867 to evaluate tradeoffs), the @code{debug} optimization quality is directly
868 translated to a level of debug information. This absolute interpretation
869 allows the user to count on a particular amount of debug information being
870 available even when the values of the other qualities are changed during
871 compilation. These are the levels of debug information that correspond to the
872 values of the @code{debug} quality:
877 Only the function name and enough information to allow the stack to
881 Any level greater than @code{0} gives level @code{0} plus all argument
882 variables. Values will only be accessible if the argument variable is
883 never set and @code{speed} is not @code{3}. SBCL allows any real
884 value for optimization qualities. It may be useful to specify
885 @code{0.5} to get backtrace argument display without argument
889 Level @code{1} provides argument documentation (printed arglists) and
890 derived argument/result type information. This makes @code{describe}
891 more informative, and allows the compiler to do compile-time argument
892 count and type checking for any calls compiled at run-time. This is
896 Level @code{1} plus all interned local variables, source location
897 information, and lifetime information that tells the debugger when
898 arguments are available (even when @code{speed} is @code{3} or the
902 Any level greater than @code{2} gives level @code{2} and in addition
903 disables tail-call optimization, so that the backtrace will contain
904 frames for all invoked functions, even those in tail positions.
907 Level @code{2} plus all uninterned variables. In addition, lifetime
908 analysis is disabled (even when @code{speed} is @code{3}), ensuring
909 that all variable values are available at any known location within
910 the scope of the binding. This has a speed penalty in addition to the
911 obvious space penalty.
913 @item > (max speed space)
914 If @code{debug} is greater than both @code{speed} and @code{space},
915 the command @command{return} can be used to continue execution by
916 returning a value from the current stack frame.
920 As you can see, if the @code{speed} quality is @code{3}, debugger performance is
921 degraded. This effect comes from the elimination of argument variable
922 special-casing (@pxref{Variable Value Availability}). Some degree of
923 speed/debuggability tradeoff is unavoidable, but the effect is not too drastic
924 when @code{debug} is at least @code{2}.
926 In addition to @code{inline} and @code{notinline} declarations, the
927 relative values of the @code{speed} and @code{space} qualities also
928 change whether functions are inline expanded.
929 @comment FIXME: link to section about inline expansion when it exists
930 @c (\pxlref{inline-expansion}.)
931 If a function is inline expanded, then
932 there will be no frame to represent the call, and the arguments will
933 be treated like any other local variable. Functions may also be
934 ``semi-inline'', in which case there is a frame to represent the call,
935 but the call is to an optimized local version of the function, not to
936 the original function.
939 @node Exiting Commands
940 @comment node-name, next, previous, up
941 @section Exiting Commands
943 These commands get you out of the debugger.
945 @deffn {Debugger Command} toplevel
949 @deffn {Debugger Command} restart [@var{n}]
950 Invokes the @var{n}th restart case as displayed by the @code{error}
951 command. If @var{n} is not specified, the available restart cases are
955 @deffn {Debugger Command} continue
956 Calls @code{continue} on the condition given to @code{debug}. If there is no
957 restart case named @var{continue}, then an error is signaled.
960 @deffn {Debugger Command} abort
961 Calls @code{abort} on the condition given to @code{debug}. This is
962 useful for popping debug command loop levels or aborting to top level,
966 @deffn {Debugger Command} return @var{value}
967 Returns @var{value} from the current stack frame. This command is
968 available when the @code{debug} optimization quality is greater than
969 both @code{speed} and @code{space}. Care must be taken that the value
970 is of the same type as SBCL expects the stack frame to return.
974 @node Information Commands
975 @comment node-name, next, previous, up
976 @section Information Commands
978 Most of these commands print information about the current frame or
979 function, but a few show general information.
981 @deffn {Debugger Command} help
982 @deffnx {Debugger Command} ?
983 Displays a synopsis of debugger commands.
986 @deffn {Debugger Command} describe
987 Calls @code{describe} on the current function and displays the number of
991 @deffn {Debugger Command} print
992 Displays the current function call as it would be displayed by moving to
996 @deffn {Debugger Command} error
997 Prints the condition given to @code{invoke-debugger} and the active
1001 @deffn {Debugger Command} backtrace [@var{n}]
1002 Displays all the frames from the current to the bottom. Only shows
1003 @var{n} frames if specified. The printing is controlled by @code{*debug-print-variable-alist*}.
1006 @comment FIXME (rudi 2004-03-31): sbcl doesn't support breakpoints
1007 @comment and stepping as of version 0.8.9. The `list-locations'
1008 @comment command works, but executing a function leads to an error
1009 @comment when a breakpoint is hit. When stepping works, the
1010 @comment commented-out section below should be reinstated and the
1011 @comment example output updated to correspont to sbcl's behaviour.
1013 @c @node Breakpoint Commands, , Information Commands, The Debugger
1014 @c @comment node-name, next, previous, up
1015 @c @section Breakpoint Commands
1016 @c @cindex Breakpoints
1018 @c SBCL supports setting of breakpoints inside compiled functions and
1019 @c stepping of compiled code. Breakpoints can only be set at at known
1020 @c locations (@pxref{Unknown Locations and Interrupts}), so these
1021 @c commands are largely useless unless the @code{debug} optimize quality
1022 @c is at least @code{2} (@pxref{Debugger Policy Control}). These
1023 @c commands manipulate breakpoints:
1025 @c @deffn {Debugger Command} breakpoint @var{location} [@var{option} @var{value}]*
1026 @c Set a breakpoint in some function. @var{location} may be an integer
1027 @c code location number (as displayed by @command{list-locations}) or a
1028 @c keyword. The keyword can be used to indicate setting a breakpoint at
1029 @c the function start (@code{:start}, @code{:s}) or function end
1030 @c (@code{:end}, @code{:e}). The @command{breakpoint} command has
1031 @c @code{:condition}, @code{:break}, @code{:print} and @code{:function}
1032 @c options which work similarly to the @code{trace} options.
1035 @c @deffn {Debugger Command} list-locations [@var{function}]
1036 @c @deffnx {Debugger Command} ll [@var{function}]
1037 @c List all the code locations in the current frame's function, or in
1038 @c @var{function} if it is supplied. The display format is the code
1039 @c location number, a colon and then the source form for that location:
1045 @c If consecutive locations have the same source, then a numeric range
1046 @c like @code{3-5:} will be printed. For example, a default function
1047 @c call has a known location both immediately before and after the call,
1048 @c which would result in two code locations with the same source. The
1049 @c listed function becomes the new default function for breakpoint
1050 @c setting (via the @command{breakpoint}) command.
1053 @c @deffn {Debugger Command} list-breakpoints
1054 @c @deffnx {Debugger Command} lb
1055 @c List all currently active breakpoints with their breakpoint number.
1058 @c @deffn {Debugger Command} delete-breakpoint [@var{number}]
1059 @c @deffnx {Debugger Command} db [@var{number}]
1060 @c Delete a breakpoint specified by its breakpoint number. If no number
1061 @c is specified, delete all breakpoints.
1064 @c @deffn {Debugger Command} step
1065 @c Step to the next possible breakpoint location in the current function.
1066 @c This always steps over function calls, instead of stepping into them.
1071 @c * Breakpoint Example::
1074 @c @node Breakpoint Example, , Breakpoint Commands, Breakpoint Commands
1075 @c @comment node-name, next, previous, up
1076 @c @subsection Breakpoint Example
1078 @c Consider this definition of the factorial function:
1084 @c (* n (! (1- n)))))
1087 @c This debugger session demonstrates the use of breakpoints:
1090 @c * (break) ; invoke debugger
1092 @c debugger invoked on a SIMPLE-CONDITION in thread 11184: break
1094 @c restarts (invokable by number or by possibly-abbreviated name):
1095 @c 0: [CONTINUE] Return from BREAK.
1096 @c 1: [ABORT ] Reduce debugger level (leaving debugger, returning to toplevel).
1097 @c 2: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
1098 @c ("varargs entry for top level local call BREAK" "break")
1101 @c 0-1: (SB-INT:NAMED-LAMBDA ! (N) (BLOCK ! (IF (ZEROP N) 1 (* N (! #)))))
1102 @c 2: (BLOCK ! (IF (ZEROP N) 1 (* N (! (1- N)))))
1104 @c 4: (* N (! (1- N)))
1107 @c 7-8: (* N (! (1- N)))
1108 @c 9-10: (IF (ZEROP N) 1 (* N (! (1- N))))
1116 @c FIXME: SBCL errored out, and not in the expected way ... Copying the
1117 @c output verbatim from the CMUCL manual for now.
1119 @c common-lisp-user> (! 10) ; Call the function
1124 @c 0: [CONTINUE] Return from BREAK.
1125 @c 1: [ABORT ] Return to Top-Level.
1127 @c Debug (type H for help)
1129 @c (! 10) ; We are now in first call (arg 10) before the multiply
1130 @c Source: (* N (! (1- N)))
1135 @c (! 10) ; We have finished evaluation of (1- n)
1142 @c 0: [CONTINUE] Return from BREAK.
1143 @c 1: [ABORT ] Return to Top-Level.
1145 @c Debug (type H for help)
1147 @c (! 9) ; We hit the breakpoint in the recursive call
1148 @c Source: (* N (! (1- N)))
1153 @node Function Tracing
1154 @comment node-name, next, previous, up
1155 @section Function Tracing
1157 @cindex Function, tracing
1159 The tracer causes selected functions to print their arguments and
1160 their results whenever they are called. Options allow conditional
1161 printing of the trace information and conditional breakpoints on
1162 function entry or exit.
1164 @include macro-common-lisp-trace.texinfo
1166 @include macro-common-lisp-untrace.texinfo
1168 @include var-sb-debug-star-trace-indentation-step-star.texinfo
1170 @include var-sb-debug-star-max-trace-indentation-star.texinfo
1172 @include var-sb-debug-star-trace-encapsulate-default-star.texinfo
1174 @include var-sb-debug-star-trace-values-star.texinfo
1176 @comment FIXME rudi 2004-03-26: encapsulate is (per TODO file as of
1177 @comment 0.8.9) in a state of flux. When it's sorted out, revive the
1178 @comment cmucl documentation.