1 @node The Debugger, Efficiency, The Compiler, Top
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, The Debugger Command Loop, The Debugger, 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, Controlling Printing in the Debugger, Starting the Debugger, The Debugger
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}.
96 The package is not significant in debugger commands; any symbol with the
97 name of a debugger command will work. If you want to show the value of
98 a variable that happens also to be the name of a debugger command, you
99 can use the @command{list-locals} command or the @code{sb-debug:var}
100 function, or you can wrap the variable in a @code{progn} to hide it from
103 The debugger prompt is ``@code{@var{frame}]}'', where @var{frame} is
104 the number of the current frame. Frames are numbered starting from
105 zero at the top (most recent call), increasing down to the bottom.
106 The current frame is the frame that commands refer to. The current
107 frame also provides the lexical environment for evaluation of
110 The debugger evaluates forms in the lexical environment of the
111 functions being debugged. The debugger can only access variables.
112 You can't @code{go} or @code{return-from} into a function, and you
113 can't call local functions. Special variable references are evaluated
114 with their current value (the innermost binding around the debugger
115 invocation) -- you don't get the value that the special had in the
116 current frame. For more information on debugger variable access, see
117 @ref{Variable Access}.
120 @node Controlling Printing in the Debugger, Stack Frames, The Debugger Command Loop, The Debugger
121 @comment node-name, next, previous, up
122 @section Controlling Printing in the Debugger
124 In the debugger, it is possible to override the printing behaviour of
127 @defvr {Variable} *debug-print-variable-alist*
129 An association list describing new bindings for special variables
130 (typically *PRINT-FOO* variables) to be used within the debugger, e.g.
132 ((*PRINT-LENGTH* . 10) (*PRINT-LEVEL* . 6) (*PRINT-PRETTY* . NIL))
134 The variables in the @code{car} position are bound to the values in
135 the @code{cdr} during the execution of some debug commands. When
136 evaluating arbitrary expressions in the debugger, the normal values of
137 the printer control variables are in effect. @c FIXME: is this correct?
138 @code{*debug-print-variable-alist*} does not contain any bindings
143 @node Stack Frames, Variable Access, Controlling Printing in the Debugger, The Debugger
144 @comment node-name, next, previous, up
145 @section Stack Frames
148 A @dfn{stack frame} is the run-time representation of a call to a
149 function; the frame stores the state that a function needs to remember
150 what it is doing. Frames have:
155 @dfn{Variables} (@pxref{Variable Access}), which are the values being operated
159 @dfn{Arguments} to the call (which are really just particularly
160 interesting variables), and
163 A current location (@pxref{Source Location Printing}), which is the place in
164 the program where the function was running when it stopped to call
165 another function, or because of an interrupt or error.
172 * How Arguments are Printed::
175 * Debug Tail Recursion::
176 * Unknown Locations and Interrupts::
179 @node Stack Motion, How Arguments are Printed, Stack Frames, Stack Frames
180 @comment node-name, next, previous, up
181 @subsection Stack Motion
183 These commands move to a new stack frame and print the name of the
184 function and the values of its arguments in the style of a Lisp
187 @deffn {Debugger Command} up
188 Move up to the next higher frame. More recent function calls are
189 considered to be higher on the stack.
192 @deffn {Debugger Command} down
193 Move down to the next lower frame.
196 @deffn {Debugger Command} top
197 Move to the highest frame, that is, the frame where the debugger was
201 @deffn {Debugger Command} bottom
202 Move to the lowest frame.
205 @deffn {Debugger Command} frame [@var{n}]
206 Move to the frame with the specified number. Prompts for the number if not
207 supplied. The frame with number 0 is the frame where the debugger
212 @node How Arguments are Printed, Function Names, Stack Motion, Stack Frames
213 @comment node-name, next, previous, up
214 @subsection How Arguments are Printed
216 A frame is printed to look like a function call, but with the actual
217 argument values in the argument positions. So the frame for this call
224 would look like this:
230 All keyword and optional arguments are displayed with their actual
231 values; if the corresponding argument was not supplied, the value will
232 be the default. So this call:
238 would look like this:
247 (string-upcase "test case")
250 would look like this:
253 (STRING-UPCASE "test case" :START 0 :END NIL)
256 The arguments to a function call are displayed by accessing the
257 argument variables. Although those variables are initialized to the
258 actual argument values, they can be set inside the function; in this
259 case the new value will be displayed.
261 @code{&rest} arguments are handled somewhat differently. The value of
262 the rest argument variable is displayed as the spread-out arguments to
266 (format t "~A is a ~A." "This" 'test)
269 would look like this:
272 (FORMAT T "~A is a ~A." "This" 'TEST)
275 Rest arguments cause an exception to the normal display of keyword
276 arguments in functions that have both @code{&rest} and @code{&key}
277 arguments. In this case, the keyword argument variables are not
278 displayed at all; the rest arg is displayed instead. So for these
279 functions, only the keywords actually supplied will be shown, and the
280 values displayed will be the argument values, not values of the
281 (possibly modified) variables.
283 If the variable for an argument is never referenced by the function,
284 it will be deleted. The variable value is then unavailable, so the
285 debugger prints @samp{#<unused-arg>} instead of the value. Similarly,
286 if for any of a number of reasons the value of the variable is
287 unavailable or not known to be available (@pxref{Variable Access}),
288 then @samp{#<unavailable-arg>} will be printed instead of the argument
291 Printing of argument values is controlled by
292 @code{*debug-print-variable-alist*}. @xref{Controlling Printing in
296 @node Function Names, Funny Frames, How Arguments are Printed, Stack Frames
297 @comment node-name, next, previous, up
298 @subsection Function Names
300 If a function is defined by @code{defun}, @code{labels}, or
301 @code{flet}, then the debugger will print the actual function name
302 after the open parenthesis, like:
305 (STRING-UPCASE "test case" :START 0 :END NIL)
306 ((SETF AREF) #\a "for" 1)
309 Otherwise, the function name is a string, and will be printed in
314 ("DEFMACRO DO" (DO ((I 0 (1+ I))) ((= I 13))) NIL)
315 ("SETQ *GC-NOTIFY-BEFORE*")
318 This string name is derived from the @code{def@var{mumble}} form
319 that encloses or expanded into the lambda, or the outermost enclosing
320 form if there is no @code{def@var{mumble}}.
323 @node Funny Frames, Debug Tail Recursion, Function Names, Stack Frames
324 @comment node-name, next, previous, up
325 @subsection Funny Frames
326 @cindex External entry points
327 @cindex Entry points, external
328 @cindex Block compilation, debugger implications
329 @cindex External, stack frame kind
330 @cindex Optional, stack frame kind
331 @cindex Cleanup, stack frame kind
333 Sometimes the evaluator introduces new functions that are used to
334 implement a user function, but are not directly specified in the
335 source. The main place this is done is for checking argument type and
336 syntax. Usually these functions do their thing and then go away, and
337 thus are not seen on the stack in the debugger. But when you get some
338 sort of error during lambda-list processing, you end up in the
339 debugger on one of these funny frames.
341 These funny frames are flagged by printing
342 ``@code{[@var{keyword}]}'' after the parentheses. For example,
358 (string-upcase "test case" :end)
361 would look like this:
364 ("SB!INT:&MORE processing" "test case" 1053984 1)[:OPTIONAL]
367 As you can see, these frames have only a vague resemblance to the
368 original call. Fortunately, the error message displayed when you
369 enter the debugger will usually tell you what problem is (in these
370 cases, too many arguments and odd keyword arguments.) Also, if you go
371 down the stack to the frame for the calling function, you can display
372 the original source. @xref{Source Location Printing}.
374 @c FIXME: is the block-compilation part correct for SBCL?
376 With recursive or block compiled functions, an @code{:EXTERNAL} frame
377 may appear before the frame representing the first call to the
378 recursive function or entry to the compiled block. This is a
379 consequence of the way the compiler does block compilation: there is
380 nothing odd with your program. You will also see @code{:CLEANUP}
381 frames during the execution of @code{unwind-protect} cleanup
382 code. Note that inline expansion and open-coding affect what frames
383 are present in the debugger, see @ref{Debugger Policy Control}.
384 @comment FIXME: link here to section about open coding once it exists.
388 @node Debug Tail Recursion, Unknown Locations and Interrupts, Funny Frames, Stack Frames
389 @comment node-name, next, previous, up
390 @subsection Debug Tail Recursion
391 @cindex Tail recursion
392 @cindex Recursion, tail
394 Both the compiler and the interpreter are ``properly tail recursive.''
395 If a function call is in a tail-recursive position, the stack frame
396 will be deallocated @emph{at the time of the call}, rather than after
397 the call returns. Consider this backtrace:
404 Because of tail recursion, it is not necessarily the case that
405 @code{FOO} directly called @code{BAR}. It may be that @code{FOO}
406 called some other function @code{FOO2} which then called @code{BAR}
407 tail-recursively, as in this example:
423 Usually the elimination of tail-recursive frames makes debugging more
424 pleasant, since theses frames are mostly uninformative. If there is
425 any doubt about how one function called another, it can usually be
426 eliminated by finding the source location in the calling frame.
427 @xref{Source Location Printing}.
429 The elimination of tail-recursive frames can be prevented by disabling
430 tail-recursion optimization, which happens when the @code{debug}
431 optimization quality is greater than @code{2}.
432 @xref{Debugger Policy Control}.
434 @comment FIXME: reinstate this link once the chapter is in the manual.
435 @c For a more thorough discussion of tail recursion, @ref{tail-recursion}.
438 @node Unknown Locations and Interrupts, , Debug Tail Recursion, Stack Frames
439 @comment node-name, next, previous, up
440 @subsection Unknown Locations and Interrupts
441 @cindex Unknown code locations
442 @cindex Locations, unknown
444 @cindex Errors, run-time
446 The debugger operates using special debugging information attached to
447 the compiled code. This debug information tells the debugger what it
448 needs to know about the locations in the code where the debugger can
449 be invoked. If the debugger somehow encounters a location not
450 described in the debug information, then it is said to be
451 @dfn{unknown}. If the code location for a frame is unknown, then some
452 variables may be inaccessible, and the source location cannot be
455 There are three reasons why a code location could be unknown:
460 There is inadequate debug information due to the value of the @code{debug}
461 optimization quality. @xref{Debugger Policy Control}.
464 The debugger was entered because of an interrupt such as @key{C-c}.
467 A hardware error such as ``@samp{bus error}'' occurred in code that was
468 compiled unsafely due to the value of the @code{safety} optimization
470 @comment FIXME: reinstate link when section on optimize qualities exists.
471 @c @xref{optimize-declaration}.
475 In the last two cases, the values of argument variables are
476 accessible, but may be incorrect. For more details on when variable
477 values are accessible, @ref{Variable Value Availability}.
479 It is possible for an interrupt to happen when a function call or
480 return is in progress. The debugger may then flame out with some
481 obscure error or insist that the bottom of the stack has been reached,
482 when the real problem is that the current stack frame can't be
483 located. If this happens, return from the interrupt and try again.
486 @node Variable Access, Source Location Printing, Stack Frames, The Debugger
487 @comment node-name, next, previous, up
488 @section Variable Access
489 @cindex Debug variables
490 @cindex Variables, debugger access
492 There are two ways to access the current frame's local variables in
493 the debugger: @command{list-locals} and @code{sb-debug:var}.
495 The debugger doesn't really understand lexical scoping; it has just
496 one namespace for all the variables in the current stack frame. If a
497 symbol is the name of multiple variables in the same function, then
498 the reference appears ambiguous, even though lexical scoping specifies
499 which value is visible at any given source location. If the scopes of
500 the two variables are not nested, then the debugger can resolve the
501 ambiguity by observing that only one variable is accessible.
503 When there are ambiguous variables, the evaluator assigns each one a
504 small integer identifier. The @code{sb-debug:var} function uses this
505 identifier to distinguish between ambiguous variables. The
506 @command{list-locals} command prints the identifier. In the
507 following example, there are two variables named @code{X}. The first
508 one has identifier 0 (which is not printed), the second one has
516 @deffn {Debugger Command} list-locals [@var{prefix}]
517 This command prints the name and value of all variables in the current
518 frame whose name has the specified @var{prefix}. @var{prefix} may be
519 a string or a symbol. If no @var{prefix} is given, then all available
520 variables are printed. If a variable has a potentially ambiguous
521 name, then the name is printed with a ``@code{#@var{identifier}}''
522 suffix, where @var{identifier} is the small integer used to make the
526 @defun sb-debug:var @var{name} &optional @var{identifier}
527 This function returns the value of the variable in the current frame
528 with the specified @var{name}. If supplied, @var{identifier}
529 determines which value to return when there are ambiguous variables.
531 When @var{name} is a symbol, it is interpreted as the symbol name of
532 the variable, i.e. the package is significant. If @var{name} is an
533 uninterned symbol (gensym), then return the value of the uninterned
534 variable with the same name. If @var{name} is a string,
535 @code{sb-debug:var} interprets it as the prefix of a variable name
536 that must unambiguously complete to the name of a valid variable.
538 @var{identifier} is used to disambiguate the variable name; use
539 @command{list-locals} to find out the identifiers.
544 * Variable Value Availability::
545 * Note On Lexical Variable Access::
548 @node Variable Value Availability, Note On Lexical Variable Access, Variable Access, Variable Access
549 @comment node-name, next, previous, up
550 @subsection Variable Value Availability
551 @cindex Availability of debug variables
552 @cindex Validity of debug variables
553 @cindex Debug optimization quality
555 The value of a variable may be unavailable to the debugger in portions
556 of the program where Lisp says that the variable is defined. If a
557 variable value is not available, the debugger will not let you read or
558 write that variable. With one exception, the debugger will never
559 display an incorrect value for a variable. Rather than displaying
560 incorrect values, the debugger tells you the value is unavailable.
562 The one exception is this: if you interrupt (e.g., with @key{C-c}) or
563 if there is an unexpected hardware error such as ``@samp{bus error}''
564 (which should only happen in unsafe code), then the values displayed
565 for arguments to the interrupted frame might be
566 incorrect.@footnote{Since the location of an interrupt or hardware
567 error will always be an unknown location, non-argument variable values
568 will never be available in the interrupted frame. @xref{Unknown
569 Locations and Interrupts}.} This exception applies only to the
570 interrupted frame: any frame farther down the stack will be fine.
572 The value of a variable may be unavailable for these reasons:
577 The value of the @code{debug} optimization quality may have omitted debug
578 information needed to determine whether the variable is available.
579 Unless a variable is an argument, its value will only be available when
580 @code{debug} is at least @code{2}.
583 The compiler did lifetime analysis and determined that the value was no longer
584 needed, even though its scope had not been exited. Lifetime analysis is
585 inhibited when the @code{debug} optimization quality is @code{3}.
588 The variable's name is an uninterned symbol (gensym). To save space, the
589 compiler only dumps debug information about uninterned variables when the
590 @code{debug} optimization quality is @code{3}.
593 The frame's location is unknown (@pxref{Unknown Locations and
594 Interrupts}) because the debugger was entered due to an interrupt or
595 unexpected hardware error. Under these conditions the values of
596 arguments will be available, but might be incorrect. This is the
597 exception mentioned above.
600 The variable (or the code referencing it) was optimized out
601 of existence. Variables with no reads are always optimized away. The
602 degree to which the compiler deletes variables will depend on the
603 value of the @code{compilation-speed} optimization quality, but most
604 source-level optimizations are done under all compilation policies.
607 The variable is never set and its definition looks like
612 In this case, @code{var1} is substituted with @code{var2}.
615 The variable is never set and is referenced exactly once. In this
616 case, the reference is substituted with the variable initial value.
620 Since it is especially useful to be able to get the arguments to a
621 function, argument variables are treated specially when the
622 @code{speed} optimization quality is less than @code{3} and the
623 @code{debug} quality is at least @code{1}. With this compilation
624 policy, the values of argument variables are almost always available
625 everywhere in the function, even at unknown locations. For
626 non-argument variables, @code{debug} must be at least @code{2} for
627 values to be available, and even then, values are only available at
631 @node Note On Lexical Variable Access, , Variable Value Availability, Variable Access
632 @comment node-name, next, previous, up
633 @subsection Note On Lexical Variable Access
635 When the debugger command loop establishes variable bindings for
636 available variables, these variable bindings have lexical scope and
637 dynamic extent.@footnote{The variable bindings are actually created
638 using the Lisp @code{symbol-macrolet} special form.} You can close
639 over them, but such closures can't be used as upward funargs.
641 You can also set local variables using @code{setq}, but if the
642 variable was closed over in the original source and never set, then
643 setting the variable in the debugger may not change the value in all
644 the functions the variable is defined in. Another risk of setting
645 variables is that you may assign a value of a type that the compiler
646 proved the variable could never take on. This may result in bad
650 @node Source Location Printing, Debugger Policy Control, Variable Access, The Debugger
651 @comment node-name, next, previous, up
652 @section Source Location Printing
653 @cindex Source location printing, debugger
655 One of the debugger's capabilities is source level debugging of
656 compiled code. These commands display the source location for the
659 @deffn {Debugger Command} source [@var{context}]
660 This command displays the file that the current frame's function was
661 defined from (if it was defined from a file), and then the source form
662 responsible for generating the code that the current frame was
663 executing. If @var{context} is specified, then it is an integer
664 specifying the number of enclosing levels of list structure to print.
667 The source form for a location in the code is the innermost list present
668 in the original source that encloses the form responsible for generating
669 that code. If the actual source form is not a list, then some enclosing
670 list will be printed. For example, if the source form was a reference
671 to the variable @code{*some-random-special*}, then the innermost
672 enclosing evaluated form will be printed. Here are some possible
676 (let ((a *some-random-special*))
679 (+ *some-random-special* ...)
682 If the code at a location was generated from the expansion of a macro
683 or a source-level compiler optimization, then the form in the original
684 source that expanded into that code will be printed. Suppose the file
685 @file{/usr/me/mystuff.lisp} looked like this:
696 If @code{foo} has called @code{myfun}, and is waiting for it to
697 return, then the @command{source} command would print:
700 ; File: /usr/me/mystuff.lisp
705 Note that the macro use was printed, not the actual function call form,
708 If enclosing source is printed by giving an argument to
709 @command{source} or @command{vsource}, then the actual source form is
710 marked by wrapping it in a list whose first element is
711 @samp{#:***HERE***}. In the previous example, @code{source 1} would
715 ; File: /usr/me/mystuff.lisp
725 * How the Source is Found::
726 * Source Location Availability::
729 @node How the Source is Found, Source Location Availability, Source Location Printing, Source Location Printing
730 @comment node-name, next, previous, up
731 @subsection How the Source is Found
733 If the code was defined from Lisp by @code{compile} or
734 @code{eval}, then the source can always be reliably located. If the
735 code was defined from a @file{fasl} file created by
736 @code{compile-file}, then the debugger gets the source forms it
737 prints by reading them from the original source file. This is a
738 potential problem, since the source file might have moved or changed
739 since the time it was compiled.
741 The source file is opened using the @code{truename} of the source file
742 pathname originally given to the compiler. This is an absolute pathname
743 with all logical names and symbolic links expanded. If the file can't
744 be located using this name, then the debugger gives up and signals an
747 If the source file can be found, but has been modified since the time it was
748 compiled, the debugger prints this warning:
751 ; File has been modified since compilation:
753 ; Using form offset instead of character position.
756 where @var{filename} is the name of the source file. It then proceeds
757 using a robust but not foolproof heuristic for locating the source.
758 This heuristic works if:
763 No top-level forms before the top-level form containing the source
764 have been added or deleted, and
767 The top-level form containing the source has not been modified much.
768 (More precisely, none of the list forms beginning before the source
769 form have been added or deleted.)
773 If the heuristic doesn't work, the displayed source will be wrong, but will
774 probably be near the actual source. If the ``shape'' of the top-level form in
775 the source file is too different from the original form, then an error will be
776 signaled. When the heuristic is used, the the source location commands are
779 Source location printing can also be confused if (after the source was
780 compiled) a read-macro you used in the code was redefined to expand
781 into something different, or if a read-macro ever returns the same
782 @code{eq} list twice. If you don't define read macros and don't use
783 @code{##} in perverted ways, you don't need to worry about this.
786 @node Source Location Availability, , How the Source is Found, Source Location Printing
787 @comment node-name, next, previous, up
788 @subsection Source Location Availability
789 @cindex Debug optimization quality
791 @cindex Block, start location
793 Source location information is only available when the @code{debug}
794 optimization quality is at least @code{2}. If source location
795 information is unavailable, the source commands will give an error
798 If source location information is available, but the source location
799 is unknown because of an interrupt or unexpected hardware error
800 (@pxref{Unknown Locations and Interrupts}), then the command will
804 Unknown location: using block start.
807 and then proceed to print the source location for the start of the
808 @emph{basic block} enclosing the code location. It's a bit
809 complicated to explain exactly what a basic block is, but here are
810 some properties of the block start location:
814 @item The block start location may be the same as the true location.
816 @item The block start location will never be later in the the
817 program's flow of control than the true location.
819 @item No conditional control structures (such as @code{if},
820 @code{cond}, @code{or}) will intervene between the block start and the
821 true location (but note that some conditionals present in the original
822 source could be optimized away.) Function calls @emph{do not} end
825 @item The head of a loop will be the start of a block.
827 @item The programming language concept of ``block structure'' and the
828 Lisp @code{block} special form are totally unrelated to the compiler's
833 In other words, the true location lies between the printed location and the
834 next conditional (but watch out because the compiler may have changed the
838 @node Debugger Policy Control, Exiting Commands, Source Location Printing, The Debugger
839 @comment node-name, next, previous, up
840 @section Debugger Policy Control
841 @cindex Policy, debugger
842 @cindex Debug optimization quality
843 @cindex Optimize declaration
844 @cindex Inline expansion
845 @cindex Semi-inline expansion
847 The compilation policy specified by @code{optimize} declarations
848 affects the behavior seen in the debugger. The @code{debug} quality
849 directly affects the debugger by controlling the amount of debugger
850 information dumped. Other optimization qualities have indirect but
851 observable effects due to changes in the way compilation is done.
853 Unlike the other optimization qualities (which are compared in relative value
854 to evaluate tradeoffs), the @code{debug} optimization quality is directly
855 translated to a level of debug information. This absolute interpretation
856 allows the user to count on a particular amount of debug information being
857 available even when the values of the other qualities are changed during
858 compilation. These are the levels of debug information that correspond to the
859 values of the @code{debug} quality:
864 Only the function name and enough information to allow the stack to
868 Any level greater than @code{0} gives level @code{0} plus all argument
869 variables. Values will only be accessible if the argument variable is
870 never set and @code{speed} is not @code{3}. SBCL allows any real
871 value for optimization qualities. It may be useful to specify
872 @code{0.5} to get backtrace argument display without argument
876 Level @code{1} provides argument documentation (printed arglists) and
877 derived argument/result type information. This makes @code{describe}
878 more informative, and allows the compiler to do compile-time argument
879 count and type checking for any calls compiled at run-time. This is
883 Level @code{1} plus all interned local variables, source location
884 information, and lifetime information that tells the debugger when
885 arguments are available (even when @code{speed} is @code{3} or the
889 Any level greater than @code{2} gives level @code{2} and in addition
890 disables tail-call optimization, so that the backtrace will contain
891 frames for all invoked functions, even those in tail positions.
894 Level @code{2} plus all uninterned variables. In addition, lifetime
895 analysis is disabled (even when @code{speed} is @code{3}), ensuring
896 that all variable values are available at any known location within
897 the scope of the binding. This has a speed penalty in addition to the
898 obvious space penalty.
900 @item > (max speed space)
901 If @code{debug} is greater than both @code{speed} and @code{space},
902 the command @command{return} can be used to continue execution by
903 returning a value from the current stack frame.
907 As you can see, if the @code{speed} quality is @code{3}, debugger performance is
908 degraded. This effect comes from the elimination of argument variable
909 special-casing (@pxref{Variable Value Availability}). Some degree of
910 speed/debuggability tradeoff is unavoidable, but the effect is not too drastic
911 when @code{debug} is at least @code{2}.
913 In addition to @code{inline} and @code{notinline} declarations, the
914 relative values of the @code{speed} and @code{space} qualities also
915 change whether functions are inline expanded.
916 @comment FIXME: link to section about inline expansion when it exists
917 @c (\pxlref{inline-expansion}.)
918 If a function is inline expanded, then
919 there will be no frame to represent the call, and the arguments will
920 be treated like any other local variable. Functions may also be
921 ``semi-inline'', in which case there is a frame to represent the call,
922 but the call is to an optimized local version of the function, not to
923 the original function.
926 @node Exiting Commands, Information Commands, Debugger Policy Control, The Debugger
927 @comment node-name, next, previous, up
928 @section Exiting Commands
930 These commands get you out of the debugger.
932 @deffn {Debugger Command} toplevel
936 @deffn {Debugger Command} restart [@var{n}]
937 Invokes the @var{n}th restart case as displayed by the @code{error}
938 command. If @var{n} is not specified, the available restart cases are
942 @deffn {Debugger Command} continue
943 Calls @code{continue} on the condition given to @code{debug}. If there is no
944 restart case named @var{continue}, then an error is signaled.
947 @deffn {Debugger Command} abort
948 Calls @code{abort} on the condition given to @code{debug}. This is
949 useful for popping debug command loop levels or aborting to top level,
953 @deffn {Debugger Command} return @var{value}
954 Returns @var{value} from the current stack frame. This command is
955 available when the @code{debug} optimization quality is greater than
956 both @code{speed} and @code{space}. Care must be taken that the value
957 is of the same type as SBCL expects the stack frame to return.
961 @node Information Commands, Function Tracing, Exiting Commands, The Debugger
962 @comment node-name, next, previous, up
963 @section Information Commands
965 Most of these commands print information about the current frame or
966 function, but a few show general information.
968 @deffn {Debugger Command} help
969 @deffnx {Debugger Command} ?
970 Displays a synopsis of debugger commands.
973 @deffn {Debugger Command} describe
974 Calls @code{describe} on the current function and displays the number of
978 @deffn {Debugger Command} print
979 Displays the current function call as it would be displayed by moving to
983 @deffn {Debugger Command} error
984 Prints the condition given to @code{invoke-debugger} and the active
988 @deffn {Debugger Command} backtrace [@var{n}]
989 Displays all the frames from the current to the bottom. Only shows
990 @var{n} frames if specified. The printing is controlled by @code{*debug-print-variable-alist*}.
993 @comment FIXME (rudi 2004-03-31): sbcl doesn't support breakpoints
994 @comment and stepping as of version 0.8.9. The `list-locations'
995 @comment command works, but executing a function leads to an error
996 @comment when a breakpoint is hit. When stepping works, the
997 @comment commented-out section below should be reinstated and the
998 @comment example output updated to correspont to sbcl's behaviour.
1000 @c @node Breakpoint Commands, , Information Commands, The Debugger
1001 @c @comment node-name, next, previous, up
1002 @c @section Breakpoint Commands
1003 @c @cindex Breakpoints
1005 @c SBCL supports setting of breakpoints inside compiled functions and
1006 @c stepping of compiled code. Breakpoints can only be set at at known
1007 @c locations (@pxref{Unknown Locations and Interrupts}), so these
1008 @c commands are largely useless unless the @code{debug} optimize quality
1009 @c is at least @code{2} (@pxref{Debugger Policy Control}). These
1010 @c commands manipulate breakpoints:
1012 @c @deffn {Debugger Command} breakpoint @var{location} [@var{option} @var{value}]*
1013 @c Set a breakpoint in some function. @var{location} may be an integer
1014 @c code location number (as displayed by @command{list-locations}) or a
1015 @c keyword. The keyword can be used to indicate setting a breakpoint at
1016 @c the function start (@code{:start}, @code{:s}) or function end
1017 @c (@code{:end}, @code{:e}). The @command{breakpoint} command has
1018 @c @code{:condition}, @code{:break}, @code{:print} and @code{:function}
1019 @c options which work similarly to the @code{trace} options.
1022 @c @deffn {Debugger Command} list-locations [@var{function}]
1023 @c @deffnx {Debugger Command} ll [@var{function}]
1024 @c List all the code locations in the current frame's function, or in
1025 @c @var{function} if it is supplied. The display format is the code
1026 @c location number, a colon and then the source form for that location:
1032 @c If consecutive locations have the same source, then a numeric range
1033 @c like @code{3-5:} will be printed. For example, a default function
1034 @c call has a known location both immediately before and after the call,
1035 @c which would result in two code locations with the same source. The
1036 @c listed function becomes the new default function for breakpoint
1037 @c setting (via the @command{breakpoint}) command.
1040 @c @deffn {Debugger Command} list-breakpoints
1041 @c @deffnx {Debugger Command} lb
1042 @c List all currently active breakpoints with their breakpoint number.
1045 @c @deffn {Debugger Command} delete-breakpoint [@var{number}]
1046 @c @deffnx {Debugger Command} db [@var{number}]
1047 @c Delete a breakpoint specified by its breakpoint number. If no number
1048 @c is specified, delete all breakpoints.
1051 @c @deffn {Debugger Command} step
1052 @c Step to the next possible breakpoint location in the current function.
1053 @c This always steps over function calls, instead of stepping into them.
1058 @c * Breakpoint Example::
1061 @c @node Breakpoint Example, , Breakpoint Commands, Breakpoint Commands
1062 @c @comment node-name, next, previous, up
1063 @c @subsection Breakpoint Example
1065 @c Consider this definition of the factorial function:
1071 @c (* n (! (1- n)))))
1074 @c This debugger session demonstrates the use of breakpoints:
1077 @c * (break) ; invoke debugger
1079 @c debugger invoked on a SIMPLE-CONDITION in thread 11184: break
1081 @c restarts (invokable by number or by possibly-abbreviated name):
1082 @c 0: [CONTINUE] Return from BREAK.
1083 @c 1: [ABORT ] Reduce debugger level (leaving debugger, returning to toplevel).
1084 @c 2: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
1085 @c ("varargs entry for top level local call BREAK" "break")
1088 @c 0-1: (SB-INT:NAMED-LAMBDA ! (N) (BLOCK ! (IF (ZEROP N) 1 (* N (! #)))))
1089 @c 2: (BLOCK ! (IF (ZEROP N) 1 (* N (! (1- N)))))
1091 @c 4: (* N (! (1- N)))
1094 @c 7-8: (* N (! (1- N)))
1095 @c 9-10: (IF (ZEROP N) 1 (* N (! (1- N))))
1103 @c FIXME: SBCL errored out, and not in the expected way ... Copying the
1104 @c output verbatim from the CMUCL manual for now.
1106 @c common-lisp-user> (! 10) ; Call the function
1111 @c 0: [CONTINUE] Return from BREAK.
1112 @c 1: [ABORT ] Return to Top-Level.
1114 @c Debug (type H for help)
1116 @c (! 10) ; We are now in first call (arg 10) before the multiply
1117 @c Source: (* N (! (1- N)))
1122 @c (! 10) ; We have finished evaluation of (1- n)
1129 @c 0: [CONTINUE] Return from BREAK.
1130 @c 1: [ABORT ] Return to Top-Level.
1132 @c Debug (type H for help)
1134 @c (! 9) ; We hit the breakpoint in the recursive call
1135 @c Source: (* N (! (1- N)))
1140 @node Function Tracing, , Information Commands, The Debugger
1141 @comment node-name, next, previous, up
1142 @section Function Tracing
1144 @cindex Function, tracing
1146 The tracer causes selected functions to print their arguments and
1147 their results whenever they are called. Options allow conditional
1148 printing of the trace information and conditional breakpoints on
1149 function entry or exit.
1151 @comment rudi 2004-03-26: The docstring for `trace' is quite comprehensive,
1152 @comment so refer to it (see also ``OAOO'')
1153 The docstrings for @code{trace} and @code{untrace} explain SBCL's
1156 @comment FIXME rudi 2004-03-26: revive the documentation of variables
1157 @comment describing trace behaviour: *trace-encapsulate-default*,
1158 @comment *max-trace-indentation* and friends. Some of these are
1159 @comment mentioned (perhaps under different names) in the cmucl
1162 @comment FIXME rudi 2004-03-26: encapsulate is (per TODO file as of
1163 @comment 0.8.9) in a state of flux. When it's sorted out, revive the
1164 @comment cmucl documentation.