1.0.29.8: :PTY and stream arguments in RUN-PROGRAM

[sbcl.git] / doc / manual / debugger.texinfo

diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo
index 3713a9a..45a4b99 100644 (file)
--- a/doc/manual/debugger.texinfo
+++ b/doc/manual/debugger.texinfo
@@ -1,33 +1,15 @@
-@node  The Debugger, Efficiency, The Compiler, Top
+@node Debugger

 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up

-@chapter The Debugger
+@chapter Debugger

 @cindex Debugger
 
 @cindex Debugger
 

-The SBCL debugger (as the CMUCL debugger it was derived from) has very
-good support for source-level debugging of compiled code.  Although
-some other debuggers allow access of variables by name, this seems to
-be the first Lisp debugger that:
-
-@itemize
-
-@item
-Tells you when a variable doesn't have a value because it hasn't been
-initialized yet or has already been deallocated, or
-
-@item
-Can display the precise source location corresponding to a code
-location in the debugged program.
-
-@end itemize
-
-These features allow the debugging of compiled code to be made almost
-indistinguishable from interpreted code debugging.
-
+This chapter documents the debugging facilities of SBCL, including
+the debugger, single-stepper and @code{trace}, and the effect of
+@code{(optimize debug)} declarations.

 
 @menu
 
 @menu

-* Starting the Debugger::       
-* The Debugger Command Loop::   
-* Controlling Printing in the Debugger::  
+* Debugger Entry::              
+* Debugger Command Loop::       

 * Stack Frames::                
 * Variable Access::             
 * Source Location Printing::    
 * Stack Frames::                
 * Variable Access::             
 * Source Location Printing::    

@@ -35,112 +17,116 @@ indistinguishable from interpreted code debugging.
 * Exiting Commands::            
 * Information Commands::        
 * Function Tracing::            
 * Exiting Commands::            
 * Information Commands::        
 * Function Tracing::            

+* Single Stepping::             

 @end menu
 
 @end menu
 

-@node  Starting the Debugger, The Debugger Command Loop, The Debugger, The Debugger
+@node Debugger Entry

 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up

-@section Starting the Debugger
-
-The debugger is an interactive command loop that allows a user to examine
-the function call stack.  The debugger is invoked when:
+@section Debugger Entry

 
 

-@itemize
-
-@item
-A @code{serious-condition} is signaled, and it is not handled, or
-
-@item
-@code{error} is called, and the condition it signals is not handled,
-or
-
-@item
-the debugger is explicitly entered with the Lisp @code{break} or
-@code{debug} functions.
+@menu
+* Debugger Banner::             
+* Debugger Invocation::         
+@end menu

 
 

-@end itemize
+@node Debugger Banner
+@comment  node-name,  next,  previous,  up
+@subsection Debugger Banner

 
 

-When you enter the TTY debugger, it looks something like this:
+When you enter the debugger, it looks something like this:

 
 @example
 debugger invoked on a TYPE-ERROR in thread 11184:
   The value 3 is not of type LIST.
 
 @example
 debugger invoked on a TYPE-ERROR in thread 11184:
   The value 3 is not of type LIST.

+
+You can type HELP for debugger help, or (SB-EXT:QUIT) to exit from SBCL.
+

 restarts (invokable by number or by possibly-abbreviated name):
   0: [ABORT   ] Reduce debugger level (leaving debugger, returning to toplevel).
   1: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
 restarts (invokable by number or by possibly-abbreviated name):
   0: [ABORT   ] Reduce debugger level (leaving debugger, returning to toplevel).
   1: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.

-(CAR 1 3)[:EXTERNAL]
+(CAR 1 3)

 0]
 @end example
 
 The first group of lines describe what the error was that put us in
 0]
 @end example
 
 The first group of lines describe what the error was that put us in

-the debugger.  In this case @code{car} was called on @code{3}.  After
-@samp{restarts} is a list of all the ways that we can restart
-execution after this error.  In this case, both options return to
-top-level.  After printing its banner, the debugger prints the current
-frame and the debugger prompt.
+the debugger.  In this case @code{car} was called on @code{3}, causing
+a @code{type-error}.  

 
 

+This is followed by the ``beginner help line'', which appears only if
+@code{sb-ext:*debugger-beginner-help*} is true (default).

 
 

