More robust homedir detection on Windows.

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

diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo
index fd299dd..15abf78 100644 (file)
--- a/doc/manual/debugger.texinfo
+++ b/doc/manual/debugger.texinfo
@@ -18,6 +18,7 @@ the debugger, single-stepper and @code{trace}, and the effect of
 * Information Commands::        
 * Function Tracing::            
 * Single Stepping::             
 * Information Commands::        
 * Function Tracing::            
 * Single Stepping::             

+* Enabling and Disabling the Debugger::

 @end menu
 
 @node Debugger Entry
 @end menu
 
 @node Debugger Entry

@@ -26,7 +27,7 @@ the debugger, single-stepper and @code{trace}, and the effect of
 
 @menu
 * Debugger Banner::             
 
 @menu
 * Debugger Banner::             

-* Debugger Invokation::         
+* Debugger Invocation::         

 @end menu
 
 @node Debugger Banner
 @end menu
 
 @node Debugger Banner

@@ -53,7 +54,7 @@ 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
 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).
+@code{sb-ext:*debug-beginner-help-p*} is true (default).

 
 Next comes a listing of the active restart names, along with their
 descriptions -- the ways we can restart execution after this error. In
 
 Next comes a listing of the active restart names, along with their
 descriptions -- the ways we can restart execution after this error. In

@@ -63,9 +64,9 @@ by entering the corresponding number or name.
 The current frame appears right underneath the restarts, immediately
 followed by the debugger prompt.
 
 The current frame appears right underneath the restarts, immediately
 followed by the debugger prompt.
 

-@node Debugger Invokation
+@node Debugger Invocation

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

-@subsection Debugger Invokation
+@subsection Debugger Invocation

 
 The debugger is invoked when:
 
 
 The debugger is invoked when:
 

@@ -168,25 +169,25 @@ These commands move to a new stack frame and print the name of the
 function and the values of its arguments in the style of a Lisp
 function call:
 
 function and the values of its arguments in the style of a Lisp
 function call:
 

-@deffn {Debugger Command} up
+@deffn {Debugger Command} @nopkg{up}

 Move up to the next higher frame.  More recent function calls are
 considered to be higher on the stack.
 @end deffn
 
 Move up to the next higher frame.  More recent function calls are
 considered to be higher on the stack.
 @end deffn
 

-@deffn {Debugger Command} down
+@deffn {Debugger Command} @nopkg{down}

 Move down to the next lower frame.
 @end deffn
 
 Move down to the next lower frame.
 @end deffn
 

-@deffn {Debugger Command} top
+@deffn {Debugger Command} @nopkg{top}

 Move to the highest frame, that is, the frame where the debugger was
 entered.
 @end deffn
 
 Move to the highest frame, that is, the frame where the debugger was
 entered.
 @end deffn
 

-@deffn {Debugger Command} bottom
+@deffn {Debugger Command} @nopkg{bottom}

 Move to the lowest frame.
 @end deffn
 
 Move to the lowest frame.
 @end deffn
 

-@deffn {Debugger Command} frame [@var{n}]
+@deffn {Debugger Command} @nopkg{frame} [@var{n}]

 Move to the frame with the specified number.  Prompts for the number if not
 supplied.  The frame with number 0 is the frame where the debugger
 was entered.
 Move to the frame with the specified number.  Prompts for the number if not
 supplied.  The frame with number 0 is the frame where the debugger
 was entered.

@@ -305,12 +306,6 @@ Sometimes the compiler introduces new functions that are used to
 implement a user function, but are not directly specified in the
 source. This is mostly done for argument type and count checking.
 
 implement a user function, but are not directly specified in the
 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 FIXME: the following bits talked about block-compilation, but
 @c we don't currently support it...
 

@@ -326,13 +321,12 @@ problems that occur during lambda-list processing.
 @c frames during the execution of @code{unwind-protect} cleanup
 @c code.
 
 @c frames during the execution of @code{unwind-protect} cleanup
 @c code.
 

-With recursive functions, an additional @code{:EXTERNAL} frame may
+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
 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.
