* Information Commands::
* Function Tracing::
* Single Stepping::
+* Enabling and Disabling the Debugger::
@end menu
@node Debugger Entry
@menu
* Debugger Banner::
-* Debugger Invokation::
+* Debugger Invocation::
@end menu
@node Debugger Banner
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
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
-@subsection Debugger Invokation
+@subsection Debugger Invocation
The debugger is invoked when:
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
-@deffn {Debugger Command} down
+@deffn {Debugger Command} @nopkg{down}
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
-@deffn {Debugger Command} bottom
+@deffn {Debugger Command} @nopkg{bottom}
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.
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 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
-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
@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}.
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
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.
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
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
These commands get you out of the debugger.
-@deffn {Debugger Command} toplevel
+@deffn {Debugger Command} @nopkg{toplevel}
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
-@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
-@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
-@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
+@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
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
-@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
-@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
-@deffn {Debugger Command} error
+@deffn {Debugger Command} @nopkg{error}
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
-@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).
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
+
+@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
projects / sbcl.git / blobdiff