-@node  The Debugger Command Loop, Controlling Printing in the Debugger, Starting the Debugger, The Debugger
+Next comes a listing of the active restart names, along with their
+descriptions -- the ways we can restart execution after this error. In
+this case, both options return to top-level. Restarts can be selected
+by entering the corresponding number or name.
+
+The current frame appears right underneath the restarts, immediately
+followed by the debugger prompt.
+
+@node Debugger Invocation

 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up

-@section The Debugger Command Loop
-@cindex Evaluation, in the debugger
-
-The debugger is an interactive read-eval-print loop much like the normal
-top-level, but some symbols are interpreted as debugger commands instead
-of being evaluated.  A debugger command starts with the symbol name of
-the command, possibly followed by some arguments on the same line.  Some
-commands prompt for additional input.  Debugger commands can be
-abbreviated by any unambiguous prefix: @command{help} can be typed as
-@samp{h}, @samp{he}, etc.  For convenience, some commands have
-ambiguous one-letter abbreviations: @samp{f} for @command{frame}.
-
-The package is not significant in debugger commands; any symbol with the
-name of a debugger command will work.  If you want to show the value of
-a variable that happens also to be the name of a debugger command, you
-can use the @command{list-locals} command or the @code{sb-debug:var}
-function, or you can wrap the variable in a @code{progn} to hide it from
-the command loop.
+@subsection Debugger Invocation

 
 

-The debugger prompt is ``@code{@var{frame}]}'', where @var{frame} is
-the number of the current frame.  Frames are numbered starting from
-zero at the top (most recent call), increasing down to the bottom.
-The current frame is the frame that commands refer to.  The current
-frame also provides the lexical environment for evaluation of
-non-command forms.
+The debugger is invoked when:

 
 

- The debugger evaluates forms in the lexical environment of the
-functions being debugged.  The debugger can only access variables.
-You can't @code{go} or @code{return-from} into a function, and you
-can't call local functions.  Special variable references are evaluated
-with their current value (the innermost binding around the debugger
-invocation) -- you don't get the value that the special had in the
-current frame.  For more information on debugger variable access, see
-@ref{Variable Access}.
+@itemize

 
 

+@item
+@code{error} is called, and the condition it signals is not handled.

 
 

-@node Controlling Printing in the Debugger, Stack Frames, The Debugger Command Loop, The Debugger
-@comment  node-name,  next,  previous,  up
-@section Controlling Printing in the Debugger
+@item
+@code{break} is called, or @code{signal} is called with a condition
+that matches the current @code{*break-on-signals*}.

 
 

-In the debugger, it is possible to override the printing behaviour of
-the REPL.
+@item
+the debugger is explicitly entered with the @code{invoke-debugger}
+function.

 
 

-@defvr {Variable} *debug-print-variable-alist*
+@end itemize

 
 

-An association list describing new bindings for special variables
-(typically *PRINT-FOO* variables) to be used within the debugger, e.g.
-@lisp
-((*PRINT-LENGTH* . 10) (*PRINT-LEVEL* . 6) (*PRINT-PRETTY* . NIL))
-@end lisp
-The variables in the @code{car} position are bound to the values in
-the @code{cdr} during the execution of some debug commands.  When
-evaluating arbitrary expressions in the debugger, the normal values of
-the printer control variables are in effect. @c FIXME: is this correct?
-@code{*debug-print-variable-alist*} does not contain any bindings
-initially.
+When the debugger is invoked by a condition, ANSI mandates that the
+value of @code{*debugger-hook*}, if any, be called with two arguments:
+the condition that caused the debugger to be invoked and the previous
+value of @code{*debugger-hook*}. When this happens,
+@code{*debugger-hook*} is bound to NIL to prevent recursive errors.
+However, ANSI also mandates that @code{*debugger-hook*} not be invoked
+when the debugger is to be entered by the @code{break} function. For
+users who wish to provide an alternate debugger interface (and thus
+catch @code{break} entries into the debugger), SBCL provides
+@code{sb-ext:*invoke-debugger-hook*}, which is invoked during any
+entry into the debugger.
+
+@include var-sb-ext-star-invoke-debugger-hook-star.texinfo
+
+@node  Debugger Command Loop
+@comment  node-name,  next,  previous,  up
+@section Debugger Command Loop
+
+The debugger is an interactive read-eval-print loop much like the
+normal top level, but some symbols are interpreted as debugger
+commands instead of being evaluated. A debugger command starts with
+the symbol name of the command, possibly followed by some arguments on
+the same line. Some commands prompt for additional input. Debugger
+commands can be abbreviated by any unambiguous prefix: @command{help}
+can be typed as @samp{h}, @samp{he}, etc.
+
+The package is not significant in debugger commands; any symbol with
+the name of a debugger command will work. If you want to show the
+value of a variable that happens also to be the name of a debugger
+command you can wrap the variable in a @code{progn} to hide it from
+the command loop.

 
 