+is nothing odd with your program. You may also see @code{cleanup}
+frames during the execution of @code{unwind-protect} cleanup code, and
+@code{optional} for variable argument entry points.

 
 @node  Debug Tail Recursion
 @comment  node-name,  next,  previous,  up
 
 @node  Debug Tail Recursion
 @comment  node-name,  next,  previous,  up

@@ -461,7 +455,7 @@ X  =  1
 X#1  =  2
 @end example
 
 X#1  =  2
 @end example
 

-@deffn {Debugger Command} list-locals [@var{prefix}]
+@deffn {Debugger Command} @nopkg{list-locals} [@var{prefix}]

 This command prints the name and value of all variables in the current
 frame whose name has the specified @var{prefix}.  @var{prefix} may be
 a string or a symbol.  If no @var{prefix} is given, then all available
 This command prints the name and value of all variables in the current
 frame whose name has the specified @var{prefix}.  @var{prefix} may be
 a string or a symbol.  If no @var{prefix} is given, then all available

@@ -471,7 +465,7 @@ suffix, where @var{identifier} is the small integer used to make the
 name unique.
 @end deffn
 
 name unique.
 @end deffn
 

-@defun sb-debug:var @var{name} &optional @var{identifier}
+@defun @sbdebug{var} @var{name} &optional @var{identifier}

 This function returns the value of the variable in the current frame
 with the specified @var{name}.  If supplied, @var{identifier}
 determines which value to return when there are ambiguous variables.
 This function returns the value of the variable in the current frame
 with the specified @var{name}.  If supplied, @var{identifier}
 determines which value to return when there are ambiguous variables.

@@ -604,7 +598,7 @@ One of the debugger's capabilities is source level debugging of
 compiled code.  These commands display the source location for the
 current frame:
 
 compiled code.  These commands display the source location for the
 current frame:
 

-@deffn {Debugger Command} source [@var{context}]
+@deffn {Debugger Command} @nopkg{source} [@var{context}]

 This command displays the file that the current frame's function was
 defined from (if it was defined from a file), and then the source form
 responsible for generating the code that the current frame was
 This command displays the file that the current frame's function was
 defined from (if it was defined from a file), and then the source form
 responsible for generating the code that the current frame was

@@ -850,9 +844,9 @@ 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.
 

-If @code{debug} is also at least 2, then  the code is @emph{partially
-steppable}. If @code{debug} is 3, the code is @emph{fully steppable}.
-@xref{Single Stepping}, for details.
+@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
 
 
 @end table
 

@@ -881,34 +875,41 @@ the original function.
 
 These commands get you out of the debugger.
 
 
 These commands get you out of the debugger.
 

-@deffn {Debugger Command} toplevel
+@deffn {Debugger Command} @nopkg{toplevel}

 Throw to top level.
 @end deffn
 
 Throw to top level.
 @end deffn
 

-@deffn {Debugger Command} restart [@var{n}]
+@deffn {Debugger Command} @nopkg{restart} [@var{n}]

 Invokes the @var{n}th restart case as displayed by the @code{error}
 command.  If @var{n} is not specified, the available restart cases are
 reported.
 @end deffn
 
 Invokes the @var{n}th restart case as displayed by the @code{error}
 command.  If @var{n} is not specified, the available restart cases are
 reported.
 @end deffn
 

-@deffn {Debugger Command} continue
+@deffn {Debugger Command} @nopkg{continue}

 Calls @code{continue} on the condition given to @code{debug}.  If there is no
 restart case named @var{continue}, then an error is signaled.
 @end deffn
 
 Calls @code{continue} on the condition given to @code{debug}.  If there is no
 restart case named @var{continue}, then an error is signaled.
 @end deffn
 

-@deffn {Debugger Command} abort
+@deffn {Debugger Command} @nopkg{abort}

 Calls @code{abort} on the condition given to @code{debug}.  This is
 useful for popping debug command loop levels or aborting to top level,
 as the case may be.
 @end deffn
 
 Calls @code{abort} on the condition given to @code{debug}.  This is
 useful for popping debug command loop levels or aborting to top level,
 as the case may be.
 @end deffn
 

