1.0.8.48: Update comment.
[sbcl.git] / doc / manual / debugger.texinfo
1 @node Debugger
2 @comment  node-name,  next,  previous,  up
3 @chapter Debugger
4 @cindex Debugger
5
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.
9
10 @menu
11 * Debugger Entry::              
12 * Debugger Command Loop::       
13 * Stack Frames::                
14 * Variable Access::             
15 * Source Location Printing::    
16 * Debugger Policy Control::     
17 * Exiting Commands::            
18 * Information Commands::        
19 * Function Tracing::            
20 * Single Stepping::             
21 @end menu
22
23 @node Debugger Entry
24 @comment  node-name,  next,  previous,  up
25 @section Debugger Entry
26
27 @menu
28 * Debugger Banner::             
29 * Debugger Invocation::         
30 @end menu
31
32 @node Debugger Banner
33 @comment  node-name,  next,  previous,  up
34 @subsection Debugger Banner
35
36 When you enter the debugger, it looks something like this:
37
38 @example
39 debugger invoked on a TYPE-ERROR in thread 11184:
40   The value 3 is not of type LIST.
41
42 You can type HELP for debugger help, or (SB-EXT:QUIT) to exit from SBCL.
43
44 restarts (invokable by number or by possibly-abbreviated name):
45   0: [ABORT   ] Reduce debugger level (leaving debugger, returning to toplevel).
46   1: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
47 (CAR 1 3)
48 0]
49 @end example
50
51 The first group of lines describe what the error was that put us in
52 the debugger.  In this case @code{car} was called on @code{3}, causing
53 a @code{type-error}.  
54
55 This is followed by the ``beginner help line'', which appears only if
56 @code{sb-ext:*debugger-beginner-help*} is true (default).
57
58 Next comes a listing of the active restart names, along with their
59 descriptions -- the ways we can restart execution after this error. In
60 this case, both options return to top-level. Restarts can be selected
61 by entering the corresponding number or name.
62
63 The current frame appears right underneath the restarts, immediately
64 followed by the debugger prompt.
65
66 @node Debugger Invocation
67 @comment  node-name,  next,  previous,  up
68 @subsection Debugger Invocation
69
70 The debugger is invoked when:
71
72 @itemize
73
74 @item
75 @code{error} is called, and the condition it signals is not handled.
76
77 @item
78 @code{break} is called, or @code{signal} is called with a condition
79 that matches the current @code{*break-on-signals*}.
80
81 @item
82 the debugger is explicitly entered with the @code{invoke-debugger}
83 function.
84
85 @end itemize
86
87 When the debugger is invoked by a condition, ANSI mandates that the
88 value of @code{*debugger-hook*}, if any, be called with two arguments:
89 the condition that caused the debugger to be invoked and the previous
90 value of @code{*debugger-hook*}. When this happens,
91 @code{*debugger-hook*} is bound to NIL to prevent recursive errors.
92 However, ANSI also mandates that @code{*debugger-hook*} not be invoked
93 when the debugger is to be entered by the @code{break} function. For
94 users who wish to provide an alternate debugger interface (and thus
95 catch @code{break} entries into the debugger), SBCL provides
96 @code{sb-ext:*invoke-debugger-hook*}, which is invoked during any
97 entry into the debugger.
98
99 @include var-sb-ext-star-invoke-debugger-hook-star.texinfo
100
101 @node  Debugger Command Loop
102 @comment  node-name,  next,  previous,  up
103 @section Debugger Command Loop
104
105 The debugger is an interactive read-eval-print loop much like the
106 normal top level, but some symbols are interpreted as debugger
107 commands instead of being evaluated. A debugger command starts with
108 the symbol name of the command, possibly followed by some arguments on
109 the same line. Some commands prompt for additional input. Debugger
110 commands can be abbreviated by any unambiguous prefix: @command{help}
111 can be typed as @samp{h}, @samp{he}, etc.
112
113 The package is not significant in debugger commands; any symbol with
114 the name of a debugger command will work. If you want to show the
115 value of a variable that happens also to be the name of a debugger
116 command you can wrap the variable in a @code{progn} to hide it from
117 the command loop.
118
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. 
123
124 It is possible to override the normal printing behaviour in the
125 debugger by using the @code{sb-ext:*debug-print-variable-alist*}.
126
127 @include var-sb-ext-star-debug-print-variable-alist-star.texinfo
128
129 @node  Stack Frames
130 @comment  node-name,  next,  previous,  up
131 @section Stack Frames
132 @cindex Stack frames
133
134 A @dfn{stack frame} is the run-time representation of a call to a
135 function; the frame stores the state that a function needs to remember
136 what it is doing.  Frames have:
137
138 @itemize
139
140 @item
141 @dfn{variables} (@pxref{Variable Access}), which are the values being operated
142 on.
143
144 @item
145 @dfn{arguments} to the call (which are really just particularly
146 interesting variables).
147
148 @item
149 a current source location (@pxref{Source Location Printing}), which is
150 the place in the program where the function was running when it
151 stopped to call another function, or because of an interrupt or error.
152
153 @end itemize
154
155 @menu
156 * Stack Motion::                
157 * How Arguments are Printed::   
158 * Function Names::              
159 * Debug Tail Recursion::        
160 * Unknown Locations and Interrupts::  
161 @end menu
162
163 @node  Stack Motion
164 @comment  node-name,  next,  previous,  up
165 @subsection Stack Motion
166
167 These commands move to a new stack frame and print the name of the
168 function and the values of its arguments in the style of a Lisp
169 function call:
170
171 @deffn {Debugger Command} up
172 Move up to the next higher frame.  More recent function calls are
173 considered to be higher on the stack.
174 @end deffn
175
176 @deffn {Debugger Command} down
177 Move down to the next lower frame.
178 @end deffn
179
180 @deffn {Debugger Command} top
181 Move to the highest frame, that is, the frame where the debugger was
182 entered.
183 @end deffn
184
185 @deffn {Debugger Command} bottom
186 Move to the lowest frame.
187 @end deffn
188
189 @deffn {Debugger Command} frame [@var{n}]
190 Move to the frame with the specified number.  Prompts for the number if not
191 supplied.  The frame with number 0 is the frame where the debugger
192 was entered.
193 @end deffn
194
195
196 @node  How Arguments are Printed
197 @comment  node-name,  next,  previous,  up
198 @subsection How Arguments are Printed
199
200 A frame is printed to look like a function call, but with the actual
201 argument values in the argument positions.  So the frame for this call
202 in the source:
203
204 @lisp
205 (myfun (+ 3 4) 'a)
206 @end lisp
207
208 would look like this:
209
210 @example
211 (MYFUN 7 A)
212 @end example
213
214 All keyword and optional arguments are displayed with their actual
215 values; if the corresponding argument was not supplied, the value will
216 be the default.  So this call:
217
218 @lisp
219 (subseq "foo" 1)
220 @end lisp
221
222 would look like this:
223
224 @example
225 (SUBSEQ "foo" 1 3)
226 @end example
227
228 And this call:
229
230 @lisp
231 (string-upcase "test case")
232 @end lisp
233
234 would look like this:
235
236 @example
237 (STRING-UPCASE "test case" :START 0 :END NIL)
238 @end example
239
240 The arguments to a function call are displayed by accessing the
241 argument variables.  Although those variables are initialized to the
242 actual argument values, they can be set inside the function; in this
243 case the new value will be displayed.
244
245 @code{&rest} arguments are handled somewhat differently.  The value of
246 the rest argument variable is displayed as the spread-out arguments to
247 the call, so:
248
249 @lisp
250 (format t "~A is a ~A." "This" 'test)
251 @end lisp
252
253 would look like this:
254
255 @example
256 (FORMAT T "~A is a ~A." "This" 'TEST)
257 @end example
258
259 Rest arguments cause an exception to the normal display of keyword
260 arguments in functions that have both @code{&rest} and @code{&key}
261 arguments.  In this case, the keyword argument variables are not
262 displayed at all; the rest arg is displayed instead.  So for these
263 functions, only the keywords actually supplied will be shown, and the
264 values displayed will be the argument values, not values of the
265 (possibly modified) variables.
266
267 If the variable for an argument is never referenced by the function,
268 it will be deleted.  The variable value is then unavailable, so the
269 debugger prints @samp{#<unused-arg>} instead of the value.  Similarly,
270 if for any of a number of reasons the value of the variable is
271 unavailable or not known to be available (@pxref{Variable Access}),
272 then @samp{#<unavailable-arg>} will be printed instead of the argument
273 value.
274
275  Note that inline expansion and open-coding affect what frames
276 are present in the debugger, see @ref{Debugger Policy Control}.
277 @comment FIXME: link here to section about open coding once it exists.
278 @c @ref{open-coding}
279
280
281 @node  Function Names
282 @comment  node-name,  next,  previous,  up
283 @subsection Function Names
284
285 If a function is defined by @code{defun} it will appear in backtrace
286 by that name. Functions defined by @code{labels} and @code{flet} will
287 appear as @code{(FLET <name>)} and @code{(LABELS <name>)} respectively.
288 Anonymous lambdas will appear as @code{(LAMDBA <lambda-list>)}.
289
290 @menu
291 * Entry Point Details::         
292 @end menu
293
294 @node  Entry Point Details
295 @comment  node-name,  next,  previous,  up
296 @subsubsection Entry Point Details
297 @cindex External entry points
298 @cindex Entry points, external
299 @cindex Block compilation, debugger implications
300 @cindex External, stack frame kind
301 @cindex Optional, stack frame kind
302 @cindex Cleanup, stack frame kind
303
304 Sometimes the compiler introduces new functions that are used to
305 implement a user function, but are not directly specified in the
306 source. This is mostly done for argument type and count checking.
307
308 The debugger will normally show these entry point functions as if
309 they were the normal main entry point, but more detail can be obtained
310 by setting @code{sb-debug:*show-entry-point-details*} to true; this is
311 primarily useful for debugging SBCL itself, but may help pinpoint
312 problems that occur during lambda-list processing.
313
314 @c FIXME: the following bits talked about block-compilation, but
315 @c we don't currently support it...
316
317 @c With recursive 
318 @c or block compiled 
319 @c functions, an additional @code{:EXTERNAL} frame
320 @c may appear before the frame representing the first call to the
321 @c recursive function
322 @c or entry to the compiled block. 
323 @c This is a
324 @c consequence of the way the compiler works: there is
325 @c nothing odd with your program. You will also see @code{:CLEANUP}
326 @c frames during the execution of @code{unwind-protect} cleanup
327 @c code.
328
329 With recursive functions, an additional @code{:EXTERNAL} frame may
330 appear before the frame representing the first call to the recursive
331 function. This is a consequence of the way the compiler works: there
332 is nothing odd with your program. You will also see @code{:CLEANUP}
333 frames during the execution of @code{unwind-protect} cleanup code.
334 The @code{:EXTERNAL} and @code{:CLEANUP} above are entry-point types,
335 visible only if @code{sb-debug:*show-entry-point-details*} os true.
336
337 @node  Debug Tail Recursion
338 @comment  node-name,  next,  previous,  up
339 @subsection Debug Tail Recursion
340 @cindex Tail recursion
341 @cindex Recursion, tail
342
343 The compiler is ``properly tail recursive.'' If a function call is in
344 a tail-recursive position, the stack frame will be deallocated
345 @emph{at the time of the call}, rather than after the call returns.
346 Consider this backtrace:
347
348 @example
349 (BAR ...) 
350 (FOO ...)
351 @end example
352
353 Because of tail recursion, it is not necessarily the case that
354 @code{FOO} directly called @code{BAR}.  It may be that @code{FOO}
355 called some other function @code{FOO2} which then called @code{BAR}
356 tail-recursively, as in this example:
357
358 @lisp
359 (defun foo ()
360   ...
361   (foo2 ...)
362   ...)
363
364 (defun foo2 (...)
365   ...
366   (bar ...))
367
368 (defun bar (...)
369   ...)
370 @end lisp
371
372 Usually the elimination of tail-recursive frames makes debugging more
373 pleasant, since these frames are mostly uninformative.  If there is any
374 doubt about how one function called another, it can usually be
375 eliminated by finding the source location in the calling frame.
376 @xref{Source Location Printing}.
377
378 The elimination of tail-recursive frames can be prevented by disabling
379 tail-recursion optimization, which happens when the @code{debug}
380 optimization quality is greater than @code{2}.  
381 @xref{Debugger Policy Control}.
382
383 @comment FIXME: reinstate this link once the chapter is in the manual.
384 @c For a more thorough discussion of tail recursion, @ref{tail-recursion}.
385
386 @node Unknown Locations and Interrupts
387 @comment  node-name,  next,  previous,  up
388 @subsection Unknown Locations and Interrupts
389 @cindex Unknown code locations
390 @cindex Locations, unknown
391 @cindex Interrupts
392 @cindex Errors, run-time
393
394 The debugger operates using special debugging information attached to
395 the compiled code.  This debug information tells the debugger what it
396 needs to know about the locations in the code where the debugger can
397 be invoked.  If the debugger somehow encounters a location not
398 described in the debug information, then it is said to be
399 @dfn{unknown}.  If the code location for a frame is unknown, then some
400 variables may be inaccessible, and the source location cannot be
401 precisely displayed.
402
403 There are three reasons why a code location could be unknown:
404
405 @itemize
406
407 @item
408 There is inadequate debug information due to the value of the @code{debug}
409 optimization quality.  @xref{Debugger Policy Control}.
410
411 @item
412 The debugger was entered because of an interrupt such as @key{C-c}.
413
414 @item
415 A hardware error such as ``@samp{bus error}'' occurred in code that was
416 compiled unsafely due to the value of the @code{safety} optimization
417 quality.
418 @comment FIXME: reinstate link when section on optimize qualities exists.
419 @c  @xref{optimize-declaration}.
420
421 @end itemize
422
423 In the last two cases, the values of argument variables are
424 accessible, but may be incorrect.  For more details on when variable
425 values are accessible, @ref{Variable Value Availability}.
426
427 It is possible for an interrupt to happen when a function call or
428 return is in progress.  The debugger may then flame out with some
429 obscure error or insist that the bottom of the stack has been reached,
430 when the real problem is that the current stack frame can't be
431 located.  If this happens, return from the interrupt and try again.
432
433
434 @node Variable Access
435 @comment  node-name,  next,  previous,  up
436 @section Variable Access
437 @cindex Debug variables
438 @cindex Variables, debugger access
439
440 There are two ways to access the current frame's local variables in
441 the debugger: @command{list-locals} and @code{sb-debug:var}.
442
443 The debugger doesn't really understand lexical scoping; it has just
444 one namespace for all the variables in the current stack frame.  If a
445 symbol is the name of multiple variables in the same function, then
446 the reference appears ambiguous, even though lexical scoping specifies
447 which value is visible at any given source location.  If the scopes of
448 the two variables are not nested, then the debugger can resolve the
449 ambiguity by observing that only one variable is accessible.
450
451 When there are ambiguous variables, the evaluator assigns each one a
452 small integer identifier.  The @code{sb-debug:var} function uses this
453 identifier to distinguish between ambiguous variables.  The
454 @command{list-locals} command prints the identifier.  In the
455 following example, there are two variables named @code{X}.  The first
456 one has identifier 0 (which is not printed), the second one has
457 identifier 1.
458
459 @example
460 X  =  1
461 X#1  =  2
462 @end example
463
464 @deffn {Debugger Command} list-locals [@var{prefix}]
465 This command prints the name and value of all variables in the current
466 frame whose name has the specified @var{prefix}.  @var{prefix} may be
467 a string or a symbol.  If no @var{prefix} is given, then all available
468 variables are printed.  If a variable has a potentially ambiguous
469 name, then the name is printed with a ``@code{#@var{identifier}}''
470 suffix, where @var{identifier} is the small integer used to make the
471 name unique.
472 @end deffn
473
474 @defun sb-debug:var @var{name} &optional @var{identifier}
475 This function returns the value of the variable in the current frame
476 with the specified @var{name}.  If supplied, @var{identifier}
477 determines which value to return when there are ambiguous variables.
478   
479 When @var{name} is a symbol, it is interpreted as the symbol name of
480 the variable, i.e. the package is significant.  If @var{name} is an
481 uninterned symbol (gensym), then return the value of the uninterned
482 variable with the same name.  If @var{name} is a string,
483 @code{sb-debug:var} interprets it as the prefix of a variable name
484 that must unambiguously complete to the name of a valid variable.
485
486 @var{identifier} is used to disambiguate the variable name; use
487 @command{list-locals} to find out the identifiers.
488 @end defun
489
490
491 @menu
492 * Variable Value Availability::  
493 * Note On Lexical Variable Access::  
494 @end menu
495
496 @node Variable Value Availability
497 @comment  node-name,  next,  previous,  up
498 @subsection Variable Value Availability
499 @cindex Availability of debug variables
500 @cindex Validity of debug variables
501 @cindex Debug optimization quality
502
503 The value of a variable may be unavailable to the debugger in portions
504 of the program where Lisp says that the variable is defined.  If a
505 variable value is not available, the debugger will not let you read or
506 write that variable.  With one exception, the debugger will never
507 display an incorrect value for a variable.  Rather than displaying
508 incorrect values, the debugger tells you the value is unavailable.
509
510 The one exception is this: if you interrupt (e.g., with @key{C-c}) or
511 if there is an unexpected hardware error such as ``@samp{bus error}''
512 (which should only happen in unsafe code), then the values displayed
513 for arguments to the interrupted frame might be
514 incorrect.@footnote{Since the location of an interrupt or hardware
515 error will always be an unknown location, non-argument variable values
516 will never be available in the interrupted frame.  @xref{Unknown
517 Locations and Interrupts}.}  This exception applies only to the
518 interrupted frame: any frame farther down the stack will be fine.
519
520 The value of a variable may be unavailable for these reasons:
521
522 @itemize
523
524 @item
525 The value of the @code{debug} optimization quality may have omitted debug
526 information needed to determine whether the variable is available.
527 Unless a variable is an argument, its value will only be available when
528 @code{debug} is at least @code{2}.
529
530 @item
531 The compiler did lifetime analysis and determined that the value was no longer
532 needed, even though its scope had not been exited.  Lifetime analysis is
533 inhibited when the @code{debug} optimization quality is @code{3}.
534
535 @item
536 The variable's name is an uninterned symbol (gensym).  To save space, the
537 compiler only dumps debug information about uninterned variables when the
538 @code{debug} optimization quality is @code{3}.
539
540 @item
541 The frame's location is unknown (@pxref{Unknown Locations and
542 Interrupts}) because the debugger was entered due to an interrupt or
543 unexpected hardware error.  Under these conditions the values of
544 arguments will be available, but might be incorrect.  This is the
545 exception mentioned above.
546
547 @item
548 The variable (or the code referencing it) was optimized out
549 of existence.  Variables with no reads are always optimized away.  The
550 degree to which the compiler deletes variables will depend on the
551 value of the @code{compilation-speed} optimization quality, but most
552 source-level optimizations are done under all compilation policies.
553
554 @item
555 The variable is never set and its definition looks like
556 @lisp
557 (LET ((var1 var2))
558    ...)
559 @end lisp
560 In this case, @code{var1} is substituted with @code{var2}.
561
562 @item 
563 The variable is never set and is referenced exactly once.  In this
564 case, the reference is substituted with the variable initial value.
565
566 @end itemize
567
568 Since it is especially useful to be able to get the arguments to a
569 function, argument variables are treated specially when the
570 @code{speed} optimization quality is less than @code{3} and the
571 @code{debug} quality is at least @code{1}.  With this compilation
572 policy, the values of argument variables are almost always available
573 everywhere in the function, even at unknown locations.  For
574 non-argument variables, @code{debug} must be at least @code{2} for
575 values to be available, and even then, values are only available at
576 known locations.
577
578
579 @node  Note On Lexical Variable Access
580 @comment  node-name,  next,  previous,  up
581 @subsection Note On Lexical Variable Access
582
583 When the debugger command loop establishes variable bindings for
584 available variables, these variable bindings have lexical scope and
585 dynamic extent.@footnote{The variable bindings are actually created
586 using the Lisp @code{symbol-macrolet} special form.}  You can close
587 over them, but such closures can't be used as upward funargs.
588
589 You can also set local variables using @code{setq}, but if the
590 variable was closed over in the original source and never set, then
591 setting the variable in the debugger may not change the value in all
592 the functions the variable is defined in.  Another risk of setting
593 variables is that you may assign a value of a type that the compiler
594 proved the variable could never take on.  This may result in bad
595 things happening.
596
597
598 @node Source Location Printing
599 @comment  node-name,  next,  previous,  up
600 @section Source Location Printing
601 @cindex Source location printing, debugger
602
603 One of the debugger's capabilities is source level debugging of
604 compiled code.  These commands display the source location for the
605 current frame:
606
607 @deffn {Debugger Command} source [@var{context}]
608 This command displays the file that the current frame's function was
609 defined from (if it was defined from a file), and then the source form
610 responsible for generating the code that the current frame was
611 executing.  If @var{context} is specified, then it is an integer
612 specifying the number of enclosing levels of list structure to print.
613 @end deffn
614
615 The source form for a location in the code is the innermost list present
616 in the original source that encloses the form responsible for generating
617 that code.  If the actual source form is not a list, then some enclosing
618 list will be printed.  For example, if the source form was a reference
619 to the variable @code{*some-random-special*}, then the innermost
620 enclosing evaluated form will be printed.  Here are some possible
621 enclosing forms:
622
623 @lisp
624 (let ((a *some-random-special*))
625   ...)
626
627 (+ *some-random-special* ...)
628 @end lisp
629
630 If the code at a location was generated from the expansion of a macro
631 or a source-level compiler optimization, then the form in the original
632 source that expanded into that code will be printed.  Suppose the file
633 @file{/usr/me/mystuff.lisp} looked like this:
634
635 @lisp
636 (defmacro mymac ()
637   '(myfun))
638
639 (defun foo ()
640   (mymac)
641   ...)
642 @end lisp
643
644 If @code{foo} has called @code{myfun}, and is waiting for it to
645 return, then the @command{source} command would print:
646
647 @example
648 ; File: /usr/me/mystuff.lisp
649
650 (MYMAC)
651 @end example
652
653 Note that the macro use was printed, not the actual function call form,
654 @code{(myfun)}.
655
656 If enclosing source is printed by giving an argument to
657 @command{source} or @command{vsource}, then the actual source form is
658 marked by wrapping it in a list whose first element is
659 @samp{#:***HERE***}.  In the previous example, @code{source 1} would
660 print:
661
662 @example
663 ; File: /usr/me/mystuff.lisp
664
665 (DEFUN FOO ()
666   (#:***HERE***
667    (MYMAC))
668   ...)
669 @end example
670
671
672 @menu
673 * How the Source is Found::     
674 * Source Location Availability::  
675 @end menu
676
677 @node  How the Source is Found
678 @comment  node-name,  next,  previous,  up
679 @subsection How the Source is Found
680
681 If the code was defined from Lisp by @code{compile} or
682 @code{eval}, then the source can always be reliably located.  If the
683 code was defined from a @file{fasl} file created by
684 @code{compile-file}, then the debugger gets the source forms it
685 prints by reading them from the original source file.  This is a
686 potential problem, since the source file might have moved or changed
687 since the time it was compiled.
688
689 The source file is opened using the @code{truename} of the source file
690 pathname originally given to the compiler.  This is an absolute pathname
691 with all logical names and symbolic links expanded.  If the file can't
692 be located using this name, then the debugger gives up and signals an
693 error.
694
695 If the source file can be found, but has been modified since the time it was
696 compiled, the debugger prints this warning:
697
698 @example
699 ; File has been modified since compilation:
700 ;   @var{filename}
701 ; Using form offset instead of character position.
702 @end example
703
704 where @var{filename} is the name of the source file.  It then proceeds
705 using a robust but not foolproof heuristic for locating the source.
706 This heuristic works if:
707
708 @itemize
709
710 @item
711 No top-level forms before the top-level form containing the source
712 have been added or deleted, and
713
714 @item
715 The top-level form containing the source has not been modified much.
716 (More precisely, none of the list forms beginning before the source
717 form have been added or deleted.)
718
719 @end itemize
720
721 If the heuristic doesn't work, the displayed source will be wrong, but will
722 probably be near the actual source.  If the ``shape'' of the top-level form in
723 the source file is too different from the original form, then an error will be
724 signaled.  When the heuristic is used, the source location commands are
725 noticeably slowed.
726
727 Source location printing can also be confused if (after the source was
728 compiled) a read-macro you used in the code was redefined to expand
729 into something different, or if a read-macro ever returns the same
730 @code{eq} list twice.  If you don't define read macros and don't use
731 @code{##} in perverted ways, you don't need to worry about this.
732
733
734 @node  Source Location Availability
735 @comment  node-name,  next,  previous,  up
736 @subsection Source Location Availability
737 @cindex Debug optimization quality
738 @cindex Block, basic
739 @cindex Block, start location
740
741 Source location information is only available when the @code{debug}
742 optimization quality is at least @code{2}.  If source location
743 information is unavailable, the source commands will give an error
744 message.
745
746 If source location information is available, but the source location
747 is unknown because of an interrupt or unexpected hardware error
748 (@pxref{Unknown Locations and Interrupts}), then the command will
749 print:
750
751 @example
752 Unknown location: using block start.
753 @end example
754
755 and then proceed to print the source location for the start of the
756 @emph{basic block} enclosing the code location.  It's a bit
757 complicated to explain exactly what a basic block is, but here are
758 some properties of the block start location:
759
760 @itemize
761
762 @item The block start location may be the same as the true location.
763
764 @item The block start location will never be later in the 
765 program's flow of control than the true location.
766
767 @item No conditional control structures (such as @code{if},
768 @code{cond}, @code{or}) will intervene between the block start and the
769 true location (but note that some conditionals present in the original
770 source could be optimized away.)  Function calls @emph{do not} end
771 basic blocks.
772
773 @item The head of a loop will be the start of a block.
774
775 @item The programming language concept of ``block structure'' and the
776 Lisp @code{block} special form are totally unrelated to the compiler's
777 basic block.
778
779 @end itemize
780
781 In other words, the true location lies between the printed location and the
782 next conditional (but watch out because the compiler may have changed the
783 program on you.)
784
785
786 @node Debugger Policy Control
787 @comment  node-name,  next,  previous,  up
788 @section Debugger Policy Control
789 @cindex Policy, debugger
790 @cindex Debug optimization quality
791 @cindex Optimize declaration
792 @cindex Inline expansion
793 @cindex Semi-inline expansion
794
795 The compilation policy specified by @code{optimize} declarations
796 affects the behavior seen in the debugger.  The @code{debug} quality
797 directly affects the debugger by controlling the amount of debugger
798 information dumped.  Other optimization qualities have indirect but
799 observable effects due to changes in the way compilation is done.
800
801 Unlike the other optimization qualities (which are compared in relative value
802 to evaluate tradeoffs), the @code{debug} optimization quality is directly
803 translated to a level of debug information.  This absolute interpretation
804 allows the user to count on a particular amount of debug information being
805 available even when the values of the other qualities are changed during
806 compilation.  These are the levels of debug information that correspond to the
807 values of the @code{debug} quality:
808
809 @table @code
810
811 @item 0
812 Only the function name and enough information to allow the stack to
813 be parsed.
814
815 @item > 0
816 Any level greater than @code{0} gives level @code{0} plus all argument
817 variables.  Values will only be accessible if the argument variable is
818 never set and @code{speed} is not @code{3}.  SBCL allows any real
819 value for optimization qualities.  It may be useful to specify
820 @code{0.5} to get backtrace argument display without argument
821 documentation.
822
823 @item 1
824 Level @code{1} provides argument documentation (printed arglists) and
825 derived argument/result type information.  This makes @code{describe}
826 more informative, and allows the compiler to do compile-time argument
827 count and type checking for any calls compiled at run-time.  This is
828 the default.
829
830 @item 2
831 Level @code{1} plus all interned local variables, source location
832 information, and lifetime information that tells the debugger when
833 arguments are available (even when @code{speed} is @code{3} or the
834 argument is set).
835  
836 @item > 2
837 Any level greater than @code{2} gives level @code{2} and in addition
838 disables tail-call optimization, so that the backtrace will contain
839 frames for all invoked functions, even those in tail positions.
840
841 @item 3
842 Level @code{2} plus all uninterned variables.  In addition, lifetime
843 analysis is disabled (even when @code{speed} is @code{3}), ensuring
844 that all variable values are available at any known location within
845 the scope of the binding.  This has a speed penalty in addition to the
846 obvious space penalty.
847
848 @item > (max speed space)
849 If @code{debug} is greater than both @code{speed} and @code{space},
850 the command @command{return} can be used to continue execution by
851 returning a value from the current stack frame.
852
853 @item > (max speed space compilation-speed)
854 If @code{debug} is greater than all of @code{speed}, @code{space} and
855 @code{compilation-speed} the code will be steppable (@pxref{Single Stepping}).
856
857 @end table
858
859 As you can see, if the @code{speed} quality is @code{3}, debugger performance is
860 degraded.  This effect comes from the elimination of argument variable
861 special-casing (@pxref{Variable Value Availability}).  Some degree of
862 speed/debuggability tradeoff is unavoidable, but the effect is not too drastic
863 when @code{debug} is at least @code{2}.
864
865 In addition to @code{inline} and @code{notinline} declarations, the
866 relative values of the @code{speed} and @code{space} qualities also
867 change whether functions are inline expanded.
868 @comment FIXME: link to section about inline expansion when it exists
869 @c (\pxlref{inline-expansion}.)
870 If a function is inline expanded, then
871 there will be no frame to represent the call, and the arguments will
872 be treated like any other local variable.  Functions may also be
873 ``semi-inline'', in which case there is a frame to represent the call,
874 but the call is to an optimized local version of the function, not to
875 the original function.
876
877
878 @node  Exiting Commands
879 @comment  node-name,  next,  previous,  up
880 @section Exiting Commands
881
882 These commands get you out of the debugger.
883
884 @deffn {Debugger Command} toplevel
885 Throw to top level.
886 @end deffn
887
888 @deffn {Debugger Command} restart [@var{n}]
889 Invokes the @var{n}th restart case as displayed by the @code{error}
890 command.  If @var{n} is not specified, the available restart cases are
891 reported.
892 @end deffn
893
894 @deffn {Debugger Command} continue
895 Calls @code{continue} on the condition given to @code{debug}.  If there is no
896 restart case named @var{continue}, then an error is signaled.
897 @end deffn
898
899 @deffn {Debugger Command} abort
900 Calls @code{abort} on the condition given to @code{debug}.  This is
901 useful for popping debug command loop levels or aborting to top level,
902 as the case may be.
903 @end deffn
904
905 @deffn {Debugger Command} return @var{value} 
906 Returns @var{value} from the current stack frame.  This command is
907 available when the @code{debug} optimization quality is greater than
908 both @code{speed} and @code{space}.  Care must be taken that the value
909 is of the same type as SBCL expects the stack frame to return.
910 @end deffn
911
912 @deffn {Debugger Command} restart-frame
913 Restarts execution of the current stack frame. This command is
914 available when the @code{debug} optimization quality is greater than
915 both @code{speed} and @code{space} and when the frame is for is a global
916 function. If the function is redefined in the debugger before the frame
917 is restarted, the new function will be used.
918 @end deffn
919
920 @node  Information Commands
921 @comment  node-name,  next,  previous,  up
922 @section Information Commands
923
924 Most of these commands print information about the current frame or
925 function, but a few show general information.
926
927 @deffn {Debugger Command} help
928 @deffnx {Debugger Command} ?
929 Displays a synopsis of debugger commands.
930 @end deffn
931
932 @deffn {Debugger Command} describe
933 Calls @code{describe} on the current function and displays the number of
934 local variables.
935 @end deffn
936
937 @deffn {Debugger Command} print
938 Displays the current function call as it would be displayed by moving to
939 this frame.
940 @end deffn
941
942 @deffn {Debugger Command} error
943 Prints the condition given to @code{invoke-debugger} and the active
944 proceed cases.
945 @end deffn
946
947 @deffn {Debugger Command} backtrace [@var{n}]
948 Displays all the frames from the current to the bottom. Only shows
949 @var{n} frames if specified. The printing is controlled by
950 @code{*debug-print-variable-alist*}.
951 @end deffn
952
953 @c The new instrumentation based single stepper doesn't support
954 @c the following commands, but BREAKPOINT at least should be
955 @c resurrectable via (TRACE FOO :BREAK T).
956
957 @c @cindex Breakpoints
958
959 @c SBCL supports setting of breakpoints inside compiled functions and
960 @c stepping of compiled code.  Breakpoints can only be set at known
961 @c locations (@pxref{Unknown Locations and Interrupts}), so these
962 @c commands are largely useless unless the @code{debug} optimize quality
963 @c is at least @code{2} (@pxref{Debugger Policy Control}).  These
964 @c commands manipulate breakpoints:
965
966 @c @deffn {Debugger Command} breakpoint @var{location} [@var{option} @var{value}]*
967 @c Set a breakpoint in some function.  @var{location} may be an integer
968 @c code location number (as displayed by @command{list-locations}) or a
969 @c keyword.  The keyword can be used to indicate setting a breakpoint at
970 @c the function start (@code{:start}, @code{:s}) or function end
971 @c (@code{:end}, @code{:e}).  The @command{breakpoint} command has
972 @c @code{:condition}, @code{:break}, @code{:print} and @code{:function}
973 @c options which work similarly to the @code{trace} options.
974 @c @end deffn
975
976 @c @deffn {Debugger Command} list-locations [@var{function}]
977 @c @deffnx {Debugger Command} ll  [@var{function}]
978 @c List all the code locations in the current frame's function, or in
979 @c @var{function} if it is supplied.  The display format is the code
980 @c location number, a colon and then the source form for that location:
981
982 @c @example
983 @c 3: (1- N)
984 @c @end example
985
986 @c If consecutive locations have the same source, then a numeric range
987 @c like @code{3-5:} will be printed.  For example, a default function
988 @c call has a known location both immediately before and after the call,
989 @c which would result in two code locations with the same source.  The
990 @c listed function becomes the new default function for breakpoint
991 @c setting (via the @command{breakpoint}) command.
992 @c @end deffn
993
994 @c @deffn {Debugger Command} list-breakpoints
995 @c @deffnx {Debugger Command} lb
996 @c List all currently active breakpoints with their breakpoint number.
997 @c @end deffn
998
999 @c @deffn {Debugger Command} delete-breakpoint [@var{number}]
1000 @c @deffnx {Debugger Command} db  [@var{number}]
1001 @c Delete a breakpoint specified by its breakpoint number.  If no number
1002 @c is specified, delete all breakpoints.
1003 @c @end deffn
1004
1005 @c @menu
1006 @c * Breakpoint Example::          
1007 @c @end menu
1008
1009 @c @node  Breakpoint Example,  , Breakpoint Commands, Breakpoint Commands
1010 @c @comment  node-name,  next,  previous,  up
1011 @c @subsection Breakpoint Example
1012
1013 @c Consider this definition of the factorial function:
1014
1015 @c @lisp
1016 @c (defun ! (n)
1017 @c   (if (zerop n)
1018 @c       1
1019 @c       (* n (! (1- n)))))
1020 @c @end lisp
1021
1022 @c This debugger session demonstrates the use of breakpoints:
1023
1024 @c @example
1025 @c * (break)  ; invoke debugger
1026
1027 @c debugger invoked on a SIMPLE-CONDITION in thread 11184: break
1028
1029 @c restarts (invokable by number or by possibly-abbreviated name):
1030 @c   0: [CONTINUE] Return from BREAK.
1031 @c   1: [ABORT   ] Reduce debugger level (leaving debugger, returning to toplevel).
1032 @c   2: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
1033 @c ("varargs entry for top level local call BREAK" "break")
1034 @c 0] ll #'!
1035
1036 @c 0-1: (SB-INT:NAMED-LAMBDA ! (N) (BLOCK ! (IF (ZEROP N) 1 (* N (! #)))))
1037 @c 2: (BLOCK ! (IF (ZEROP N) 1 (* N (! (1- N)))))
1038 @c 3: (ZEROP N)
1039 @c 4: (* N (! (1- N)))
1040 @c 5: (1- N)
1041 @c 6: (! (1- N))
1042 @c 7-8: (* N (! (1- N)))
1043 @c 9-10: (IF (ZEROP N) 1 (* N (! (1- N))))
1044 @c 0] br 4
1045
1046 @c (* N (! (1- N)))
1047 @c 1: 4 in !
1048 @c added
1049 @c 0] toplevel
1050
1051 @c FIXME: SBCL errored out, and not in the expected way ... Copying the
1052 @c output verbatim from the CMUCL manual for now.
1053
1054 @c common-lisp-user> (! 10) ; Call the function
1055
1056 @c *Breakpoint hit*
1057
1058 @c Restarts:
1059 @c   0: [CONTINUE] Return from BREAK.
1060 @c   1: [ABORT   ] Return to Top-Level.
1061
1062 @c Debug  (type H for help)
1063
1064 @c (! 10) ; We are now in first call (arg 10) before the multiply
1065 @c Source: (* N (! (1- N)))
1066 @c 3] st
1067
1068 @c *Step*
1069
1070 @c (! 10) ; We have finished evaluation of (1- n)
1071 @c Source: (1- N)
1072 @c 3] st
1073
1074 @c *Breakpoint hit*
1075
1076 @c Restarts:
1077 @c   0: [CONTINUE] Return from BREAK.
1078 @c   1: [ABORT   ] Return to Top-Level.
1079
1080 @c Debug  (type H for help)
1081
1082 @c (! 9) ; We hit the breakpoint in the recursive call
1083 @c Source: (* N (! (1- N)))
1084 @c 3] 
1085 @c @end example
1086
1087
1088 @node  Function Tracing
1089 @comment  node-name,  next,  previous,  up
1090 @section Function Tracing
1091 @cindex Tracing
1092 @cindex Function, tracing
1093
1094 The tracer causes selected functions to print their arguments and
1095 their results whenever they are called.  Options allow conditional
1096 printing of the trace information and conditional breakpoints on
1097 function entry or exit.
1098
1099 @include macro-common-lisp-trace.texinfo
1100
1101 @include macro-common-lisp-untrace.texinfo
1102
1103 @include var-sb-debug-star-trace-indentation-step-star.texinfo
1104
1105 @include var-sb-debug-star-max-trace-indentation-star.texinfo
1106
1107 @include var-sb-debug-star-trace-encapsulate-default-star.texinfo
1108
1109 @include var-sb-debug-star-trace-values-star.texinfo
1110
1111 @comment FIXME rudi 2004-03-26: encapsulate is (per TODO file as of
1112 @comment 0.8.9) in a state of flux.  When it's sorted out, revive the
1113 @comment cmucl documentation.
1114
1115 @node Single Stepping
1116 @comment  node-name,  next,  previous,  up
1117 @section Single Stepping
1118 @cindex Stepper
1119 @cindex Single Stepping
1120
1121 SBCL includes an instrumentation based single-stepper for compiled
1122 code, that can be invoked via the @code{step} macro, or from within
1123 the debugger. @xref{Debugger Policy Control}, for details on enabling
1124 stepping for compiled code.
1125
1126 The following debugger commands are used for controlling single stepping.
1127
1128 @deffn {Debugger Command} start
1129 Selects the @code{continue} restart if one exists and starts single stepping.
1130 None of the other single stepping commands can be used before stepping has
1131 been started either by using @code{start} or by using the standard 
1132 @code{step} macro.
1133 @end deffn
1134
1135 @deffn {Debugger Command} step
1136 Steps into the current form. Stepping will be resumed when the next
1137 form that has been compiled with stepper instrumentation is evaluated.
1138 @end deffn
1139
1140 @deffn {Debugger Command} next
1141 Steps over the current form. Stepping will be disabled until evaluation of
1142 the form is complete.
1143 @end deffn
1144
1145 @deffn {Debugger Command} out
1146 Steps out of the current frame. Stepping will be disabled until the 
1147 topmost stack frame that had been stepped into returns.
1148 @end deffn
1149
1150 @deffn {Debugger Command} stop
1151 Stops the single stepper and resumes normal execution.
1152 @end deffn
1153
1154 @include macro-common-lisp-step.texinfo