2 @comment node-name, next, previous, up
6 This chapter documents the debugging facilities of SBCL, including
7 the debugger, single-stepper and @code{trace}, and the effect of
8 @code{(optimize debug)} declarations.
12 * Debugger Command Loop::
15 * Source Location Printing::
16 * Debugger Policy Control::
18 * Information Commands::
21 * Enabling and Disabling the Debugger::
25 @comment node-name, next, previous, up
26 @section Debugger Entry
30 * Debugger Invocation::
34 @comment node-name, next, previous, up
35 @subsection Debugger Banner
37 When you enter the debugger, it looks something like this:
40 debugger invoked on a TYPE-ERROR in thread 11184:
41 The value 3 is not of type LIST.
43 You can type HELP for debugger help, or (SB-EXT:QUIT) to exit from SBCL.
45 restarts (invokable by number or by possibly-abbreviated name):
46 0: [ABORT ] Reduce debugger level (leaving debugger, returning to toplevel).
47 1: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
52 The first group of lines describe what the error was that put us in
53 the debugger. In this case @code{car} was called on @code{3}, causing
56 This is followed by the ``beginner help line'', which appears only if
57 @code{sb-ext:*debug-beginner-help-p*} is true (default).
59 Next comes a listing of the active restart names, along with their
60 descriptions -- the ways we can restart execution after this error. In
61 this case, both options return to top-level. Restarts can be selected
62 by entering the corresponding number or name.
64 The current frame appears right underneath the restarts, immediately
65 followed by the debugger prompt.
67 @node Debugger Invocation
68 @comment node-name, next, previous, up
69 @subsection Debugger Invocation
71 The debugger is invoked when:
76 @code{error} is called, and the condition it signals is not handled.
79 @code{break} is called, or @code{signal} is called with a condition
80 that matches the current @code{*break-on-signals*}.
83 the debugger is explicitly entered with the @code{invoke-debugger}
88 When the debugger is invoked by a condition, ANSI mandates that the
89 value of @code{*debugger-hook*}, if any, be called with two arguments:
90 the condition that caused the debugger to be invoked and the previous
91 value of @code{*debugger-hook*}. When this happens,
92 @code{*debugger-hook*} is bound to NIL to prevent recursive errors.
93 However, ANSI also mandates that @code{*debugger-hook*} not be invoked
94 when the debugger is to be entered by the @code{break} function. For
95 users who wish to provide an alternate debugger interface (and thus
96 catch @code{break} entries into the debugger), SBCL provides
97 @code{sb-ext:*invoke-debugger-hook*}, which is invoked during any
98 entry into the debugger.
100 @include var-sb-ext-star-invoke-debugger-hook-star.texinfo
102 @node Debugger Command Loop
103 @comment node-name, next, previous, up
104 @section Debugger Command Loop
106 The debugger is an interactive read-eval-print loop much like the
107 normal top level, but some symbols are interpreted as debugger
108 commands instead of being evaluated. A debugger command starts with
109 the symbol name of the command, possibly followed by some arguments on
110 the same line. Some commands prompt for additional input. Debugger
111 commands can be abbreviated by any unambiguous prefix: @command{help}
112 can be typed as @samp{h}, @samp{he}, etc.
114 The package is not significant in debugger commands; any symbol with
115 the name of a debugger command will work. If you want to show the
116 value of a variable that happens also to be the name of a debugger
117 command you can wrap the variable in a @code{progn} to hide it from
120 The debugger prompt is ``@code{@var{frame}]}'', where @var{frame} is
121 the number of the current frame. Frames are numbered starting from
122 zero at the top (most recent call), increasing down to the bottom.
123 The current frame is the frame that commands refer to.
125 It is possible to override the normal printing behaviour in the
126 debugger by using the @code{sb-ext:*debug-print-variable-alist*}.
128 @include var-sb-ext-star-debug-print-variable-alist-star.texinfo
131 @comment node-name, next, previous, up
132 @section Stack Frames
135 A @dfn{stack frame} is the run-time representation of a call to a
136 function; the frame stores the state that a function needs to remember
137 what it is doing. Frames have:
142 @dfn{variables} (@pxref{Variable Access}), which are the values being operated
146 @dfn{arguments} to the call (which are really just particularly
147 interesting variables).
150 a current source location (@pxref{Source Location Printing}), which is
151 the place in the program where the function was running when it
152 stopped to call another function, or because of an interrupt or error.
158 * How Arguments are Printed::
160 * Debug Tail Recursion::
161 * Unknown Locations and Interrupts::
165 @comment node-name, next, previous, up
166 @subsection Stack Motion
168 These commands move to a new stack frame and print the name of the
169 function and the values of its arguments in the style of a Lisp
172 @deffn {Debugger Command} @nopkg{up}
173 Move up to the next higher frame. More recent function calls are
174 considered to be higher on the stack.
177 @deffn {Debugger Command} @nopkg{down}
178 Move down to the next lower frame.
181 @deffn {Debugger Command} @nopkg{top}
182 Move to the highest frame, that is, the frame where the debugger was
186 @deffn {Debugger Command} @nopkg{bottom}
187 Move to the lowest frame.
190 @deffn {Debugger Command} @nopkg{frame} [@var{n}]
191 Move to the frame with the specified number. Prompts for the number if not
192 supplied. The frame with number 0 is the frame where the debugger
197 @node How Arguments are Printed
198 @comment node-name, next, previous, up
199 @subsection How Arguments are Printed
201 A frame is printed to look like a function call, but with the actual
202 argument values in the argument positions. So the frame for this call
209 would look like this:
215 All keyword and optional arguments are displayed with their actual
216 values; if the corresponding argument was not supplied, the value will
217 be the default. So this call:
223 would look like this:
232 (string-upcase "test case")
235 would look like this:
238 (STRING-UPCASE "test case" :START 0 :END NIL)
241 The arguments to a function call are displayed by accessing the
242 argument variables. Although those variables are initialized to the
243 actual argument values, they can be set inside the function; in this
244 case the new value will be displayed.
246 @code{&rest} arguments are handled somewhat differently. The value of
247 the rest argument variable is displayed as the spread-out arguments to
251 (format t "~A is a ~A." "This" 'test)
254 would look like this:
257 (FORMAT T "~A is a ~A." "This" 'TEST)
260 Rest arguments cause an exception to the normal display of keyword
261 arguments in functions that have both @code{&rest} and @code{&key}
262 arguments. In this case, the keyword argument variables are not
263 displayed at all; the rest arg is displayed instead. So for these
264 functions, only the keywords actually supplied will be shown, and the
265 values displayed will be the argument values, not values of the
266 (possibly modified) variables.
268 If the variable for an argument is never referenced by the function,
269 it will be deleted. The variable value is then unavailable, so the
270 debugger prints @samp{#<unused-arg>} instead of the value. Similarly,
271 if for any of a number of reasons the value of the variable is
272 unavailable or not known to be available (@pxref{Variable Access}),
273 then @samp{#<unavailable-arg>} will be printed instead of the argument
276 Note that inline expansion and open-coding affect what frames
277 are present in the debugger, see @ref{Debugger Policy Control}.
278 @comment FIXME: link here to section about open coding once it exists.
283 @comment node-name, next, previous, up
284 @subsection Function Names
286 If a function is defined by @code{defun} it will appear in backtrace
287 by that name. Functions defined by @code{labels} and @code{flet} will
288 appear as @code{(FLET <name>)} and @code{(LABELS <name>)} respectively.
289 Anonymous lambdas will appear as @code{(LAMDBA <lambda-list>)}.
292 * Entry Point Details::
295 @node Entry Point Details
296 @comment node-name, next, previous, up
297 @subsubsection Entry Point Details
298 @cindex External entry points
299 @cindex Entry points, external
300 @cindex Block compilation, debugger implications
301 @cindex External, stack frame kind
302 @cindex Optional, stack frame kind
303 @cindex Cleanup, stack frame kind
305 Sometimes the compiler introduces new functions that are used to
306 implement a user function, but are not directly specified in the
307 source. This is mostly done for argument type and count checking.
309 The debugger will normally show these entry point functions as if
310 they were the normal main entry point, but more detail can be obtained
311 by setting @code{sb-debug:*show-entry-point-details*} to true; this is
312 primarily useful for debugging SBCL itself, but may help pinpoint
313 problems that occur during lambda-list processing.
315 @c FIXME: the following bits talked about block-compilation, but
316 @c we don't currently support it...
320 @c functions, an additional @code{:EXTERNAL} frame
321 @c may appear before the frame representing the first call to the
322 @c recursive function
323 @c or entry to the compiled block.
325 @c consequence of the way the compiler works: there is
326 @c nothing odd with your program. You will also see @code{:CLEANUP}
327 @c frames during the execution of @code{unwind-protect} cleanup
330 With recursive functions, an additional @code{:EXTERNAL} frame may
331 appear before the frame representing the first call to the recursive
332 function. This is a consequence of the way the compiler works: there
333 is nothing odd with your program. You will also see @code{:CLEANUP}
334 frames during the execution of @code{unwind-protect} cleanup code.
335 The @code{:EXTERNAL} and @code{:CLEANUP} above are entry-point types,
336 visible only if @code{sb-debug:*show-entry-point-details*} os true.
338 @node Debug Tail Recursion
339 @comment node-name, next, previous, up
340 @subsection Debug Tail Recursion
341 @cindex Tail recursion
342 @cindex Recursion, tail
344 The compiler is ``properly tail recursive.'' If a function call is in
345 a tail-recursive position, the stack frame will be deallocated
346 @emph{at the time of the call}, rather than after the call returns.
347 Consider this backtrace:
354 Because of tail recursion, it is not necessarily the case that
355 @code{FOO} directly called @code{BAR}. It may be that @code{FOO}
356 called some other function @code{FOO2} which then called @code{BAR}
357 tail-recursively, as in this example:
373 Usually the elimination of tail-recursive frames makes debugging more
374 pleasant, since these frames are mostly uninformative. If there is any
375 doubt about how one function called another, it can usually be
376 eliminated by finding the source location in the calling frame.
377 @xref{Source Location Printing}.
379 The elimination of tail-recursive frames can be prevented by disabling
380 tail-recursion optimization, which happens when the @code{debug}
381 optimization quality is greater than @code{2}.
382 @xref{Debugger Policy Control}.
384 @comment FIXME: reinstate this link once the chapter is in the manual.
385 @c For a more thorough discussion of tail recursion, @ref{tail-recursion}.
387 @node Unknown Locations and Interrupts
388 @comment node-name, next, previous, up
389 @subsection Unknown Locations and Interrupts
390 @cindex Unknown code locations
391 @cindex Locations, unknown
393 @cindex Errors, run-time
395 The debugger operates using special debugging information attached to
396 the compiled code. This debug information tells the debugger what it
397 needs to know about the locations in the code where the debugger can
398 be invoked. If the debugger somehow encounters a location not
399 described in the debug information, then it is said to be
400 @dfn{unknown}. If the code location for a frame is unknown, then some
401 variables may be inaccessible, and the source location cannot be
404 There are three reasons why a code location could be unknown:
409 There is inadequate debug information due to the value of the @code{debug}
410 optimization quality. @xref{Debugger Policy Control}.
413 The debugger was entered because of an interrupt such as @key{C-c}.
416 A hardware error such as ``@samp{bus error}'' occurred in code that was
417 compiled unsafely due to the value of the @code{safety} optimization
419 @comment FIXME: reinstate link when section on optimize qualities exists.
420 @c @xref{optimize-declaration}.
424 In the last two cases, the values of argument variables are
425 accessible, but may be incorrect. For more details on when variable
426 values are accessible, @ref{Variable Value Availability}.
428 It is possible for an interrupt to happen when a function call or
429 return is in progress. The debugger may then flame out with some
430 obscure error or insist that the bottom of the stack has been reached,
431 when the real problem is that the current stack frame can't be
432 located. If this happens, return from the interrupt and try again.
435 @node Variable Access
436 @comment node-name, next, previous, up
437 @section Variable Access
438 @cindex Debug variables
439 @cindex Variables, debugger access
441 There are two ways to access the current frame's local variables in
442 the debugger: @command{list-locals} and @code{sb-debug:var}.
444 The debugger doesn't really understand lexical scoping; it has just
445 one namespace for all the variables in the current stack frame. If a
446 symbol is the name of multiple variables in the same function, then
447 the reference appears ambiguous, even though lexical scoping specifies
448 which value is visible at any given source location. If the scopes of
449 the two variables are not nested, then the debugger can resolve the
450 ambiguity by observing that only one variable is accessible.
452 When there are ambiguous variables, the evaluator assigns each one a
453 small integer identifier. The @code{sb-debug:var} function uses this
454 identifier to distinguish between ambiguous variables. The
455 @command{list-locals} command prints the identifier. In the
456 following example, there are two variables named @code{X}. The first
457 one has identifier 0 (which is not printed), the second one has
465 @deffn {Debugger Command} @nopkg{list-locals} [@var{prefix}]
466 This command prints the name and value of all variables in the current
467 frame whose name has the specified @var{prefix}. @var{prefix} may be
468 a string or a symbol. If no @var{prefix} is given, then all available
469 variables are printed. If a variable has a potentially ambiguous
470 name, then the name is printed with a ``@code{#@var{identifier}}''
471 suffix, where @var{identifier} is the small integer used to make the
475 @defun @sbdebug{var} @var{name} &optional @var{identifier}
476 This function returns the value of the variable in the current frame
477 with the specified @var{name}. If supplied, @var{identifier}
478 determines which value to return when there are ambiguous variables.
480 When @var{name} is a symbol, it is interpreted as the symbol name of
481 the variable, i.e. the package is significant. If @var{name} is an
482 uninterned symbol (gensym), then return the value of the uninterned
483 variable with the same name. If @var{name} is a string,
484 @code{sb-debug:var} interprets it as the prefix of a variable name
485 that must unambiguously complete to the name of a valid variable.
487 @var{identifier} is used to disambiguate the variable name; use
488 @command{list-locals} to find out the identifiers.
493 * Variable Value Availability::
494 * Note On Lexical Variable Access::
497 @node Variable Value Availability
498 @comment node-name, next, previous, up
499 @subsection Variable Value Availability
500 @cindex Availability of debug variables
501 @cindex Validity of debug variables
502 @cindex Debug optimization quality
504 The value of a variable may be unavailable to the debugger in portions
505 of the program where Lisp says that the variable is defined. If a
506 variable value is not available, the debugger will not let you read or
507 write that variable. With one exception, the debugger will never
508 display an incorrect value for a variable. Rather than displaying
509 incorrect values, the debugger tells you the value is unavailable.
511 The one exception is this: if you interrupt (e.g., with @key{C-c}) or
512 if there is an unexpected hardware error such as ``@samp{bus error}''
513 (which should only happen in unsafe code), then the values displayed
514 for arguments to the interrupted frame might be
515 incorrect.@footnote{Since the location of an interrupt or hardware
516 error will always be an unknown location, non-argument variable values
517 will never be available in the interrupted frame. @xref{Unknown
518 Locations and Interrupts}.} This exception applies only to the
519 interrupted frame: any frame farther down the stack will be fine.
521 The value of a variable may be unavailable for these reasons:
526 The value of the @code{debug} optimization quality may have omitted debug
527 information needed to determine whether the variable is available.
528 Unless a variable is an argument, its value will only be available when
529 @code{debug} is at least @code{2}.
532 The compiler did lifetime analysis and determined that the value was no longer
533 needed, even though its scope had not been exited. Lifetime analysis is
534 inhibited when the @code{debug} optimization quality is @code{3}.
537 The variable's name is an uninterned symbol (gensym). To save space, the
538 compiler only dumps debug information about uninterned variables when the
539 @code{debug} optimization quality is @code{3}.
542 The frame's location is unknown (@pxref{Unknown Locations and
543 Interrupts}) because the debugger was entered due to an interrupt or
544 unexpected hardware error. Under these conditions the values of
545 arguments will be available, but might be incorrect. This is the
546 exception mentioned above.
549 The variable (or the code referencing it) was optimized out
550 of existence. Variables with no reads are always optimized away. The
551 degree to which the compiler deletes variables will depend on the
552 value of the @code{compilation-speed} optimization quality, but most
553 source-level optimizations are done under all compilation policies.
556 The variable is never set and its definition looks like
561 In this case, @code{var1} is substituted with @code{var2}.
564 The variable is never set and is referenced exactly once. In this
565 case, the reference is substituted with the variable initial value.
569 Since it is especially useful to be able to get the arguments to a
570 function, argument variables are treated specially when the
571 @code{speed} optimization quality is less than @code{3} and the
572 @code{debug} quality is at least @code{1}. With this compilation
573 policy, the values of argument variables are almost always available
574 everywhere in the function, even at unknown locations. For
575 non-argument variables, @code{debug} must be at least @code{2} for
576 values to be available, and even then, values are only available at
580 @node Note On Lexical Variable Access
581 @comment node-name, next, previous, up
582 @subsection Note On Lexical Variable Access
584 When the debugger command loop establishes variable bindings for
585 available variables, these variable bindings have lexical scope and
586 dynamic extent.@footnote{The variable bindings are actually created
587 using the Lisp @code{symbol-macrolet} special form.} You can close
588 over them, but such closures can't be used as upward funargs.
590 You can also set local variables using @code{setq}, but if the
591 variable was closed over in the original source and never set, then
592 setting the variable in the debugger may not change the value in all
593 the functions the variable is defined in. Another risk of setting
594 variables is that you may assign a value of a type that the compiler
595 proved the variable could never take on. This may result in bad
599 @node Source Location Printing
600 @comment node-name, next, previous, up
601 @section Source Location Printing
602 @cindex Source location printing, debugger
604 One of the debugger's capabilities is source level debugging of
605 compiled code. These commands display the source location for the
608 @deffn {Debugger Command} @nopkg{source} [@var{context}]
609 This command displays the file that the current frame's function was
610 defined from (if it was defined from a file), and then the source form
611 responsible for generating the code that the current frame was
612 executing. If @var{context} is specified, then it is an integer
613 specifying the number of enclosing levels of list structure to print.
616 The source form for a location in the code is the innermost list present
617 in the original source that encloses the form responsible for generating
618 that code. If the actual source form is not a list, then some enclosing
619 list will be printed. For example, if the source form was a reference
620 to the variable @code{*some-random-special*}, then the innermost
621 enclosing evaluated form will be printed. Here are some possible
625 (let ((a *some-random-special*))
628 (+ *some-random-special* ...)
631 If the code at a location was generated from the expansion of a macro
632 or a source-level compiler optimization, then the form in the original
633 source that expanded into that code will be printed. Suppose the file
634 @file{/usr/me/mystuff.lisp} looked like this:
645 If @code{foo} has called @code{myfun}, and is waiting for it to
646 return, then the @command{source} command would print:
649 ; File: /usr/me/mystuff.lisp
654 Note that the macro use was printed, not the actual function call form,
657 If enclosing source is printed by giving an argument to
658 @command{source} or @command{vsource}, then the actual source form is
659 marked by wrapping it in a list whose first element is
660 @samp{#:***HERE***}. In the previous example, @code{source 1} would
664 ; File: /usr/me/mystuff.lisp
674 * How the Source is Found::
675 * Source Location Availability::
678 @node How the Source is Found
679 @comment node-name, next, previous, up
680 @subsection How the Source is Found
682 If the code was defined from Lisp by @code{compile} or
683 @code{eval}, then the source can always be reliably located. If the
684 code was defined from a @file{fasl} file created by
685 @code{compile-file}, then the debugger gets the source forms it
686 prints by reading them from the original source file. This is a
687 potential problem, since the source file might have moved or changed
688 since the time it was compiled.
690 The source file is opened using the @code{truename} of the source file
691 pathname originally given to the compiler. This is an absolute pathname
692 with all logical names and symbolic links expanded. If the file can't
693 be located using this name, then the debugger gives up and signals an
696 If the source file can be found, but has been modified since the time it was
697 compiled, the debugger prints this warning:
700 ; File has been modified since compilation:
702 ; Using form offset instead of character position.
705 where @var{filename} is the name of the source file. It then proceeds
706 using a robust but not foolproof heuristic for locating the source.
707 This heuristic works if:
712 No top-level forms before the top-level form containing the source
713 have been added or deleted, and
716 The top-level form containing the source has not been modified much.
717 (More precisely, none of the list forms beginning before the source
718 form have been added or deleted.)
722 If the heuristic doesn't work, the displayed source will be wrong, but will
723 probably be near the actual source. If the ``shape'' of the top-level form in
724 the source file is too different from the original form, then an error will be
725 signaled. When the heuristic is used, the source location commands are
728 Source location printing can also be confused if (after the source was
729 compiled) a read-macro you used in the code was redefined to expand
730 into something different, or if a read-macro ever returns the same
731 @code{eq} list twice. If you don't define read macros and don't use
732 @code{##} in perverted ways, you don't need to worry about this.
735 @node Source Location Availability
736 @comment node-name, next, previous, up
737 @subsection Source Location Availability
738 @cindex Debug optimization quality
740 @cindex Block, start location
742 Source location information is only available when the @code{debug}
743 optimization quality is at least @code{2}. If source location
744 information is unavailable, the source commands will give an error
747 If source location information is available, but the source location
748 is unknown because of an interrupt or unexpected hardware error
749 (@pxref{Unknown Locations and Interrupts}), then the command will
753 Unknown location: using block start.
756 and then proceed to print the source location for the start of the
757 @emph{basic block} enclosing the code location. It's a bit
758 complicated to explain exactly what a basic block is, but here are
759 some properties of the block start location:
763 @item The block start location may be the same as the true location.
765 @item The block start location will never be later in the
766 program's flow of control than the true location.
768 @item No conditional control structures (such as @code{if},
769 @code{cond}, @code{or}) will intervene between the block start and the
770 true location (but note that some conditionals present in the original
771 source could be optimized away.) Function calls @emph{do not} end
774 @item The head of a loop will be the start of a block.
776 @item The programming language concept of ``block structure'' and the
777 Lisp @code{block} special form are totally unrelated to the compiler's
782 In other words, the true location lies between the printed location and the
783 next conditional (but watch out because the compiler may have changed the
787 @node Debugger Policy Control
788 @comment node-name, next, previous, up
789 @section Debugger Policy Control
790 @cindex Policy, debugger
791 @cindex Debug optimization quality
792 @cindex Optimize declaration
793 @cindex Inline expansion
794 @cindex Semi-inline expansion
796 The compilation policy specified by @code{optimize} declarations
797 affects the behavior seen in the debugger. The @code{debug} quality
798 directly affects the debugger by controlling the amount of debugger
799 information dumped. Other optimization qualities have indirect but
800 observable effects due to changes in the way compilation is done.
802 Unlike the other optimization qualities (which are compared in relative value
803 to evaluate tradeoffs), the @code{debug} optimization quality is directly
804 translated to a level of debug information. This absolute interpretation
805 allows the user to count on a particular amount of debug information being
806 available even when the values of the other qualities are changed during
807 compilation. These are the levels of debug information that correspond to the
808 values of the @code{debug} quality:
813 Only the function name and enough information to allow the stack to
817 Any level greater than @code{0} gives level @code{0} plus all argument
818 variables. Values will only be accessible if the argument variable is
819 never set and @code{speed} is not @code{3}. SBCL allows any real
820 value for optimization qualities. It may be useful to specify
821 @code{0.5} to get backtrace argument display without argument
825 Level @code{1} provides argument documentation (printed arglists) and
826 derived argument/result type information. This makes @code{describe}
827 more informative, and allows the compiler to do compile-time argument
828 count and type checking for any calls compiled at run-time. This is
832 Level @code{1} plus all interned local variables, source location
833 information, and lifetime information that tells the debugger when
834 arguments are available (even when @code{speed} is @code{3} or the
838 Any level greater than @code{2} gives level @code{2} and in addition
839 disables tail-call optimization, so that the backtrace will contain
840 frames for all invoked functions, even those in tail positions.
843 Level @code{2} plus all uninterned variables. In addition, lifetime
844 analysis is disabled (even when @code{speed} is @code{3}), ensuring
845 that all variable values are available at any known location within
846 the scope of the binding. This has a speed penalty in addition to the
847 obvious space penalty.
849 @item > (max speed space)
850 If @code{debug} is greater than both @code{speed} and @code{space},
851 the command @command{return} can be used to continue execution by
852 returning a value from the current stack frame.
854 @item > (max speed space compilation-speed)
855 If @code{debug} is greater than all of @code{speed}, @code{space} and
856 @code{compilation-speed} the code will be steppable (@pxref{Single Stepping}).
860 As you can see, if the @code{speed} quality is @code{3}, debugger performance is
861 degraded. This effect comes from the elimination of argument variable
862 special-casing (@pxref{Variable Value Availability}). Some degree of
863 speed/debuggability tradeoff is unavoidable, but the effect is not too drastic
864 when @code{debug} is at least @code{2}.
866 In addition to @code{inline} and @code{notinline} declarations, the
867 relative values of the @code{speed} and @code{space} qualities also
868 change whether functions are inline expanded.
869 @comment FIXME: link to section about inline expansion when it exists
870 @c (\pxlref{inline-expansion}.)
871 If a function is inline expanded, then
872 there will be no frame to represent the call, and the arguments will
873 be treated like any other local variable. Functions may also be
874 ``semi-inline'', in which case there is a frame to represent the call,
875 but the call is to an optimized local version of the function, not to
876 the original function.
879 @node Exiting Commands
880 @comment node-name, next, previous, up
881 @section Exiting Commands
883 These commands get you out of the debugger.
885 @deffn {Debugger Command} @nopkg{toplevel}
889 @deffn {Debugger Command} @nopkg{restart} [@var{n}]
890 Invokes the @var{n}th restart case as displayed by the @code{error}
891 command. If @var{n} is not specified, the available restart cases are
895 @deffn {Debugger Command} @nopkg{continue}
896 Calls @code{continue} on the condition given to @code{debug}. If there is no
897 restart case named @var{continue}, then an error is signaled.
900 @deffn {Debugger Command} @nopkg{abort}
901 Calls @code{abort} on the condition given to @code{debug}. This is
902 useful for popping debug command loop levels or aborting to top level,
906 @deffn {Debugger Command} @nopkg{return} @var{value}
907 Returns @var{value} from the current stack frame. This command is
908 available when the @code{debug} optimization quality is greater than
909 both @code{speed} and @code{space}. Care must be taken that the value
910 is of the same type as SBCL expects the stack frame to return.
913 @deffn {Debugger Command} @nopkg{restart-frame}
914 Restarts execution of the current stack frame. This command is
915 available when the @code{debug} optimization quality is greater than
916 both @code{speed} and @code{space} and when the frame is for is a global
917 function. If the function is redefined in the debugger before the frame
918 is restarted, the new function will be used.
921 @node Information Commands
922 @comment node-name, next, previous, up
923 @section Information Commands
925 Most of these commands print information about the current frame or
926 function, but a few show general information.
928 @deffn {Debugger Command} @nopkg{help}
929 @deffnx {Debugger Command} @nopkg{?}
930 Displays a synopsis of debugger commands.
933 @deffn {Debugger Command} @nopkg{describe}
934 Calls @code{describe} on the current function and displays the number of
938 @deffn {Debugger Command} @nopkg{print}
939 Displays the current function call as it would be displayed by moving to
943 @deffn {Debugger Command} @nopkg{error}
944 Prints the condition given to @code{invoke-debugger} and the active
948 @deffn {Debugger Command} @nopkg{backtrace} [@var{n}]
949 Displays all the frames from the current to the bottom. Only shows
950 @var{n} frames if specified. The printing is controlled by
951 @code{*debug-print-variable-alist*}.
954 @c The new instrumentation based single stepper doesn't support
955 @c the following commands, but BREAKPOINT at least should be
956 @c resurrectable via (TRACE FOO :BREAK T).
958 @c @cindex Breakpoints
960 @c SBCL supports setting of breakpoints inside compiled functions and
961 @c stepping of compiled code. Breakpoints can only be set at known
962 @c locations (@pxref{Unknown Locations and Interrupts}), so these
963 @c commands are largely useless unless the @code{debug} optimize quality
964 @c is at least @code{2} (@pxref{Debugger Policy Control}). These
965 @c commands manipulate breakpoints:
967 @c @deffn {Debugger Command} breakpoint @var{location} [@var{option} @var{value}]*
968 @c Set a breakpoint in some function. @var{location} may be an integer
969 @c code location number (as displayed by @command{list-locations}) or a
970 @c keyword. The keyword can be used to indicate setting a breakpoint at
971 @c the function start (@code{:start}, @code{:s}) or function end
972 @c (@code{:end}, @code{:e}). The @command{breakpoint} command has
973 @c @code{:condition}, @code{:break}, @code{:print} and @code{:function}
974 @c options which work similarly to the @code{trace} options.
977 @c @deffn {Debugger Command} list-locations [@var{function}]
978 @c @deffnx {Debugger Command} ll [@var{function}]
979 @c List all the code locations in the current frame's function, or in
980 @c @var{function} if it is supplied. The display format is the code
981 @c location number, a colon and then the source form for that location:
987 @c If consecutive locations have the same source, then a numeric range
988 @c like @code{3-5:} will be printed. For example, a default function
989 @c call has a known location both immediately before and after the call,
990 @c which would result in two code locations with the same source. The
991 @c listed function becomes the new default function for breakpoint
992 @c setting (via the @command{breakpoint}) command.
995 @c @deffn {Debugger Command} list-breakpoints
996 @c @deffnx {Debugger Command} lb
997 @c List all currently active breakpoints with their breakpoint number.
1000 @c @deffn {Debugger Command} delete-breakpoint [@var{number}]
1001 @c @deffnx {Debugger Command} db [@var{number}]
1002 @c Delete a breakpoint specified by its breakpoint number. If no number
1003 @c is specified, delete all breakpoints.
1007 @c * Breakpoint Example::
1010 @c @node Breakpoint Example, , Breakpoint Commands, Breakpoint Commands
1011 @c @comment node-name, next, previous, up
1012 @c @subsection Breakpoint Example
1014 @c Consider this definition of the factorial function:
1020 @c (* n (! (1- n)))))
1023 @c This debugger session demonstrates the use of breakpoints:
1026 @c * (break) ; invoke debugger
1028 @c debugger invoked on a SIMPLE-CONDITION in thread 11184: break
1030 @c restarts (invokable by number or by possibly-abbreviated name):
1031 @c 0: [CONTINUE] Return from BREAK.
1032 @c 1: [ABORT ] Reduce debugger level (leaving debugger, returning to toplevel).
1033 @c 2: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
1034 @c ("varargs entry for top level local call BREAK" "break")
1037 @c 0-1: (SB-INT:NAMED-LAMBDA ! (N) (BLOCK ! (IF (ZEROP N) 1 (* N (! #)))))
1038 @c 2: (BLOCK ! (IF (ZEROP N) 1 (* N (! (1- N)))))
1040 @c 4: (* N (! (1- N)))
1043 @c 7-8: (* N (! (1- N)))
1044 @c 9-10: (IF (ZEROP N) 1 (* N (! (1- N))))
1052 @c FIXME: SBCL errored out, and not in the expected way ... Copying the
1053 @c output verbatim from the CMUCL manual for now.
1055 @c common-lisp-user> (! 10) ; Call the function
1060 @c 0: [CONTINUE] Return from BREAK.
1061 @c 1: [ABORT ] Return to Top-Level.
1063 @c Debug (type H for help)
1065 @c (! 10) ; We are now in first call (arg 10) before the multiply
1066 @c Source: (* N (! (1- N)))
1071 @c (! 10) ; We have finished evaluation of (1- n)
1078 @c 0: [CONTINUE] Return from BREAK.
1079 @c 1: [ABORT ] Return to Top-Level.
1081 @c Debug (type H for help)
1083 @c (! 9) ; We hit the breakpoint in the recursive call
1084 @c Source: (* N (! (1- N)))
1089 @node Function Tracing
1090 @comment node-name, next, previous, up
1091 @section Function Tracing
1093 @cindex Function, tracing
1095 The tracer causes selected functions to print their arguments and
1096 their results whenever they are called. Options allow conditional
1097 printing of the trace information and conditional breakpoints on
1098 function entry or exit.
1100 @include macro-common-lisp-trace.texinfo
1102 @include macro-common-lisp-untrace.texinfo
1104 @include var-sb-debug-star-trace-indentation-step-star.texinfo
1106 @include var-sb-debug-star-max-trace-indentation-star.texinfo
1108 @include var-sb-debug-star-trace-encapsulate-default-star.texinfo
1110 @include var-sb-debug-star-trace-values-star.texinfo
1112 @comment FIXME rudi 2004-03-26: encapsulate is (per TODO file as of
1113 @comment 0.8.9) in a state of flux. When it's sorted out, revive the
1114 @comment cmucl documentation.
1116 @node Single Stepping
1117 @comment node-name, next, previous, up
1118 @section Single Stepping
1120 @cindex Single Stepping
1122 SBCL includes an instrumentation based single-stepper for compiled
1123 code, that can be invoked via the @code{step} macro, or from within
1124 the debugger. @xref{Debugger Policy Control}, for details on enabling
1125 stepping for compiled code.
1127 The following debugger commands are used for controlling single stepping.
1129 @deffn {Debugger Command} @nopkg{start}
1130 Selects the @code{continue} restart if one exists and starts single stepping.
1131 None of the other single stepping commands can be used before stepping has
1132 been started either by using @code{start} or by using the standard
1136 @deffn {Debugger Command} @nopkg{step}
1137 Steps into the current form. Stepping will be resumed when the next
1138 form that has been compiled with stepper instrumentation is evaluated.
1141 @deffn {Debugger Command} @nopkg{next}
1142 Steps over the current form. Stepping will be disabled until evaluation of
1143 the form is complete.
1146 @deffn {Debugger Command} @nopkg{out}
1147 Steps out of the current frame. Stepping will be disabled until the
1148 topmost stack frame that had been stepped into returns.
1151 @deffn {Debugger Command} @nopkg{stop}
1152 Stops the single stepper and resumes normal execution.
1155 @include macro-common-lisp-step.texinfo
1157 @node Enabling and Disabling the Debugger
1158 @comment node-name, next, previous, up
1159 @section Enabling and Disabling the Debugger
1161 @cindex debugger, enabling
1162 @cindex debugger, disabling
1163 @cindex disabling debugger
1164 @cindex ldb, enabling
1165 @cindex ldb, disabling
1166 @cindex disabling ldb
1168 In certain contexts (e.g., non-interactive applications), it may be
1169 desirable to turn off the SBCL debugger (and possibly re-enable it).
1170 The functions here control the debugger.
1172 @include fun-sb-ext-disable-debugger.texinfo
1174 @include fun-sb-ext-enable-debugger.texinfo