-@end defvr
+The debugger prompt is ``@code{@var{frame}]}'', where @var{frame} is
+the number of the current frame.  Frames are numbered starting from
+zero at the top (most recent call), increasing down to the bottom.
+The current frame is the frame that commands refer to. 
+
+It is possible to override the normal printing behaviour in the
+debugger by using the @code{sb-ext:*debug-print-variable-alist*}.

 
 

-@node  Stack Frames, Variable Access, Controlling Printing in the Debugger, The Debugger
+@include var-sb-ext-star-debug-print-variable-alist-star.texinfo
+
+@node  Stack Frames

 @comment  node-name,  next,  previous,  up
 @section Stack Frames
 @cindex Stack frames
 @comment  node-name,  next,  previous,  up
 @section Stack Frames
 @cindex Stack frames

@@ -152,31 +138,29 @@ what it is doing.  Frames have:
 @itemize
 
 @item
 @itemize
 
 @item

-@dfn{Variables} (@pxref{Variable Access}), which are the values being operated
-on, and
+@dfn{variables} (@pxref{Variable Access}), which are the values being operated
+on.

 
 @item
 
 @item

-@dfn{Arguments} to the call (which are really just particularly
-interesting variables), and
+@dfn{arguments} to the call (which are really just particularly
+interesting variables).

 
 @item
 
 @item

-A current location (@pxref{Source Location Printing}), which is the place in
-the program where the function was running when it stopped to call
-another function, or because of an interrupt or error.
+a current source location (@pxref{Source Location Printing}), which is
+the place in the program where the function was running when it
+stopped to call another function, or because of an interrupt or error.

 
 @end itemize
 
 
 @end itemize
 

-

 @menu
 * Stack Motion::                
 * How Arguments are Printed::   
 * Function Names::              
 @menu
 * Stack Motion::                
 * How Arguments are Printed::   
 * Function Names::              

-* Funny Frames::                

 * Debug Tail Recursion::        
 * Unknown Locations and Interrupts::  
 @end menu
 
 * Debug Tail Recursion::        
 * Unknown Locations and Interrupts::  
 @end menu
 

-@node  Stack Motion, How Arguments are Printed, Stack Frames, Stack Frames
+@node  Stack Motion

 @comment  node-name,  next,  previous,  up
 @subsection Stack Motion
 
 @comment  node-name,  next,  previous,  up
 @subsection Stack Motion
 

@@ -209,7 +193,7 @@ was entered.
 @end deffn
 
 
 @end deffn
 
 

-@node  How Arguments are Printed, Function Names, Stack Motion, Stack Frames
+@node  How Arguments are Printed

 @comment  node-name,  next,  previous,  up
 @subsection How Arguments are Printed
 
 @comment  node-name,  next,  previous,  up
 @subsection How Arguments are Printed
 

