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::
41 @node Starting the Debugger
42 @comment node-name, next, previous, up
43 @section Starting the Debugger
45 The debugger is an interactive command loop that allows a user to examine
46 the function call stack. The debugger is invoked when:
51 A @code{serious-condition} is signaled, and it is not handled, or
54 @code{error} is called, and the condition it signals is not handled,
58 the debugger is explicitly entered with the Lisp @code{break} or
59 @code{invoke-debugger} functions.
63 When you enter the TTY debugger, it looks something like this:
66 debugger invoked on a TYPE-ERROR in thread 11184:
67 The value 3 is not of type LIST.
68 restarts (invokable by number or by possibly-abbreviated name):
69 0: [ABORT ] Reduce debugger level (leaving debugger, returning to toplevel).
70 1: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
75 The first group of lines describe what the error was that put us in
76 the debugger. In this case @code{car} was called on @code{3}. After
77 @samp{restarts} is a list of all the ways that we can restart
78 execution after this error. In this case, both options return to
79 top-level. After printing its banner, the debugger prints the current
80 frame and the debugger prompt.
82 When the debugger is invoked by a condition, ANSI mandates that the
83 value of @code{*debugger-hook*}, if any, be called with two arguments:
84 the condition that caused the debugger to be invoked and the previous
85 value of @code{*debugger-hook*}. When this happens,
86 @code{*debugger-hook*} is bound to NIL to prevent recursive
87 errors. However, ANSI also mandates that @code{*debugger-hook*} not be
88 invoked when the debugger is to be entered by the @code{break}
89 function. For users who wish to provide an alternate debugger
90 interface (and thus catch @code{break} entries into the debugger),
91 SBCL provides @code{sb-ext:*invoke-debugger-hook*}, which is invoked
92 during any entry into the debugger.
94 @include var-sb-ext-star-invoke-debugger-hook-star.texinfo
97 @node The Debugger Command Loop
98 @comment node-name, next, previous, up
99 @section The Debugger Command Loop
100 @cindex Evaluation, in the debugger
102 The debugger is an interactive read-eval-print loop much like the normal
103 top-level, but some symbols are interpreted as debugger commands instead
104 of being evaluated. A debugger command starts with the symbol name of
105 the command, possibly followed by some arguments on the same line. Some
106 commands prompt for additional input. Debugger commands can be
107 abbreviated by any unambiguous prefix: @command{help} can be typed as
108 @samp{h}, @samp{he}, etc. For convenience, some commands have
109 ambiguous one-letter abbreviations: @samp{f} for @command{frame}.
110 @comment FIXME: what does that last bit mean?
112 The package is not significant in debugger commands; any symbol with the
113 name of a debugger command will work. If you want to show the value of
114 a variable that happens also to be the name of a debugger command, you
115 can use the @command{list-locals} command or the @code{sb-debug:var}
116 function, or you can wrap the variable in a @code{progn} to hide it from
119 The debugger prompt is ``@code{@var{frame}]}'', where @var{frame} is
120 the number of the current frame. Frames are numbered starting from
121 zero at the top (most recent call), increasing down to the bottom.
122 The current frame is the frame that commands refer to. The current
123 frame also provides the lexical environment for evaluation of
126 The debugger evaluates forms in the lexical environment of the
127 functions being debugged. The debugger can only access variables.
128 You can't @code{go} or @code{return-from} into a function, and you
129 can't call local functions. Special variable references are evaluated
130 with their current value (the innermost binding around the debugger
131 invocation) -- you don't get the value that the special had in the
132 current frame. For more information on debugger variable access, see
133 @ref{Variable Access}.
136 @node Controlling Printing in the Debugger
137 @comment node-name, next, previous, up
138 @section Controlling Printing in the Debugger
140 In the debugger, it is possible to override the printing behaviour of
143 @include var-sb-ext-star-debug-print-variable-alist-star.texinfo
146 @comment node-name, next, previous, up
147 @section Stack Frames
150 A @dfn{stack frame} is the run-time representation of a call to a
151 function; the frame stores the state that a function needs to remember
152 what it is doing. Frames have:
157 @dfn{variables} (@pxref{Variable Access}), which are the values being operated
161 @dfn{arguments} to the call (which are really just particularly
162 interesting variables), and
165 a current location (@pxref{Source Location Printing}), which is the place in
166 the program where the function was running when it stopped to call
167 another function, or because of an interrupt or error.
174 * How Arguments are Printed::
177 * Debug Tail Recursion::
178 * Unknown Locations and Interrupts::
182 @comment node-name, next, previous, up
183 @subsection Stack Motion
185 These commands move to a new stack frame and print the name of the
186 function and the values of its arguments in the style of a Lisp
189 @deffn {Debugger Command} up
190 Move up to the next higher frame. More recent function calls are
191 considered to be higher on the stack.
194 @deffn {Debugger Command} down
195 Move down to the next lower frame.
198 @deffn {Debugger Command} top
199 Move to the highest frame, that is, the frame where the debugger was
203 @deffn {Debugger Command} bottom
204 Move to the lowest frame.
207 @deffn {Debugger Command} frame [@var{n}]
208 Move to the frame with the specified number. Prompts for the number if not
209 supplied. The frame with number 0 is the frame where the debugger
214 @node How Arguments are Printed
215 @comment node-name, next, previous, up
216 @subsection How Arguments are Printed
218 A frame is printed to look like a function call, but with the actual
219 argument values in the argument positions. So the frame for this call
226 would look like this:
232 All keyword and optional arguments are displayed with their actual
233 values; if the corresponding argument was not supplied, the value will
234 be the default. So this call:
240 would look like this:
249 (string-upcase "test case")
252 would look like this:
255 (STRING-UPCASE "test case" :START 0 :END NIL)
258 The arguments to a function call are displayed by accessing the
259 argument variables. Although those variables are initialized to the
260 actual argument values, they can be set inside the function; in this
261 case the new value will be displayed.
263 @code{&rest} arguments are handled somewhat differently. The value of
264 the rest argument variable is displayed as the spread-out arguments to
268 (format t "~A is a ~A." "This" 'test)
271 would look like this:
274 (FORMAT T "~A is a ~A." "This" 'TEST)
277 Rest arguments cause an exception to the normal display of keyword
278 arguments in functions that have both @code{&rest} and @code{&key}
279 arguments. In this case, the keyword argument variables are not
280 displayed at all; the rest arg is displayed instead. So for these
281 functions, only the keywords actually supplied will be shown, and the
282 values displayed will be the argument values, not values of the
283 (possibly modified) variables.
285 If the variable for an argument is never referenced by the function,
286 it will be deleted. The variable value is then unavailable, so the
287 debugger prints @samp{#<unused-arg>} instead of the value. Similarly,
288 if for any of a number of reasons the value of the variable is
289 unavailable or not known to be available (@pxref{Variable Access}),
290 then @samp{#<unavailable-arg>} will be printed instead of the argument
293 @vindex *debug-print-variable-alist*
294 Printing of argument values is controlled by
295 @code{*debug-print-variable-alist*}. @xref{Controlling Printing in
300 @comment node-name, next, previous, up
301 @subsection Function Names
303 If a function is defined by @code{defun}, @code{labels}, or
304 @code{flet}, then the debugger will print the actual function name
305 after the open parenthesis, like:
308 (STRING-UPCASE "test case" :START 0 :END NIL)
309 ((SETF AREF) #\a "for" 1)
312 Otherwise, the function name is a string, and will be printed in
317 ("DEFMACRO DO" (DO ((I 0 (1+ I))) ((= I 13))) NIL)
318 ("SETQ *GC-NOTIFY-BEFORE*")
321 This string name is derived from the @code{def@var{mumble}} form
322 that encloses or expanded into the lambda, or the outermost enclosing
323 form if there is no @code{def@var{mumble}}.
327 @comment node-name, next, previous, up
328 @subsection Funny Frames
329 @cindex External entry points
330 @cindex Entry points, external
331 @cindex Block compilation, debugger implications
332 @cindex External, stack frame kind
333 @cindex Optional, stack frame kind
334 @cindex Cleanup, stack frame kind
336 Sometimes the evaluator introduces new functions that are used to
337 implement a user function, but are not directly specified in the
338 source. The main place this is done is for checking argument type and
339 syntax. Usually these functions do their thing and then go away, and
340 thus are not seen on the stack in the debugger. But when you get some
341 sort of error during lambda-list processing, you end up in the
342 debugger on one of these funny frames.
344 These funny frames are flagged by printing
345 ``@code{[@var{keyword}]}'' after the parentheses. For example,
361 (string-upcase "test case" :end)
364 would look like this:
367 ("SB!INT:&MORE processing" "test case" 1053984 1)[:OPTIONAL]
370 As you can see, these frames have only a vague resemblance to the
371 original call. Fortunately, the error message displayed when you
372 enter the debugger will usually tell you what problem is (in these
373 cases, too many arguments and odd keyword arguments.) Also, if you go
374 down the stack to the frame for the calling function, you can display
375 the original source. @xref{Source Location Printing}.
377 @c FIXME: is the block-compilation part correct for SBCL?
379 With recursive or block compiled functions, an @code{:EXTERNAL} frame
380 may appear before the frame representing the first call to the
381 recursive function or entry to the compiled block. This is a
382 consequence of the way the compiler does block compilation: there is
383 nothing odd with your program. You will also see @code{:CLEANUP}
384 frames during the execution of @code{unwind-protect} cleanup
385 code. Note that inline expansion and open-coding affect what frames
386 are present in the debugger, see @ref{Debugger Policy Control}.
387 @comment FIXME: link here to section about open coding once it exists.
391 @node Debug Tail Recursion
392 @comment node-name, next, previous, up
393 @subsection Debug Tail Recursion
394 @cindex Tail recursion
395 @cindex Recursion, tail
397 Both the compiler and the interpreter are ``properly tail recursive.''
398 If a function call is in a tail-recursive position, the stack frame
399 will be deallocated @emph{at the time of the call}, rather than after
400 the call returns. Consider this backtrace:
407 Because of tail recursion, it is not necessarily the case that
408 @code{FOO} directly called @code{BAR}. It may be that @code{FOO}
409 called some other function @code{FOO2} which then called @code{BAR}
410 tail-recursively, as in this example:
426 Usually the elimination of tail-recursive frames makes debugging more
427 pleasant, since theses frames are mostly uninformative. If there is
428 any doubt about how one function called another, it can usually be
429 eliminated by finding the source location in the calling frame.
430 @xref{Source Location Printing}.
432 The elimination of tail-recursive frames can be prevented by disabling
433 tail-recursion optimization, which happens when the @code{debug}
434 optimization quality is greater than @code{2}.
435 @xref{Debugger Policy Control}.
437 @comment FIXME: reinstate this link once the chapter is in the manual.
438 @c For a more thorough discussion of tail recursion, @ref{tail-recursion}.
441 @node Unknown Locations and Interrupts
442 @comment node-name, next, previous, up
443 @subsection Unknown Locations and Interrupts
444 @cindex Unknown code locations
445 @cindex Locations, unknown
447 @cindex Errors, run-time
449 The debugger operates using special debugging information attached to
450 the compiled code. This debug information tells the debugger what it
451 needs to know about the locations in the code where the debugger can
452 be invoked. If the debugger somehow encounters a location not
453 described in the debug information, then it is said to be
454 @dfn{unknown}. If the code location for a frame is unknown, then some
455 variables may be inaccessible, and the source location cannot be
458 There are three reasons why a code location could be unknown:
463 There is inadequate debug information due to the value of the @code{debug}
464 optimization quality. @xref{Debugger Policy Control}.
467 The debugger was entered because of an interrupt such as @key{C-c}.
470 A hardware error such as ``@samp{bus error}'' occurred in code that was
471 compiled unsafely due to the value of the @code{safety} optimization
473 @comment FIXME: reinstate link when section on optimize qualities exists.
474 @c @xref{optimize-declaration}.
478 In the last two cases, the values of argument variables are
479 accessible, but may be incorrect. For more details on when variable
480 values are accessible, @ref{Variable Value Availability}.
482 It is possible for an interrupt to happen when a function call or
483 return is in progress. The debugger may then flame out with some
484 obscure error or insist that the bottom of the stack has been reached,
485 when the real problem is that the current stack frame can't be
486 located. If this happens, return from the interrupt and try again.
489 @node Variable Access
490 @comment node-name, next, previous, up
491 @section Variable Access
492 @cindex Debug variables
493 @cindex Variables, debugger access
495 There are two ways to access the current frame's local variables in
496 the debugger: @command{list-locals} and @code{sb-debug:var}.
498 The debugger doesn't really understand lexical scoping; it has just
499 one namespace for all the variables in the current stack frame. If a
500 symbol is the name of multiple variables in the same function, then
501 the reference appears ambiguous, even though lexical scoping specifies
502 which value is visible at any given source location. If the scopes of
503 the two variables are not nested, then the debugger can resolve the
504 ambiguity by observing that only one variable is accessible.
506 When there are ambiguous variables, the evaluator assigns each one a
507 small integer identifier. The @code{sb-debug:var} function uses this
508 identifier to distinguish between ambiguous variables. The
509 @command{list-locals} command prints the identifier. In the
510 following example, there are two variables named @code{X}. The first
511 one has identifier 0 (which is not printed), the second one has
519 @deffn {Debugger Command} list-locals [@var{prefix}]
520 This command prints the name and value of all variables in the current
521 frame whose name has the specified @var{prefix}. @var{prefix} may be
522 a string or a symbol. If no @var{prefix} is given, then all available
523 variables are printed. If a variable has a potentially ambiguous
524 name, then the name is printed with a ``@code{#@var{identifier}}''
525 suffix, where @var{identifier} is the small integer used to make the
529 @defun sb-debug:var @var{name} &optional @var{identifier}
530 This function returns the value of the variable in the current frame
531 with the specified @var{name}. If supplied, @var{identifier}
532 determines which value to return when there are ambiguous variables.
534 When @var{name} is a symbol, it is interpreted as the symbol name of
535 the variable, i.e. the package is significant. If @var{name} is an
536 uninterned symbol (gensym), then return the value of the uninterned
537 variable with the same name. If @var{name} is a string,
538 @code{sb-debug:var} interprets it as the prefix of a variable name
539 that must unambiguously complete to the name of a valid variable.
541 @var{identifier} is used to disambiguate the variable name; use
542 @command{list-locals} to find out the identifiers.
547 * Variable Value Availability::
548 * Note On Lexical Variable Access::
551 @node Variable Value Availability
552 @comment node-name, next, previous, up
553 @subsection Variable Value Availability
554 @cindex Availability of debug variables
555 @cindex Validity of debug variables
556 @cindex Debug optimization quality
558 The value of a variable may be unavailable to the debugger in portions
559 of the program where Lisp says that the variable is defined. If a
560 variable value is not available, the debugger will not let you read or
561 write that variable. With one exception, the debugger will never
562 display an incorrect value for a variable. Rather than displaying
563 incorrect values, the debugger tells you the value is unavailable.
565 The one exception is this: if you interrupt (e.g., with @key{C-c}) or
566 if there is an unexpected hardware error such as ``@samp{bus error}''
567 (which should only happen in unsafe code), then the values displayed
568 for arguments to the interrupted frame might be
569 incorrect.@footnote{Since the location of an interrupt or hardware
570 error will always be an unknown location, non-argument variable values
571 will never be available in the interrupted frame. @xref{Unknown
572 Locations and Interrupts}.} This exception applies only to the
573 interrupted frame: any frame farther down the stack will be fine.
575 The value of a variable may be unavailable for these reasons:
580 The value of the @code{debug} optimization quality may have omitted debug
581 information needed to determine whether the variable is available.
582 Unless a variable is an argument, its value will only be available when
583 @code{debug} is at least @code{2}.
586 The compiler did lifetime analysis and determined that the value was no longer
587 needed, even though its scope had not been exited. Lifetime analysis is
588 inhibited when the @code{debug} optimization quality is @code{3}.
591 The variable's name is an uninterned symbol (gensym). To save space, the
592 compiler only dumps debug information about uninterned variables when the
593 @code{debug} optimization quality is @code{3}.
596 The frame's location is unknown (@pxref{Unknown Locations and
597 Interrupts}) because the debugger was entered due to an interrupt or
598 unexpected hardware error. Under these conditions the values of
599 arguments will be available, but might be incorrect. This is the
600 exception mentioned above.
603 The variable (or the code referencing it) was optimized out
604 of existence. Variables with no reads are always optimized away. The
605 degree to which the compiler deletes variables will depend on the
606 value of the @code{compilation-speed} optimization quality, but most
607 source-level optimizations are done under all compilation policies.
610 The variable is never set and its definition looks like
615 In this case, @code{var1} is substituted with @code{var2}.
618 The variable is never set and is referenced exactly once. In this
619 case, the reference is substituted with the variable initial value.
623 Since it is especially useful to be able to get the arguments to a
624 function, argument variables are treated specially when the
625 @code{speed} optimization quality is less than @code{3} and the
626 @code{debug} quality is at least @code{1}. With this compilation
627 policy, the values of argument variables are almost always available
628 everywhere in the function, even at unknown locations. For
629 non-argument variables, @code{debug} must be at least @code{2} for
630 values to be available, and even then, values are only available at
634 @node Note On Lexical Variable Access
635 @comment node-name, next, previous, up
636 @subsection Note On Lexical Variable Access
638 When the debugger command loop establishes variable bindings for
639 available variables, these variable bindings have lexical scope and
640 dynamic extent.@footnote{The variable bindings are actually created
641 using the Lisp @code{symbol-macrolet} special form.} You can close
642 over them, but such closures can't be used as upward funargs.
644 You can also set local variables using @code{setq}, but if the
645 variable was closed over in the original source and never set, then
646 setting the variable in the debugger may not change the value in all
647 the functions the variable is defined in. Another risk of setting
648 variables is that you may assign a value of a type that the compiler
649 proved the variable could never take on. This may result in bad
653 @node Source Location Printing
654 @comment node-name, next, previous, up
655 @section Source Location Printing
656 @cindex Source location printing, debugger
658 One of the debugger's capabilities is source level debugging of
659 compiled code. These commands display the source location for the
662 @deffn {Debugger Command} source [@var{context}]
663 This command displays the file that the current frame's function was
664 defined from (if it was defined from a file), and then the source form
665 responsible for generating the code that the current frame was
666 executing. If @var{context} is specified, then it is an integer
667 specifying the number of enclosing levels of list structure to print.
670 The source form for a location in the code is the innermost list present
671 in the original source that encloses the form responsible for generating
672 that code. If the actual source form is not a list, then some enclosing
673 list will be printed. For example, if the source form was a reference
674 to the variable @code{*some-random-special*}, then the innermost
675 enclosing evaluated form will be printed. Here are some possible
679 (let ((a *some-random-special*))
682 (+ *some-random-special* ...)
685 If the code at a location was generated from the expansion of a macro
686 or a source-level compiler optimization, then the form in the original
687 source that expanded into that code will be printed. Suppose the file
688 @file{/usr/me/mystuff.lisp} looked like this:
699 If @code{foo} has called @code{myfun}, and is waiting for it to
700 return, then the @command{source} command would print:
703 ; File: /usr/me/mystuff.lisp
708 Note that the macro use was printed, not the actual function call form,
711 If enclosing source is printed by giving an argument to
712 @command{source} or @command{vsource}, then the actual source form is
713 marked by wrapping it in a list whose first element is
714 @samp{#:***HERE***}. In the previous example, @code{source 1} would
718 ; File: /usr/me/mystuff.lisp
728 * How the Source is Found::
729 * Source Location Availability::
732 @node How the Source is Found
733 @comment node-name, next, previous, up
734 @subsection How the Source is Found
736 If the code was defined from Lisp by @code{compile} or
737 @code{eval}, then the source can always be reliably located. If the
738 code was defined from a @file{fasl} file created by
739 @code{compile-file}, then the debugger gets the source forms it
740 prints by reading them from the original source file. This is a
741 potential problem, since the source file might have moved or changed
742 since the time it was compiled.
744 The source file is opened using the @code{truename} of the source file
745 pathname originally given to the compiler. This is an absolute pathname
746 with all logical names and symbolic links expanded. If the file can't
747 be located using this name, then the debugger gives up and signals an
750 If the source file can be found, but has been modified since the time it was
751 compiled, the debugger prints this warning:
754 ; File has been modified since compilation:
756 ; Using form offset instead of character position.
759 where @var{filename} is the name of the source file. It then proceeds
760 using a robust but not foolproof heuristic for locating the source.
761 This heuristic works if:
766 No top-level forms before the top-level form containing the source
767 have been added or deleted, and
770 The top-level form containing the source has not been modified much.
771 (More precisely, none of the list forms beginning before the source
772 form have been added or deleted.)
776 If the heuristic doesn't work, the displayed source will be wrong, but will
777 probably be near the actual source. If the ``shape'' of the top-level form in
778 the source file is too different from the original form, then an error will be
779 signaled. When the heuristic is used, the source location commands are
782 Source location printing can also be confused if (after the source was
783 compiled) a read-macro you used in the code was redefined to expand
784 into something different, or if a read-macro ever returns the same
785 @code{eq} list twice. If you don't define read macros and don't use
786 @code{##} in perverted ways, you don't need to worry about this.
789 @node Source Location Availability
790 @comment node-name, next, previous, up
791 @subsection Source Location Availability
792 @cindex Debug optimization quality
794 @cindex Block, start location
796 Source location information is only available when the @code{debug}
797 optimization quality is at least @code{2}. If source location
798 information is unavailable, the source commands will give an error
801 If source location information is available, but the source location
802 is unknown because of an interrupt or unexpected hardware error
803 (@pxref{Unknown Locations and Interrupts}), then the command will
807 Unknown location: using block start.
810 and then proceed to print the source location for the start of the
811 @emph{basic block} enclosing the code location. It's a bit
812 complicated to explain exactly what a basic block is, but here are
813 some properties of the block start location:
817 @item The block start location may be the same as the true location.
819 @item The block start location will never be later in the
820 program's flow of control than the true location.
822 @item No conditional control structures (such as @code{if},
823 @code{cond}, @code{or}) will intervene between the block start and the
824 true location (but note that some conditionals present in the original
825 source could be optimized away.) Function calls @emph{do not} end
828 @item The head of a loop will be the start of a block.
830 @item The programming language concept of ``block structure'' and the
831 Lisp @code{block} special form are totally unrelated to the compiler's
836 In other words, the true location lies between the printed location and the
837 next conditional (but watch out because the compiler may have changed the
841 @node Debugger Policy Control
842 @comment node-name, next, previous, up
843 @section Debugger Policy Control
844 @cindex Policy, debugger
845 @cindex Debug optimization quality
846 @cindex Optimize declaration
847 @cindex Inline expansion
848 @cindex Semi-inline expansion
850 The compilation policy specified by @code{optimize} declarations
851 affects the behavior seen in the debugger. The @code{debug} quality
852 directly affects the debugger by controlling the amount of debugger
853 information dumped. Other optimization qualities have indirect but
854 observable effects due to changes in the way compilation is done.
856 Unlike the other optimization qualities (which are compared in relative value
857 to evaluate tradeoffs), the @code{debug} optimization quality is directly
858 translated to a level of debug information. This absolute interpretation
859 allows the user to count on a particular amount of debug information being
860 available even when the values of the other qualities are changed during
861 compilation. These are the levels of debug information that correspond to the
862 values of the @code{debug} quality:
867 Only the function name and enough information to allow the stack to
871 Any level greater than @code{0} gives level @code{0} plus all argument
872 variables. Values will only be accessible if the argument variable is
873 never set and @code{speed} is not @code{3}. SBCL allows any real
874 value for optimization qualities. It may be useful to specify
875 @code{0.5} to get backtrace argument display without argument
879 Level @code{1} provides argument documentation (printed arglists) and
880 derived argument/result type information. This makes @code{describe}
881 more informative, and allows the compiler to do compile-time argument
882 count and type checking for any calls compiled at run-time. This is
886 Level @code{1} plus all interned local variables, source location
887 information, and lifetime information that tells the debugger when
888 arguments are available (even when @code{speed} is @code{3} or the
892 Any level greater than @code{2} gives level @code{2} and in addition
893 disables tail-call optimization, so that the backtrace will contain
894 frames for all invoked functions, even those in tail positions.
897 Level @code{2} plus all uninterned variables. In addition, lifetime
898 analysis is disabled (even when @code{speed} is @code{3}), ensuring
899 that all variable values are available at any known location within
900 the scope of the binding. This has a speed penalty in addition to the
901 obvious space penalty.
903 @item > (max speed space)
904 If @code{debug} is greater than both @code{speed} and @code{space},
905 the command @command{return} can be used to continue execution by
906 returning a value from the current stack frame.
908 If @code{debug} is also at least 2, then the code is @emph{partially
909 steppable}. If @code{debug} is 3, the code is @emph{fully steppable}.
910 @xref{Single Stepping}, for details.
914 As you can see, if the @code{speed} quality is @code{3}, debugger performance is
915 degraded. This effect comes from the elimination of argument variable
916 special-casing (@pxref{Variable Value Availability}). Some degree of
917 speed/debuggability tradeoff is unavoidable, but the effect is not too drastic
918 when @code{debug} is at least @code{2}.
920 In addition to @code{inline} and @code{notinline} declarations, the
921 relative values of the @code{speed} and @code{space} qualities also
922 change whether functions are inline expanded.
923 @comment FIXME: link to section about inline expansion when it exists
924 @c (\pxlref{inline-expansion}.)
925 If a function is inline expanded, then
926 there will be no frame to represent the call, and the arguments will
927 be treated like any other local variable. Functions may also be
928 ``semi-inline'', in which case there is a frame to represent the call,
929 but the call is to an optimized local version of the function, not to
930 the original function.
933 @node Exiting Commands
934 @comment node-name, next, previous, up
935 @section Exiting Commands
937 These commands get you out of the debugger.
939 @deffn {Debugger Command} toplevel
943 @deffn {Debugger Command} restart [@var{n}]
944 Invokes the @var{n}th restart case as displayed by the @code{error}
945 command. If @var{n} is not specified, the available restart cases are
949 @deffn {Debugger Command} continue
950 Calls @code{continue} on the condition given to @code{debug}. If there is no
951 restart case named @var{continue}, then an error is signaled.
954 @deffn {Debugger Command} abort
955 Calls @code{abort} on the condition given to @code{debug}. This is
956 useful for popping debug command loop levels or aborting to top level,
960 @deffn {Debugger Command} return @var{value}
961 Returns @var{value} from the current stack frame. This command is
962 available when the @code{debug} optimization quality is greater than
963 both @code{speed} and @code{space}. Care must be taken that the value
964 is of the same type as SBCL expects the stack frame to return.
968 @node Information Commands
969 @comment node-name, next, previous, up
970 @section Information Commands
972 Most of these commands print information about the current frame or
973 function, but a few show general information.
975 @deffn {Debugger Command} help
976 @deffnx {Debugger Command} ?
977 Displays a synopsis of debugger commands.
980 @deffn {Debugger Command} describe
981 Calls @code{describe} on the current function and displays the number of
985 @deffn {Debugger Command} print
986 Displays the current function call as it would be displayed by moving to
990 @deffn {Debugger Command} error
991 Prints the condition given to @code{invoke-debugger} and the active
995 @deffn {Debugger Command} backtrace [@var{n}]
996 Displays all the frames from the current to the bottom. Only shows
997 @var{n} frames if specified. The printing is controlled by
998 @code{*debug-print-variable-alist*}.
1001 @deffn {Debugger Command} step
1002 Selects the @code{continue} restart if one exists and starts single stepping.
1003 @xref{Single Stepping}.
1006 @c The new instrumentation based single stepper doesn't support
1007 @c the following commands, but BREAKPOINT at least should be
1008 @c resurrectable via (TRACE FOO :BREAK T).
1010 @c @cindex Breakpoints
1012 @c SBCL supports setting of breakpoints inside compiled functions and
1013 @c stepping of compiled code. Breakpoints can only be set at known
1014 @c locations (@pxref{Unknown Locations and Interrupts}), so these
1015 @c commands are largely useless unless the @code{debug} optimize quality
1016 @c is at least @code{2} (@pxref{Debugger Policy Control}). These
1017 @c commands manipulate breakpoints:
1019 @c @deffn {Debugger Command} breakpoint @var{location} [@var{option} @var{value}]*
1020 @c Set a breakpoint in some function. @var{location} may be an integer
1021 @c code location number (as displayed by @command{list-locations}) or a
1022 @c keyword. The keyword can be used to indicate setting a breakpoint at
1023 @c the function start (@code{:start}, @code{:s}) or function end
1024 @c (@code{:end}, @code{:e}). The @command{breakpoint} command has
1025 @c @code{:condition}, @code{:break}, @code{:print} and @code{:function}
1026 @c options which work similarly to the @code{trace} options.
1029 @c @deffn {Debugger Command} list-locations [@var{function}]
1030 @c @deffnx {Debugger Command} ll [@var{function}]
1031 @c List all the code locations in the current frame's function, or in
1032 @c @var{function} if it is supplied. The display format is the code
1033 @c location number, a colon and then the source form for that location:
1039 @c If consecutive locations have the same source, then a numeric range
1040 @c like @code{3-5:} will be printed. For example, a default function
1041 @c call has a known location both immediately before and after the call,
1042 @c which would result in two code locations with the same source. The
1043 @c listed function becomes the new default function for breakpoint
1044 @c setting (via the @command{breakpoint}) command.
1047 @c @deffn {Debugger Command} list-breakpoints
1048 @c @deffnx {Debugger Command} lb
1049 @c List all currently active breakpoints with their breakpoint number.
1052 @c @deffn {Debugger Command} delete-breakpoint [@var{number}]
1053 @c @deffnx {Debugger Command} db [@var{number}]
1054 @c Delete a breakpoint specified by its breakpoint number. If no number
1055 @c is specified, delete all breakpoints.
1059 @c * Breakpoint Example::
1062 @c @node Breakpoint Example, , Breakpoint Commands, Breakpoint Commands
1063 @c @comment node-name, next, previous, up
1064 @c @subsection Breakpoint Example
1066 @c Consider this definition of the factorial function:
1072 @c (* n (! (1- n)))))
1075 @c This debugger session demonstrates the use of breakpoints:
1078 @c * (break) ; invoke debugger
1080 @c debugger invoked on a SIMPLE-CONDITION in thread 11184: break
1082 @c restarts (invokable by number or by possibly-abbreviated name):
1083 @c 0: [CONTINUE] Return from BREAK.
1084 @c 1: [ABORT ] Reduce debugger level (leaving debugger, returning to toplevel).
1085 @c 2: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
1086 @c ("varargs entry for top level local call BREAK" "break")
1089 @c 0-1: (SB-INT:NAMED-LAMBDA ! (N) (BLOCK ! (IF (ZEROP N) 1 (* N (! #)))))
1090 @c 2: (BLOCK ! (IF (ZEROP N) 1 (* N (! (1- N)))))
1092 @c 4: (* N (! (1- N)))
1095 @c 7-8: (* N (! (1- N)))
1096 @c 9-10: (IF (ZEROP N) 1 (* N (! (1- N))))
1104 @c FIXME: SBCL errored out, and not in the expected way ... Copying the
1105 @c output verbatim from the CMUCL manual for now.
1107 @c common-lisp-user> (! 10) ; Call the function
1112 @c 0: [CONTINUE] Return from BREAK.
1113 @c 1: [ABORT ] Return to Top-Level.
1115 @c Debug (type H for help)
1117 @c (! 10) ; We are now in first call (arg 10) before the multiply
1118 @c Source: (* N (! (1- N)))
1123 @c (! 10) ; We have finished evaluation of (1- n)
1130 @c 0: [CONTINUE] Return from BREAK.
1131 @c 1: [ABORT ] Return to Top-Level.
1133 @c Debug (type H for help)
1135 @c (! 9) ; We hit the breakpoint in the recursive call
1136 @c Source: (* N (! (1- N)))
1141 @node Function Tracing
1142 @comment node-name, next, previous, up
1143 @section Function Tracing
1145 @cindex Function, tracing
1147 The tracer causes selected functions to print their arguments and
1148 their results whenever they are called. Options allow conditional
1149 printing of the trace information and conditional breakpoints on
1150 function entry or exit.
1152 @include macro-common-lisp-trace.texinfo
1154 @include macro-common-lisp-untrace.texinfo
1156 @include var-sb-debug-star-trace-indentation-step-star.texinfo
1158 @include var-sb-debug-star-max-trace-indentation-star.texinfo
1160 @include var-sb-debug-star-trace-encapsulate-default-star.texinfo
1162 @include var-sb-debug-star-trace-values-star.texinfo
1164 @comment FIXME rudi 2004-03-26: encapsulate is (per TODO file as of
1165 @comment 0.8.9) in a state of flux. When it's sorted out, revive the
1166 @comment cmucl documentation.
1168 @node Single Stepping
1169 @comment node-name, next, previous, up
1170 @section Single Stepping
1172 @cindex Single Stepping
1174 SBCL includes an instrumentation based single-stepper for compiled
1175 code, that can be invoked via the @code{step} macro, or from within
1176 the debugger. @xref{Debugger Policy Control}, for details on enabling
1177 stepping for compiled code.
1179 Compiled code can be unsteppable, partially steppable, or fully steppable.
1184 Single stepping is not possible.
1186 @item Partially steppable
1187 Single stepping is possible at sequential function call granularity:
1188 nested function calls cannot be stepped into, and no intermediate
1189 values are available.
1191 @item Fully steppable
1192 Single stepping is possible at individual function call argument
1193 granularity, nested calls can be stepped into, and intermediate values
1198 @include macro-common-lisp-step.texinfo