-@deffn {Debugger Command} return @var{value}
+@deffn {Debugger Command} @nopkg{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} @nopkg{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
 @comment  node-name,  next,  previous,  up
 
 @node  Information Commands
 @comment  node-name,  next,  previous,  up

@@ -917,37 +918,32 @@ is of the same type as SBCL expects the stack frame to return.
 Most of these commands print information about the current frame or
 function, but a few show general information.
 
 Most of these commands print information about the current frame or
 function, but a few show general information.
 

-@deffn {Debugger Command} help
-@deffnx {Debugger Command} ?
+@deffn {Debugger Command} @nopkg{help}
+@deffnx {Debugger Command} @nopkg{?}

 Displays a synopsis of debugger commands.
 @end deffn
 
 Displays a synopsis of debugger commands.
 @end deffn
 

-@deffn {Debugger Command} describe
+@deffn {Debugger Command} @nopkg{describe}

 Calls @code{describe} on the current function and displays the number of
 local variables.
 @end deffn
 
 Calls @code{describe} on the current function and displays the number of
 local variables.
 @end deffn
 

-@deffn {Debugger Command} print
+@deffn {Debugger Command} @nopkg{print}

 Displays the current function call as it would be displayed by moving to
 this frame.
 @end deffn
 
 Displays the current function call as it would be displayed by moving to
 this frame.
 @end deffn
 

-@deffn {Debugger Command} error
+@deffn {Debugger Command} @nopkg{error}

 Prints the condition given to @code{invoke-debugger} and the active
 proceed cases.
 @end deffn
 
 Prints the condition given to @code{invoke-debugger} and the active
 proceed cases.
 @end deffn
 

-@deffn {Debugger Command} backtrace [@var{n}]
+@deffn {Debugger Command} @nopkg{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*}.
 @end deffn
 
 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
 

-@deffn {Debugger Command} step
-Selects the @code{continue} restart if one exists and starts single stepping.
-@xref{Single Stepping}.
-@end deffn
-

 @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 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).

@@ -1121,23 +1117,51 @@ 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 debugger. @xref{Debugger Policy Control}, for details on enabling
 stepping for compiled code.
 

-Compiled code can be unsteppable, partially steppable, or fully steppable.
+The following debugger commands are used for controlling single stepping.

 
 

-@table @strong
+@deffn {Debugger Command} @nopkg{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

 
 

-@item Unsteppable
-Single stepping is not possible.
+@deffn {Debugger Command} @nopkg{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

 
 

-@item Partially steppable
-Single stepping is possible at sequential function call granularity:
-nested function calls cannot be stepped into, and no intermediate
-values are available.
+@deffn {Debugger Command} @nopkg{next}
+Steps over the current form. Stepping will be disabled until evaluation of
+the form is complete.
+@end deffn

 
 

-@item Fully steppable
-Single stepping is possible at individual function call argument
-granularity, nested calls can be stepped into, and intermediate values
-are available.
+@deffn {Debugger Command} @nopkg{out}
+Steps out of the current frame. Stepping will be disabled until the 
+topmost stack frame that had been stepped into returns.
+@end deffn

 
 

-@end table
+@deffn {Debugger Command} @nopkg{stop}
+Stops the single stepper and resumes normal execution.
+@end deffn

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

+
+@node Enabling and Disabling the Debugger
+@comment  node-name,  next,  previous,  up
+@section Enabling and Disabling the Debugger
+
+@cindex debugger, enabling
+@cindex debugger, disabling
+@cindex disabling debugger
+@cindex ldb, enabling
+@cindex ldb, disabling
+@cindex disabling ldb
+
+In certain contexts (e.g., non-interactive applications), it may be
+desirable to turn off the SBCL debugger (and possibly re-enable it).
+The functions here control the debugger.
+
+@include fun-sb-ext-disable-debugger.texinfo
+
+@include fun-sb-ext-enable-debugger.texinfo