@@ -288,41 +272,28 @@ unavailable or not known to be available (@pxref{Variable Access}),
 then @samp{#<unavailable-arg>} will be printed instead of the argument
 value.
 
 then @samp{#<unavailable-arg>} will be printed instead of the argument
 value.
 

-Printing of argument values is controlled by
-@code{*debug-print-variable-alist*}.  @xref{Controlling Printing in
-the Debugger}.
+ Note that inline expansion and open-coding affect what frames
+are present in the debugger, see @ref{Debugger Policy Control}.
+@comment FIXME: link here to section about open coding once it exists.
+@c @ref{open-coding}

 
 
 
 

-@node  Function Names, Funny Frames, How Arguments are Printed, Stack Frames
+@node  Function Names

 @comment  node-name,  next,  previous,  up
 @subsection Function Names
 
 @comment  node-name,  next,  previous,  up
 @subsection Function Names
 

-If a function is defined by @code{defun}, @code{labels}, or
-@code{flet}, then the debugger will print the actual function name
-after the open parenthesis, like:
-
-@example
-(STRING-UPCASE "test case" :START 0 :END NIL)
-((SETF AREF) #\a "for" 1)
-@end example
-
-Otherwise, the function name is a string, and will be printed in
-quotes:
-
-@example
-("DEFUN MYFUN" BAR)
-("DEFMACRO DO" (DO ((I 0 (1+ I))) ((= I 13))) NIL)
-("SETQ *GC-NOTIFY-BEFORE*")
-@end example
-
-This string name is derived from the @code{def@var{mumble}} form
-that encloses or expanded into the lambda, or the outermost enclosing
-form if there is no @code{def@var{mumble}}.
+If a function is defined by @code{defun} it will appear in backtrace
+by that name. Functions defined by @code{labels} and @code{flet} will
+appear as @code{(FLET <name>)} and @code{(LABELS <name>)} respectively.
+Anonymous lambdas will appear as @code{(LAMDBA <lambda-list>)}.

 
 

+@menu
+* Entry Point Details::         
+@end menu

 
 

-@node  Funny Frames, Debug Tail Recursion, Function Names, Stack Frames
+@node  Entry Point Details

 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up

-@subsection Funny Frames
+@subsubsection Entry Point Details

 @cindex External entry points
 @cindex Entry points, external
 @cindex Block compilation, debugger implications
 @cindex External entry points
 @cindex Entry points, external
 @cindex Block compilation, debugger implications

@@ -330,71 +301,49 @@ form if there is no @code{def@var{mumble}}.
 @cindex Optional, stack frame kind
 @cindex Cleanup, stack frame kind
 
 @cindex Optional, stack frame kind
 @cindex Cleanup, stack frame kind
 

-Sometimes the evaluator introduces new functions that are used to
+Sometimes the compiler introduces new functions that are used to

 implement a user function, but are not directly specified in the
 implement a user function, but are not directly specified in the

-source.  The main place this is done is for checking argument type and
-syntax.  Usually these functions do their thing and then go away, and
-thus are not seen on the stack in the debugger.  But when you get some
-sort of error during lambda-list processing, you end up in the
-debugger on one of these funny frames.
-
-These funny frames are flagged by printing
-``@code{[@var{keyword}]}'' after the parentheses.  For example,
-this call:
-
-@lisp
-(car 'a 'b)
-@end lisp
-
-will look like this:
-
-@example
-(CAR 2 A)[:EXTERNAL]
-@end example
-
-And this call:
-
-@lisp
-(string-upcase "test case" :end)
-@end lisp
-
-would look like this:
-
-@example
-("SB!INT:&MORE processing" "test case" 1053984 1)[:OPTIONAL]
-@end example
-
-As you can see, these frames have only a vague resemblance to the
-original call.  Fortunately, the error message displayed when you
-enter the debugger will usually tell you what problem is (in these
-cases, too many arguments and odd keyword arguments.)  Also, if you go
-down the stack to the frame for the calling function, you can display
-the original source.  @xref{Source Location Printing}.
-
-@c FIXME: is the block-compilation part correct for SBCL?
-
-With recursive or block compiled functions, an @code{:EXTERNAL} frame
-may appear before the frame representing the first call to the
-recursive function or entry to the compiled block. This is a
-consequence of the way the compiler does block compilation: there is
-nothing odd with your program. You will also see @code{:CLEANUP}
-frames during the execution of @code{unwind-protect} cleanup
-code. Note that inline expansion and open-coding affect what frames
-are present in the debugger, see @ref{Debugger Policy Control}.
-@comment FIXME: link here to section about open coding once it exists.
-@c @ref{open-coding}
-
-
-@node  Debug Tail Recursion, Unknown Locations and Interrupts, Funny Frames, Stack Frames
+source. This is mostly done for argument type and count checking.
+
+The debugger will normally show these entry point functions as if
+they were the normal main entry point, but more detail can be obtained
+by setting @code{sb-debug:*show-entry-point-details*} to true; this is
+primarily useful for debugging SBCL itself, but may help pinpoint
+problems that occur during lambda-list processing.
+
+@c FIXME: the following bits talked about block-compilation, but
+@c we don't currently support it...
+
+@c With recursive 
+@c or block compiled 
+@c functions, an additional @code{:EXTERNAL} frame
+@c may appear before the frame representing the first call to the
+@c recursive function
+@c or entry to the compiled block. 
+@c This is a
+@c consequence of the way the compiler works: there is
+@c nothing odd with your program. You will also see @code{:CLEANUP}
+@c frames during the execution of @code{unwind-protect} cleanup
+@c code.
+
+With recursive functions, an additional @code{:EXTERNAL} frame may
+appear before the frame representing the first call to the recursive
+function. This is a consequence of the way the compiler works: there
+is nothing odd with your program. You will also see @code{:CLEANUP}
+frames during the execution of @code{unwind-protect} cleanup code.
+The @code{:EXTERNAL} and @code{:CLEANUP} above are entry-point types,
+visible only if @code{sb-debug:*show-entry-point-details*} os true.
+
+@node  Debug Tail Recursion

 @comment  node-name,  next,  previous,  up
 @subsection Debug Tail Recursion
 @cindex Tail recursion
 @cindex Recursion, tail
 
 @comment  node-name,  next,  previous,  up
 @subsection Debug Tail Recursion
 @cindex Tail recursion
 @cindex Recursion, tail
 

-Both the compiler and the interpreter are ``properly tail recursive.''
-If a function call is in a tail-recursive position, the stack frame
-will be deallocated @emph{at the time of the call}, rather than after
-the call returns.  Consider this backtrace:
+The compiler is ``properly tail recursive.'' If a function call is in
+a tail-recursive position, the stack frame will be deallocated
+@emph{at the time of the call}, rather than after the call returns.
+Consider this backtrace:

 
 @example
 (BAR ...) 
 
 @example
 (BAR ...) 

@@ -421,8 +370,8 @@ tail-recursively, as in this example:
 @end lisp
 
 Usually the elimination of tail-recursive frames makes debugging more
 @end lisp
 
 Usually the elimination of tail-recursive frames makes debugging more

-pleasant, since theses frames are mostly uninformative.  If there is
-any doubt about how one function called another, it can usually be
+pleasant, since these frames are mostly uninformative.  If there is any
+doubt about how one function called another, it can usually be

 eliminated by finding the source location in the calling frame.
 @xref{Source Location Printing}.
 
 eliminated by finding the source location in the calling frame.
 @xref{Source Location Printing}.
 

@@ -434,8 +383,7 @@ optimization quality is greater than @code{2}.
 @comment FIXME: reinstate this link once the chapter is in the manual.
 @c For a more thorough discussion of tail recursion, @ref{tail-recursion}.
 
 @comment FIXME: reinstate this link once the chapter is in the manual.
 @c For a more thorough discussion of tail recursion, @ref{tail-recursion}.
 

-
-@node Unknown Locations and Interrupts,  , Debug Tail Recursion, Stack Frames
+@node Unknown Locations and Interrupts

 @comment  node-name,  next,  previous,  up
 @subsection Unknown Locations and Interrupts
 @cindex Unknown code locations
 @comment  node-name,  next,  previous,  up
 @subsection Unknown Locations and Interrupts
 @cindex Unknown code locations

@@ -483,7 +431,7 @@ when the real problem is that the current stack frame can't be
 located.  If this happens, return from the interrupt and try again.
 
 
 located.  If this happens, return from the interrupt and try again.
 
 

-@node Variable Access, Source Location Printing, Stack Frames, The Debugger
+@node Variable Access

 @comment  node-name,  next,  previous,  up
 @section Variable Access
 @cindex Debug variables
 @comment  node-name,  next,  previous,  up
 @section Variable Access
 @cindex Debug variables

@@ -545,7 +493,7 @@ that must unambiguously complete to the name of a valid variable.
 * Note On Lexical Variable Access::  
 @end menu
 
 * Note On Lexical Variable Access::  
 @end menu
 

-@node Variable Value Availability, Note On Lexical Variable Access, Variable Access, Variable Access
+@node Variable Value Availability

 @comment  node-name,  next,  previous,  up
 @subsection Variable Value Availability
 @cindex Availability of debug variables
 @comment  node-name,  next,  previous,  up
 @subsection Variable Value Availability
 @cindex Availability of debug variables

@@ -628,7 +576,7 @@ values to be available, and even then, values are only available at
 known locations.
 
 
 known locations.
 
 

-@node  Note On Lexical Variable Access,  , Variable Value Availability, Variable Access
+@node  Note On Lexical Variable Access

 @comment  node-name,  next,  previous,  up
 @subsection Note On Lexical Variable Access
 
 @comment  node-name,  next,  previous,  up
 @subsection Note On Lexical Variable Access
 

@@ -647,7 +595,7 @@ proved the variable could never take on.  This may result in bad
 things happening.
 
 
 things happening.
 
 

-@node Source Location Printing, Debugger Policy Control, Variable Access, The Debugger
+@node Source Location Printing

 @comment  node-name,  next,  previous,  up
 @section Source Location Printing
 @cindex Source location printing, debugger
 @comment  node-name,  next,  previous,  up
 @section Source Location Printing
 @cindex Source location printing, debugger

@@ -726,7 +674,7 @@ print:
 * Source Location Availability::  
 @end menu
 
 * Source Location Availability::  
 @end menu
 

-@node  How the Source is Found, Source Location Availability, Source Location Printing, Source Location Printing
+@node  How the Source is Found

 @comment  node-name,  next,  previous,  up
 @subsection How the Source is Found
 
 @comment  node-name,  next,  previous,  up
 @subsection How the Source is Found
 

@@ -773,7 +721,7 @@ form have been added or deleted.)
 If the heuristic doesn't work, the displayed source will be wrong, but will
 probably be near the actual source.  If the ``shape'' of the top-level form in
 the source file is too different from the original form, then an error will be
 If the heuristic doesn't work, the displayed source will be wrong, but will
 probably be near the actual source.  If the ``shape'' of the top-level form in
 the source file is too different from the original form, then an error will be

-signaled.  When the heuristic is used, the the source location commands are
+signaled.  When the heuristic is used, the source location commands are

 noticeably slowed.
 
 Source location printing can also be confused if (after the source was
 noticeably slowed.
 
 Source location printing can also be confused if (after the source was

@@ -783,7 +731,7 @@ into something different, or if a read-macro ever returns the same
 @code{##} in perverted ways, you don't need to worry about this.
 
 
 @code{##} in perverted ways, you don't need to worry about this.
 
 

-@node  Source Location Availability,  , How the Source is Found, Source Location Printing
+@node  Source Location Availability

 @comment  node-name,  next,  previous,  up
 @subsection Source Location Availability
 @cindex Debug optimization quality
 @comment  node-name,  next,  previous,  up
 @subsection Source Location Availability
 @cindex Debug optimization quality

@@ -813,7 +761,7 @@ some properties of the block start location:
 
 @item The block start location may be the same as the true location.
 
 
 @item The block start location may be the same as the true location.
 

-@item The block start location will never be later in the the
+@item The block start location will never be later in the 

 program's flow of control than the true location.
 
 @item No conditional control structures (such as @code{if},
 program's flow of control than the true location.
 
 @item No conditional control structures (such as @code{if},

@@ -835,7 +783,7 @@ next conditional (but watch out because the compiler may have changed the
 program on you.)
 
 
 program on you.)
 
 

-@node Debugger Policy Control, Exiting Commands, Source Location Printing, The Debugger
+@node Debugger Policy Control

 @comment  node-name,  next,  previous,  up
 @section Debugger Policy Control
 @cindex Policy, debugger
 @comment  node-name,  next,  previous,  up
 @section Debugger Policy Control
 @cindex Policy, debugger

@@ -884,7 +832,7 @@ Level @code{1} plus all interned local variables, source location
 information, and lifetime information that tells the debugger when
 arguments are available (even when @code{speed} is @code{3} or the
 argument is set).
 information, and lifetime information that tells the debugger when
 arguments are available (even when @code{speed} is @code{3} or the
 argument is set).

-
+ 

 @item > 2
 Any level greater than @code{2} gives level @code{2} and in addition
 disables tail-call optimization, so that the backtrace will contain
 @item > 2
 Any level greater than @code{2} gives level @code{2} and in addition
 disables tail-call optimization, so that the backtrace will contain

@@ -902,6 +850,10 @@ If @code{debug} is greater than both @code{speed} and @code{space},
 the command @command{return} can be used to continue execution by
 returning a value from the current stack frame.
 
 the command @command{return} can be used to continue execution by
 returning a value from the current stack frame.
 

+@item > (max speed space compilation-speed)
+If @code{debug} is greater than all of @code{speed}, @code{space} and
+@code{compilation-speed} the code will be steppable (@pxref{Single Stepping}).
+

 @end table
 
 As you can see, if the @code{speed} quality is @code{3}, debugger performance is
 @end table
 
 As you can see, if the @code{speed} quality is @code{3}, debugger performance is

@@ -923,7 +875,7 @@ but the call is to an optimized local version of the function, not to
 the original function.
 
 
 the original function.
 
 

-@node  Exiting Commands, Information Commands, Debugger Policy Control, The Debugger
+@node  Exiting Commands

 @comment  node-name,  next,  previous,  up
 @section Exiting Commands
 
 @comment  node-name,  next,  previous,  up
 @section Exiting Commands
 

@@ -950,15 +902,22 @@ useful for popping debug command loop levels or aborting to top level,
 as the case may be.
 @end deffn
 
 as the case may be.
 @end deffn
 

-@deffn {Debugger Command} return @var{value}
+@deffn {Debugger Command} return @var{value} 

 Returns @var{value} from the current stack frame.  This command is
 available when the @code{debug} optimization quality is greater than
 both @code{speed} and @code{space}.  Care must be taken that the value
 is of the same type as SBCL expects the stack frame to return.
 @end deffn
 
 Returns @var{value} from the current stack frame.  This command is
 available when the @code{debug} optimization quality is greater than
 both @code{speed} and @code{space}.  Care must be taken that the value
 is of the same type as SBCL expects the stack frame to return.
 @end deffn
 

+@deffn {Debugger Command} restart-frame
+Restarts execution of the current stack frame. This command is
+available when the @code{debug} optimization quality is greater than
+both @code{speed} and @code{space} and when the frame is for is a global
+function. If the function is redefined in the debugger before the frame
+is restarted, the new function will be used.
+@end deffn

 
 

-@node  Information Commands, Function Tracing, Exiting Commands, The Debugger
+@node  Information Commands

 @comment  node-name,  next,  previous,  up
 @section Information Commands
 
 @comment  node-name,  next,  previous,  up
 @section Information Commands
 

@@ -986,24 +945,19 @@ proceed cases.
 @end deffn
 
 @deffn {Debugger Command} backtrace [@var{n}]
 @end deffn
 
 @deffn {Debugger Command} backtrace [@var{n}]

-Displays all the frames from the current to the bottom.  Only shows
-@var{n} frames if specified.  The printing is controlled by @code{*debug-print-variable-alist*}.
+Displays all the frames from the current to the bottom. Only shows
+@var{n} frames if specified. The printing is controlled by
+@code{*debug-print-variable-alist*}.

 @end deffn
 
 @end deffn
 

-@comment  FIXME (rudi 2004-03-31): sbcl doesn't support breakpoints
-@comment  and stepping as of version 0.8.9.  The `list-locations'
-@comment  command works, but executing a function leads to an error
-@comment  when a breakpoint is hit.  When stepping works, the
-@comment  commented-out section below should be reinstated and the
-@comment  example output updated to correspont to sbcl's behaviour.
+@c The new instrumentation based single stepper doesn't support
+@c the following commands, but BREAKPOINT at least should be
+@c resurrectable via (TRACE FOO :BREAK T).

 
 

-@c @node  Breakpoint Commands, , Information Commands, The Debugger
-@c @comment  node-name,  next,  previous,  up
-@c @section Breakpoint Commands

 @c @cindex Breakpoints
 
 @c SBCL supports setting of breakpoints inside compiled functions and
 @c @cindex Breakpoints
 
 @c SBCL supports setting of breakpoints inside compiled functions and

-@c stepping of compiled code.  Breakpoints can only be set at at known
+@c stepping of compiled code.  Breakpoints can only be set at known

 @c locations (@pxref{Unknown Locations and Interrupts}), so these
 @c commands are largely useless unless the @code{debug} optimize quality
 @c is at least @code{2} (@pxref{Debugger Policy Control}).  These
 @c locations (@pxref{Unknown Locations and Interrupts}), so these
 @c commands are largely useless unless the @code{debug} optimize quality
 @c is at least @code{2} (@pxref{Debugger Policy Control}).  These

@@ -1048,12 +1002,6 @@ Displays all the frames from the current to the bottom.  Only shows
 @c is specified, delete all breakpoints.
 @c @end deffn
 
 @c is specified, delete all breakpoints.
 @c @end deffn
 

-@c @deffn {Debugger Command} step
-@c Step to the next possible breakpoint location in the current function.
-@c This always steps over function calls, instead of stepping into them.
-@c @end deffn
-
-

 @c @menu
 @c * Breakpoint Example::          
 @c @end menu
 @c @menu
 @c * Breakpoint Example::          
 @c @end menu

@@ -1137,7 +1085,7 @@ Displays all the frames from the current to the bottom.  Only shows
 @c @end example
 
 
 @c @end example
 
 

-@node  Function Tracing,  , Information Commands, The Debugger
+@node  Function Tracing

 @comment  node-name,  next,  previous,  up
 @section Function Tracing
 @cindex Tracing
 @comment  node-name,  next,  previous,  up
 @section Function Tracing
 @cindex Tracing

@@ -1148,20 +1096,59 @@ their results whenever they are called.  Options allow conditional
 printing of the trace information and conditional breakpoints on
 function entry or exit.
 
 printing of the trace information and conditional breakpoints on
 function entry or exit.
 

-@comment rudi 2004-03-26: The docstring for `trace' is quite comprehensive,
-@comment so refer to it (see also ``OAOO'')
-The docstrings for @code{trace} and @code{untrace} explain SBCL's
-tracing facility.
+@include macro-common-lisp-trace.texinfo

 
 

-@comment FIXME rudi 2004-03-26: revive the documentation of variables
-@comment describing trace behaviour: *trace-encapsulate-default*,
-@comment *max-trace-indentation* and friends.  Some of these are
-@comment mentioned (perhaps under different names) in the cmucl
-@comment manual.
+@include macro-common-lisp-untrace.texinfo
+
+@include var-sb-debug-star-trace-indentation-step-star.texinfo
+
+@include var-sb-debug-star-max-trace-indentation-star.texinfo
+
+@include var-sb-debug-star-trace-encapsulate-default-star.texinfo
+
+@include var-sb-debug-star-trace-values-star.texinfo

 
 @comment FIXME rudi 2004-03-26: encapsulate is (per TODO file as of
 @comment 0.8.9) in a state of flux.  When it's sorted out, revive the
 @comment cmucl documentation.
 
 
 @comment FIXME rudi 2004-03-26: encapsulate is (per TODO file as of
 @comment 0.8.9) in a state of flux.  When it's sorted out, revive the
 @comment cmucl documentation.
 

+@node Single Stepping
+@comment  node-name,  next,  previous,  up
+@section Single Stepping
+@cindex Stepper
+@cindex Single Stepping
+
+SBCL includes an instrumentation based single-stepper for compiled
+code, that can be invoked via the @code{step} macro, or from within
+the debugger. @xref{Debugger Policy Control}, for details on enabling
+stepping for compiled code.
+
+The following debugger commands are used for controlling single stepping.
+
+@deffn {Debugger Command} start
+Selects the @code{continue} restart if one exists and starts single stepping.
+None of the other single stepping commands can be used before stepping has
+been started either by using @code{start} or by using the standard 
+@code{step} macro.
+@end deffn

 
 

+@deffn {Debugger Command} step
+Steps into the current form. Stepping will be resumed when the next
+form that has been compiled with stepper instrumentation is evaluated.
+@end deffn
+
+@deffn {Debugger Command} next
+Steps over the current form. Stepping will be disabled until evaluation of
+the form is complete.
+@end deffn
+
+@deffn {Debugger Command} out
+Steps out of the current frame. Stepping will be disabled until the 
+topmost stack frame that had been stepped into returns.
+@end deffn
+
+@deffn {Debugger Command} stop
+Stops the single stepper and resumes normal execution.
+@end deffn

 
 

+@include macro-common-lisp-step.texinfo