@c Generated by the sb-manual contrib. Do not edit.

@node debugger
@cindex debugger
@chapter Debugger

@menu
* Debugger Entry: debugger entry.
* Debugger Command Loop: debugger command loop.
* Stack Frames: stack frames.
* Variable Access: variable access.
* Source Location Printing: source location printing.
* Debugger Policy Control: debugger policy control.
* Exiting Commands: exiting commands.
* Information Commands: information commands.
* Breakpoint Commands: breakpoint commands.
* Function Tracing: function tracing.
* Single Stepping: single stepping.
* Enabling and Disabling the Debugger: enabling and disabling the debugger.
@end menu

This chapter documents the debugging facilities of SBCL, including
the debugger, single-stepper and @code{trace}, and the effect of @code{(optimize
debug)} declarations.

@node debugger entry
@section Debugger Entry

@menu
* Debugger Banner: debugger banner.
* Debugger Invocation: debugger invocation.
@end menu

@node debugger banner
@subsection Debugger Banner

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.

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.
(CAR 1 3)
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}, causing a
@code{type-error}.

This is followed by the "beginner help line", which appears only
if @code{sb-debug:*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 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
@subsection Debugger Invocation

The debugger is invoked when:

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

@item @code{break} is called, or @code{signal} is called with a condition that matches
  the current @code{*break-on-signals*}.

@item The debugger is explicitly entered with the @code{invoke-debugger}
  function.
@end itemize

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 @code{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.

@anchor{Variable sb-ext *invoke-debugger-hook*}
@vvindex @sortas{invoke-debugger-hook* sb-ext} *invoke-debugger-hook* [sb-ext]
@deffn{Variable} sb-ext:*invoke-debugger-hook*
This is either @code{nil} or a designator for a function of two arguments,
to be run when the debugger is about to be entered. The function is
run with @code{*invoke-debugger-hook*} bound to @code{nil} to minimize
recursive errors, and receives as arguments the condition that
triggered debugger entry and the previous value of
@code{*invoke-debugger-hook*}.

This mechanism is an SBCL extension similar to the standard @code{*debugger-hook*}.
In contrast to @code{*debugger-hook*}, it is observed by @code{invoke-debugger} even when
called by @code{break}.
@end deffn
@node debugger command loop
@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:
@code{help} can be typed as @code{h}, @code{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.

The debugger prompt is @code{<frame>]}, where @code{<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*}.

@anchor{Variable sb-ext *debug-print-variable-alist*}
@vvindex @sortas{debug-print-variable-alist* sb-ext} *debug-print-variable-alist* [sb-ext]
@deffn{Variable} sb-ext:*debug-print-variable-alist*
an association list describing new bindings for special variables
to be used within the debugger. Eg.

 ((@code{*print-length*} . 10) (@code{*print-level*} . 6) (@code{*print-pretty*} . @code{nil}))

The variables in the @code{car} positions 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.

Initially empty, @code{*debug-print-variable-alist*} is typically used to
provide bindings for printer control variables.
@end deffn
@node stack frames
@cindex stack frame
@section Stack Frames

@menu
* Stack Motion: stack motion.
* How Arguments are Printed: how arguments are printed.
* Function Names: function names.
* Debug Tail Recursion: debug tail recursion.
* Unknown Locations and Interrupts: unknown locations and interrupts.
@end menu

A @emph{stack frame} is the run-time representation of a call to a
function; the frame stores the state that a function needs to
remember what it is doing. Frames have:

@itemize
@item @emph{Variables} (see @ref{variable access}), which are the values being
  operated on.

@item @emph{Arguments} to the call (which are really just particularly
  interesting variables).

@item A current source location (@ref{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

@node stack motion
@subsection Stack Motion

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:

@itemize
@item @code{up}: Move up to the next higher frame. More recent function calls
   are considered to be higher on the stack.

@item @code{down}: Move down to the next lower frame.

@item @code{top}: Move to the highest frame, that is, the frame where the
  debugger was entered.

@item @code{bottom}: Move to the lowest frame.

@item @code{frame [<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.
@end itemize

@node how arguments are printed
@subsection How Arguments are Printed

A frame is printed to look like a function call, but with the actual
argument values in the argument positions.  So the frame for this call
in the source:

@example
(myfun (+ 3 4) 'a)
@end example

would look like this:

@example
(MYFUN 7 A)
@end example

All keyword and optional arguments are displayed with their actual
values; if the corresponding argument was not supplied, the value will
be the default.  So this call:

@example
(subseq "foo" 1)
@end example

would look like this:

@example
(SUBSEQ "foo" 1 3)
@end example

And this call:

@example
(string-upcase "test case")
@end example

would look like this:

@example
(STRING-UPCASE "test case" :START 0 :END NIL)
@end example

The arguments to a function call are displayed by accessing the
argument variables. Although those variables are initialized to the
actual argument values, they can be set inside the function; in this
case the new value will be displayed.

@code{&rest} arguments are handled somewhat differently. The value of the
rest argument variable is displayed as the spread-out arguments to
the call, so:

@example
(format t "~A is a ~A." "This" 'test)
@end example

would look like this:

@example
(FORMAT T "~A is a ~A." "This" 'TEST)
@end example

Rest arguments cause an exception to the normal display of keyword
arguments in functions that have both @code{&rest} and @code{&key} arguments. In
this case, the keyword argument variables are not displayed at all;
the rest arg is displayed instead. So for these functions, only the
keywords actually supplied will be shown, and the values displayed
will be the argument values, not values of the
(possibly modified) variables.

If the variable for an argument is never referenced by the function,
it will be deleted. The variable value is then unavailable, so the
debugger prints @code{#<unused-arg>} instead of the value. Similarly, if
for any of a number of reasons the value of the variable is
unavailable or not known to be available (@ref{variable access}), then
@code{#<unavailable-arg>} will be printed instead of the argument value.

Note that inline expansion and open-coding affect what frames are
present in the debugger, see @ref{debugger policy control}.

@node function names
@subsection Function Names

@menu
* Entry Point Details: entry point details.
@end menu

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{(lambda <lambda-list>)}.

@node entry point details
@cindex external entry point
@cindex entry point, external
@cindex block compilation, debugger implications
@cindex external, stack frame kind
@cindex optional, stack frame kind
@cindex cleanup, stack frame kind
@subsubsection Entry Point Details

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.

With recursive or block compiled functions, an additional @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 works: there 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
@subsection Debug Tail Recursion

@cindex tail recursion
@cindex recursion, tail
The compiler is @emph{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 ...)
(FOO ...)
@end example

Because of tail recursion, it is not necessarily the case that @code{foo}
directly called @code{bar}. It may be that @code{foo} called some other
function @code{foo2}, which then called @code{bar} tail-recursively, as in
this example:

@example
(defun foo ()
  ...
  (foo2 ...)
  ...)

(defun foo2 (...)
  ...
  (bar ...))

(defun bar (...)
  ...)
@end example

Usually the elimination of tail-recursive frames makes debugging
more 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.
See @ref{source location printing}.

The elimination of tail-recursive frames can be prevented by
disabling tail-recursion optimization, which happens when the @code{debug}
optimization quality is greater than 2. See
@ref{debugger policy control}.

@node unknown locations and interrupts
@cindex unknown code location
@cindex code location unknown
@subsection Unknown Locations and Interrupts

The debugger operates using special debugging information attached to
the compiled code. This debug information tells the debugger what it
needs to know about the locations in the code where the debugger can
be invoked. If the debugger somehow encounters a location not
described in the debug information, then it is said to be @emph{unknown}.
If the code location for a frame is unknown, then some variables may
be inaccessible, and the source location cannot be precisely
displayed.

There are three reasons why a code location could be unknown:

@cindex interrupt
@cindex run-time error
@cindex error, run-time
@itemize
@item There is inadequate debug information due to the value of the
  @code{debug} optimization quality. See @ref{debugger policy control}.

@item The debugger was entered because of an interrupt such as @code{C-c}.

@item A hardware error  such as a bus error occurred in
  code that was compiled unsafely due to the value of the @code{safety}
  optimization quality.
@end itemize

In the last two cases, the values of argument variables are
accessible, but may be incorrect. For more details on when variable
values are accessible, see @ref{variable value availability}.

It is possible for an interrupt to happen when a function call or
return is in progress. The debugger may then flame out with some
obscure error or insist that the bottom of the stack has been
reached, when the real problem is that the current stack frame can't
be located. If this happens, return from the interrupt and try
again.

@node variable access
@cindex debug variables
@cindex variable, debugger access
@section Variable Access

@menu
* Variable Value Availability: variable value availability.
* Note On Lexical Variable Access: note on lexical variable access.
@end menu

There are two ways to access the current frame's local variables in
the debugger: @code{list-locals} and @code{sb-debug:var}.

The debugger doesn't really understand lexical scoping; it has just
one namespace for all the variables in the current stack frame. If a
symbol is the name of multiple variables in the same function, then
the reference appears ambiguous, even though lexical scoping
specifies which value is visible at any given source location. If
the scopes of the two variables are not nested, then the debugger
can resolve the ambiguity by observing that only one variable is
accessible.

When there are ambiguous variables, the evaluator assigns each one a
small integer identifier. The @code{sb-debug:var} function uses this
identifier to distinguish between ambiguous variables. The
@code{list-locals} command prints the identifier. In the following
example, there are two variables named @code{x}. The first one has
identifier 0 (which is not printed), the second one has identifier
1.

@example
X  =  1
X#1  =  2
@end example

@itemize
@item @code{list-locals [<prefix>]}: This command prints the name and value
  of all variables in the current frame whose name has the specified
  @code{<prefix>}, which may be a string or a symbol. If no @code{<prefix>} is
  given, then all available variables are printed. If a variable has
  a potentially ambiguous name, then the name is printed with a
  @code{#<identifier>} suffix, where @code{<identifier>} is the small integer
  used to make the name unique.
@end itemize

@anchor{Function sb-debug var}
@ffindex @sortas{var sb-debug} var [sb-debug]
@deffn{Function} sb-debug:var name &optional id
Return a variable's value if possible. @code{name} is a simple-string or symbol.
If it is a simple-string, it is an initial substring of the
variable's name. If name is a symbol, it has the same name and
package as the variable whose value this function returns. If the
symbol is uninterned, then the variable has the same name as the
symbol, but it has no package.

If name is the initial substring of variables with different names,
then this returns no values after displaying the ambiguous names.
If name determines multiple variables with the same name, then you
must use the optional @code{id} argument to specify which one you want. If
you left @code{id} unspecified, then this returns no values after
displaying the distinguishing id values.

The result of this function is limited to the availability of
variable information. This is @code{setf}able.
@end deffn
@node variable value availability
@cindex variable, value availabilty in debugger
@cindex debug variable, value availabilty
@subsection Variable Value Availability

The value of a variable may be unavailable to the debugger in portions
of the program where Lisp says that the variable is defined. If a
variable value is not available, the debugger will not let you read
or write that variable. With one exception, the debugger will never
display an incorrect value for a variable. Rather than displaying
incorrect values, the debugger tells you the value is unavailable.

The one exception is this: if you interrupt (e.g. with @code{C-c}) or if
there is an unexpected hardware error such as a bus error (which
should only happen in unsafe code), then the values displayed for
arguments to the interrupted frame might be incorrect. This
exception applies only to the interrupted frame: any frame farther
down the stack will be fine.

@quotation
@emph{Note}: Since the location of an interrupt or hardware error will
always be an unknown location, non-argument variable values will
never be available in the interrupted frame. See
@ref{unknown locations and interrupts}.)
@end quotation

The value of a variable may be unavailable for these reasons:

@cindex debug, optimization quality
@cindex optimization quality debug
@itemize
@item The value of the debug optimization quality may have omitted
  debug information needed to determine whether the variable is
  available. Unless a variable is an argument, its value will only
  be available when @code{debug} is at least 2.

@item The compiler did lifetime analysis and determined that the value
  was no longer needed, even though its scope had not been exited.
  Lifetime analysis is inhibited when the @code{debug} optimization
  quality is 3.

@item The variable's name is an uninterned symbol (gensym). To save
  space, the compiler only dumps debug information about uninterned
  variables when the @code{debug} optimization quality is 3.

@item The frame's location is unknown (see
  @ref{unknown locations and interrupts}) because the debugger was
  entered due to an interrupt or unexpected hardware error. Under
  these conditions the values of arguments will be available, but
  might be incorrect. This is the exception mentioned above.

@item The variable (or the code referencing it) was optimized out of
  existence. Variables with no reads are always optimized away. The
  degree to which the compiler deletes variables will depend on the
  value of the @code{compilation-speed} optimization quality, but most
  source-level optimizations are done under all compilation
  policies.

@item The variable is never set and its definition looks like

@example
(LET ((var1 var2))
   ...)
@end example

In this case, @code{var1} is substituted with @code{var2}.

@item The variable is never set and is referenced exactly once. In this
  case, the reference is substituted with the variable initial
  value.
@end itemize

Since it is especially useful to be able to get the arguments to a
function, argument variables are treated specially when the @code{speed}
optimization quality is less than 3 and the @code{debug} quality is at
least 1. With this compilation policy, the values of argument
variables are almost always available everywhere in the function,
even at unknown locations. For non-argument variables, @code{debug} must be
at least 2 for values to be available, and even then, values are
only available at known locations.

@node note on lexical variable access
@subsection Note On Lexical Variable Access

When the debugger command loop establishes variable bindings for
available variables, these variable bindings have lexical scope and
dynamic extent. You can close over them, but such closures can't be
used as upward function arguments.

@quotation
@emph{Note}: The variable bindings are actually created using the Lisp
@code{symbol-macrolet} special form.
@end quotation

You can also set local variables using @code{setq}, but if the variable was
closed over in the original source and never set, then setting the
variable in the debugger may not change the value in all the
functions the variable is defined in. Another risk of setting
variables is that you may assign a value of a type that the compiler
proved the variable could never take on. This may result in bad
things happening.

@node source location printing
@cindex source location in debugger
@section Source Location Printing

@menu
* How the Source is Found: how the source is found.
* Source Location Availability: source location availability.
@end menu

One of the debugger's capabilities is source level debugging of
compiled code.  These commands display the source location for the
current frame:

@itemize
@item @code{source [<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 executing. If @code{<context>} is
  specified, then it is an integer specifying the number of
  enclosing levels of list structure to print.
@end itemize

The source form for a location in the code is the innermost list
present in the original source that encloses the form responsible
for generating that code. If the actual source form is not a list,
then some enclosing list will be printed. For example, if the source
form was a reference to the variable @code{*some-random-special*}, then
the innermost enclosing evaluated form will be printed. Here are
some possible enclosing forms:

@example
(let ((a *some-random-special*))
  ...)

(+ *some-random-special* ...)
@end example

If the code at a location was generated from the expansion of a
macro or a source-level compiler optimization, then the form in the
original source that expanded into that code will be printed.
Suppose the file @code{/usr/me/mystuff.lisp} looked like this:

@example
(defmacro mymac ()
  '(myfun))

(defun foo ()
  (mymac)
  ...)
@end example

If @code{foo} has called @code{myfun}, and is waiting for it to return, then
the @code{source} command would print:

@example
; File: /usr/me/mystuff.lisp

(MYMAC)
@end example

Note that the macro use was printed, not the actual function call form,
@code{(myfun)}.

If enclosing source is printed by giving an argument to @code{source} or
@code{vsource}, then the actual source form is marked by wrapping it in a
list whose first element is @code{#:***here***}. In the previous example,
@code{source 1} would print:

@example
; File: /usr/me/mystuff.lisp

(DEFUN FOO ()
  (#:***HERE***
   (MYMAC))
  ...)
@end example

@node how the source is found
@subsection How the Source is Found

If the code was defined from Lisp by @code{compile} or @code{eval}, then the source
can always be reliably located. If the code was defined from a FASL
file created by @code{compile-file}, then the debugger gets the source
forms it prints by reading them from the original source file. This
is a potential problem, since the source file might have moved or
changed since the time it was compiled.

The source file is opened using the @code{truename} of the source file
pathname originally given to the compiler. This is an absolute
pathname with all logical names and symbolic links expanded. If the
file can't be located using this name, then the debugger gives up
and signals an error.

If the source file can be found, but has been modified since the time it was
compiled, the debugger prints this warning:

@example
; File has been modified since compilation:
;   <filename>
; Using form offset instead of character position.
@end example

where @code{<filename>} is the name of the source file. It then proceeds
using a robust but not foolproof heuristic for locating the source.
This heuristic works if:

@itemize
@item No top-level forms before the top-level form containing the source
  have been added or deleted, and

@item the top-level form containing the source has not been modified
  much. (More precisely, none of the list forms beginning before the
  source form have been added or deleted.)
@end itemize

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 source location commands are noticeably slowed.

Source location printing can also be confused if (after the source
was compiled) a read-macro you used in the code was redefined to
expand into something different, or if a read-macro ever returns the
same @code{eq} list twice. If you don't define read macros and don't use
@code{##} in perverted ways, you don't need to worry about this.

@node source location availability
@subsection Source Location Availability

@cindex debug, optimization quality
@cindex optimization quality debug
Source location information is only available when the debug
optimization quality is at least 2. If source location information
is unavailable, the source commands will give an error message.

If source location information is available, but the source location
is unknown because of an interrupt or unexpected hardware error
(see @ref{unknown locations and interrupts}), then the command will
print

@example
Unknown location: using block start.
@end example

@cindex basic block
@cindex block, basic
and then proceed to print the source location for the start of the
@emph{basic block} enclosing the code location. It's a bit complicated to
explain exactly what a basic block is, but here are some properties
of the block start location:

@cindex block, start location
@itemize
@item The block start location may be the same as the true location.

@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}, @code{cond}, @code{or}) will
  intervene between the block start and the true location (but note
  that some conditionals present in the original source could be
  optimized away.) Function calls @emph{do not} end basic blocks.

@item The head of a loop will be the start of a block.

@item The programming language concept of block structure and the Lisp
  @code{block} special form are totally unrelated to the compiler's basic
  block.
@end itemize

In other words, the true location lies between the printed location
and the next conditional (but watch out because the compiler may
have changed the program on you.)

@node debugger policy control
@cindex debugger policy
@cindex policy, debugger
@section Debugger Policy Control

@cindex debug, optimization quality
@cindex optimization quality debug
The compilation policy specified by @code{optimize} declarations
affects the behavior seen in the debugger. The debug quality
directly affects the debugger by controlling the amount of debugger
information dumped. Other optimization qualities have indirect but
observable effects due to changes in the way compilation is done.

Unlike the other optimization qualities (which are compared in
relative value to evaluate tradeoffs), the @code{debug} optimization
quality is directly translated to a level of debug information. This
absolute interpretation allows the user to count on a particular
amount of debug information being available even when the values of
the other qualities are changed during compilation. These are the
levels of debug information that correspond to the values of the
@code{debug} quality:

@itemize
@item @code{0}: Only the function name and enough information to allow the
  stack to be parsed.

@item @code{> 0}: Any level greater than 0 gives level 0 plus all argument
  variables. Values will only be accessible if the argument variable
  is never set and @code{speed} is not 3. SBCL allows any real value for
  optimization qualities. It may be useful to specify 0.5 to get
  backtrace argument display without argument documentation.

@item @code{1}: Level 1 provides argument documentation (printed argument
  lists) and derived argument/result type information. This makes
  @code{describe} more informative, and allows the compiler to do
  compile-time argument count and type checking for any calls
  compiled at run-time. This is the default.

@item @code{2}: Level 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 3 or the argument is
  set).

@item @code{> 2}: Any level greater than 2 gives level 2 and in addition
  disables tail-call optimization, so that the backtrace will
  contain frames for all invoked functions, even those in tail
  positions.

@item @code{3}: Level 2 plus all uninterned variables. In addition, lifetime
  analysis is disabled (even when @code{speed} is 3), ensuring that all
  variable values are available at any known location within the
  scope of the binding. This has a speed penalty in addition to the
  obvious space penalty.
@end itemize

Inlining of local functions is inhibited so that they may be @code{trace}d.

@itemize
@item @code{> (max speed space)}: If @code{debug} is greater than both @code{speed} and
  @code{space}, the command @code{return} can be used to continue execution by
  returning a value from the current stack frame.

@item @code{> (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 (see @ref{single stepping}).
@end itemize

As you can see, if the @code{speed} quality is 3, debugger performance is
degraded. This effect comes from the elimination of argument
variable special-casing (see @ref{variable value availability}). Some
degree of speed/debuggability tradeoff is unavoidable, but the
effect is not too drastic when @code{debug} is at least 2.

@cindex inline, semi
@cindex semi-inline
In addition to @code{inline} and @code{notinline} declarations, the relative
values of the @code{speed} and @code{space} qualities also change whether
functions are inline expanded. If a function is inline expanded,
then there will be no frame to represent the call, and the arguments
will be treated like any other local variable. Functions may also be
@emph{semi inline}, in which case there is a frame to represent the
call, but the call is to an optimized local version of the function,
not to the original function.

@node exiting commands
@section Exiting Commands

These commands get you out of the debugger.

@itemize
@item @code{toplevel}: Throw to top level.

@item @code{restart [<n>]}: Invoke the @code{<n>}th restart case as displayed by
  the @code{error} command. If @code{<n>} is not specified, the available
  restart cases are reported.

@item @code{continue}: Call @code{continue} on the condition given to @code{debug}. If
  there is no restart case named @code{continue}, then an error is
  signaled.

@item @code{abort}: Call @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.

@item @code{return <value>}: Return @code{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.

@item @code{restart-frame}: Restart 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 a
  global function. If the function is redefined in the debugger
  before the frame is restarted, the new function will be used.
@end itemize

@node information commands
@section Information Commands

Most of these commands print information about the current frame or
function, but a few show general information.

@itemize
@item @code{help} or @code{?}: Display a synopsis of debugger commands.

@item @code{describe}: Call @code{describe} on the current function and displays the
  number of local variables.

@item @code{print}: Display the current function call as it would be
  displayed by moving to this frame.

@item @code{error}: Print the condition given to @code{invoke-debugger} and the
  active proceed cases.

@item @code{backtrace [<n>]}: Display all the frames from the current to the
  bottom. Only shows @code{<n>} frames if specified. The printing is
  controlled by @code{sb-debug:*debug-print-variable-alist*}.
@end itemize

@node breakpoint commands
@cindex breakpoint
@section Breakpoint Commands

@menu
* Breakpoint Example: breakpoint example.
@end menu

SBCL supports setting of breakpoints inside compiled functions and
stepping of compiled code. Breakpoints can only be set at known
locations (see @ref{unknown locations and interrupts}), so these commands
are largely useless unless the @code{debug} optimize quality is at least
2 (see @ref{debugger policy control}). These commands manipulate
breakpoints:

@itemize
@item @code{breakpoint <location> [<option> <value>]*}: Set a breakpoint in
  some function. @code{<location>} may be an integer code location
  number (as displayed by @code{list-locations}) or a keyword. The
  keyword can be used to indicate setting a breakpoint at the
  function start (@code{:start}, @code{:s}) or function end (@code{:end}, @code{:e}). The
  @code{breakpoint} command has @code{:condition}, @code{:break}, @code{:print} and @code{:function}
  options which work similarly to the @code{trace} options.

@item @code{list-locations [<function>]} or @code{ll [<function>]}: List all the
  code locations in the current frame's function, or in @code{<function>}
  if it is supplied. The display format is the code location number,
  a colon and then the source form for that location:

@example
3: (1- N)
@end example

If consecutive locations have the same source, then a numeric
range like @code{3-5:} will be printed. For example, a default
function call has a known location both immediately before and
after the call, which would result in two code locations with
the same source. The listed function becomes the new default
function for breakpoint setting (via the @code{breakpoint}) command.

@item @code{list-breakpoints} or @code{lb}: List all currently active breakpoints
  with their breakpoint number.

@item @code{delete-breakpoint [<number>]} or @code{db [<number>]}: Delete a
  breakpoint specified by its breakpoint number. If no number is
  specified, delete all breakpoints.

@item @code{step*}: Step to the next possible breakpoint location in the
  current function. This always steps over function calls, instead
  of stepping into them.
@end itemize

@node breakpoint example
@subsection Breakpoint Example

Consider this definition of the factorial function:

@example
(defun ! (n)
  (if (zerop n)
      1
      (* n (! (1- n)))))
@end example

This debugger session demonstrates the use of breakpoints:

@example
* (break)  ; invoke debugger

debugger invoked on a SIMPLE-CONDITION in thread 11184: break

restarts (invokable by number or by possibly-abbreviated name):
  0: [CONTINUE] Return from BREAK.
  1: [ABORT   ] Reduce debugger level (leaving debugger, returning to toplevel).
  2: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
("varargs entry for top level local call BREAK" "break")
0] ll #'!

0-1: (SB-INT:NAMED-LAMBDA ! (N) (BLOCK ! (IF (ZEROP N) 1 (* N (! #)))))
2: (BLOCK ! (IF (ZEROP N) 1 (* N (! (1- N)))))
3: (ZEROP N)
4: (* N (! (1- N)))
5: (1- N)
6: (! (1- N))
7-8: (* N (! (1- N)))
9-10: (IF (ZEROP N) 1 (* N (! (1- N))))
0] br 4

(* N (! (1- N)))
1: 4 in !
added
0] toplevel

> (! 10) ; Call the function

*Breakpoint hit*

Restarts:
  0: [CONTINUE] Return from BREAK.
  1: [ABORT   ] Return to Top-Level.

Debug  (type H for help)

(! 10) ; We are now in first call (arg 10) before the multiply
Source: (* N (! (1- N)))
3] step*

*Step*

(! 10) ; We have finished evaluation of (1- n)
Source: (1- N)
3] step*

*Breakpoint hit*

Restarts:
  0: [CONTINUE] Return from BREAK.
  1: [ABORT   ] Return to Top-Level.

Debug  (type H for help)

(! 9) ; We hit the breakpoint in the recursive call
Source: (* N (! (1- N)))
3]
@end example

@quotation
@emph{Note}: The @code{step*} command differs from the single stepping
commands in that it also functions in compiled code which has not
been compiled with stepping instrumentation. It simply steps to
the next compiled code location. In the future, this form of
stepping may be improved enough to subsume the instrumentation
based stepping commands, which have much higher overhead.
@end quotation

@node function tracing
@cindex tracing
@cindex function, tracing
@section Function Tracing

The tracer causes selected functions to print their arguments and
their results whenever they are called.  Options allow conditional
printing of the trace information and conditional breakpoints on
function entry or exit.

In SBCL, tracing can be done either by temporarily redefining the
function name (encapsulation), or using breakpoints. When
breakpoints are used, the function object itself is destructively
modified to cause the tracing action. The advantage of using
breakpoints is that tracing works even when the function is
anonymously called via @code{funcall}, that function object identity is
preserved, and that anonymous and local functions can also be
traced.

@anchor{Macro common-lisp trace}
@ffindex @sortas{trace common-lisp} trace [common-lisp]
@deffn{Macro} trace &rest specs
@code{trace} @code{@{Option Global-Value@}* @{Name @{Option Value@}*@}*}

@code{trace} is a debugging tool that provides information when specified
functions are called. In its simplest form:

@example
(TRACE NAME-1 NAME-2 ...)
@end example

The @code{name}s are not evaluated. Each may be one of the following:

@itemize
@item @code{symbol}, denoting a function or macro.
@item @code{fname}, a valid function name, denoting a function.
@item @code{(method fname qualifiers* (specializers*))} denoting a method.
@item @code{(compiler-macro symbol)} denoting a compiler macro.
@item @code{(labels fname :in outer-name)} or @code{(flet fname :in outer-name)}
  denoting a local function where @code{outer-name} may be any of the
  previous names for functions, macros, methods or compiler macros.
  Tracing local functions may require @code{debug} policy 3 to inhibit
  inlining.
@item @code{string} denoting all functions fbound to symbols whose home package
  is the package with the given name.
@end itemize

Options allow modification of the default behavior. Each option is a
pair of an option keyword and a value form. Global options are
specified before the first name, and affect all functions traced by a
given use of @code{trace}. Options may also be interspersed with function
names, in which case they act as local options, only affecting tracing
of the immediately preceding function name. Local options override
global options.

By default, @code{trace} causes a printout on @code{*trace-output*} each time that
one of the named functions is entered or returns. (This is the basic,
ANSI Common Lisp behavior of @code{trace}.)

The following options are defined:

@itemize
@item @code{:report} @code{<report-type>}

If @code{report-type} is @code{trace} (the default) then information is
reported by printing immediately. If @code{report-type} is @code{nil}, then
the only effect of the trace is to execute other options (e.g.
@code{print} or @code{break}). Otherwise, @code{report-type} is treated as a function
designator and, for each trace event, funcalled with 5 arguments:
trace depth (a non-negative integer), a function name or a
function object, a keyword (@code{:enter}, @code{:exit} or @code{:non-local-exit}), a
stack frame, and a list of values (arguments or return values).

@item @code{:condition} @code{<form>}
@item @code{:condition-after} @code{<form>}
@item @code{:condition-all} @code{<form>}

If @code{:condition} is specified, then @code{trace} does nothing unless @code{form}
evaluates to true at the time of the call. @code{:condition-after} is
similar, but suppresses the initial printout, and is tested when
the function returns. @code{:condition-all} tries both before and after.

@item @code{:break} @code{<form>}
@item @code{:break-after} @code{<form>}
@item @code{:break-all} @code{<form>}

If specified, and @code{form} evaluates to true, then the debugger is
invoked at the start of the function, at the end of the function,
or both, according to the respective option.

@item @code{:print} @code{<form>}
@item @code{:print-after} @code{<form>}
@item @code{:print-all} @code{<form>}

In addition to the usual printout, the result of evaluating @code{form}
is printed at the start of the function, at the end of the
function, or both, according to the respective option. Multiple
print options cause multiple values to be printed.

@item @code{:wherein} @code{<names>}

If specified, @code{names} is a function name or list of names. @code{trace}
does nothing unless a call to one of those functions encloses the
call to this function (i.e. it would appear in a backtrace.)
Anonymous functions have string names like "DEFUN FOO".

@item @code{:encapsulate} @{@code{:default} | @code{t} | @code{nil}@}

If @code{t}, the default, tracing is done via encapsulation (redefining
the function name) rather than by modifying the function. @code{:default}
is not the default but means to use encapsulation for interpreted
functions and funcallable instances, breakpoints otherwise. When
encapsulation is used, forms are *not* evaluated in the function's
lexical environment, but @code{sb-debug:arg} can still be used.

@item @code{:methods} @{@code{t} | @code{nil}@}

If @code{t}, any function argument naming a generic function will have
its methods traced in addition to the generic function itself.

@item @code{:function} @code{<function-form>}

This is a not really an option but rather another way of
specifying what function to trace. The @code{function-form} is
evaluated immediately, and the resulting function is traced.
@end itemize

@code{:condition}, @code{:break} and @code{:print} forms are evaluated in a context which
mocks up the lexical environment of the called function, so that
@code{sb-debug:var} and @code{sb-debug:arg} can be used.
The @code{*-after} and @code{*-all} forms can use also use @code{sb-debug:arg}. In forms
which are evaluated after the function call, @code{(sb-debug:arg n)} returns
the @code{n}th value returned by the function.
@end deffn
In the case of functions where the known return convention is used
to optimize, encapsulation may be necessary in order to make tracing
work at all. The symptom of this occurring is an error stating

@example
Error in function FOO: :FUNCTION-END breakpoints are
currently unsupported for the known return convention.
@end example

in such cases we recommend using @code{(TRACE FOO :ENCAPSULATE t)}.

@anchor{Macro common-lisp untrace}
@ffindex @sortas{untrace common-lisp} untrace [common-lisp]
@deffn{Macro} untrace &rest specs
Remove tracing from the specified functions. Untraces all
functions when called with no arguments.
@end deffn
@anchor{Variable sb-debug *trace-indentation-step*}
@vvindex @sortas{trace-indentation-step* sb-debug} *trace-indentation-step* [sb-debug]
@deffn{Variable} sb-debug:*trace-indentation-step*
The increase in trace indentation at each call level.
@end deffn
@anchor{Variable sb-debug *max-trace-indentation*}
@vvindex @sortas{max-trace-indentation* sb-debug} *max-trace-indentation* [sb-debug]
@deffn{Variable} sb-debug:*max-trace-indentation*
If the trace indentation exceeds this value, then indentation restarts
at 0.
@end deffn
@anchor{Variable sb-debug *trace-encapsulate-default*}
@vvindex @sortas{trace-encapsulate-default* sb-debug} *trace-encapsulate-default* [sb-debug]
@deffn{Variable} sb-debug:*trace-encapsulate-default*
The default value for the @code{:encapsulate} option to @code{trace}.
@end deffn
@anchor{Variable sb-debug *trace-report-default*}
@vvindex @sortas{trace-report-default* sb-debug} *trace-report-default* [sb-debug]
@deffn{Variable} sb-debug:*trace-report-default*
The default value for the @code{:report} option to @code{trace}.
@end deffn
@node single stepping
@cindex stepper
@cindex single-stepping
@section 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. See @ref{debugger policy control}, for details on enabling
stepping for compiled code.

The following debugger commands are used for controlling single stepping.

@itemize
@item @code{start}: Select 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.

@item @code{step}: Step into the current form. Stepping will be resumed when
  the next form that has been compiled with stepper instrumentation
  is evaluated.

@item @code{next}: Step over the current form. Stepping will be disabled
  until evaluation of the form is complete.

@item @code{out}: Step out of the current frame. Stepping will be disabled
  until the topmost stack frame that had been stepped into returns.

@item @code{stop}: Stop the single stepper and resumes normal execution.
@end itemize

@anchor{Macro common-lisp step}
@ffindex @sortas{step common-lisp} step [common-lisp]
@deffn{Macro} step form
The form is evaluated with single stepping enabled. Function calls
outside the lexical scope of the form can be stepped into only if the
functions in question have been compiled with sufficient @code{debug} policy
to be at least partially steppable.
@end deffn
@node enabling and disabling the debugger
@cindex debugger, enabling
@cindex debugger, disabling
@cindex enabling debugger
@cindex disabling debugger
@cindex enabling LDB
@cindex LDB, enabling
@cindex disabling LDB
@cindex LDB, disabling
@section Enabling and Disabling the Debugger

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.

@anchor{Function sb-ext disable-debugger}
@ffindex @sortas{disable-debugger sb-ext} disable-debugger [sb-ext]
@deffn{Function} sb-ext:disable-debugger
When invoked, this function will turn off both the SBCL debugger
and @code{ldb} (the low-level debugger).  See also @code{enable-debugger}.
@end deffn
@anchor{Function sb-ext enable-debugger}
@ffindex @sortas{enable-debugger sb-ext} enable-debugger [sb-ext]
@deffn{Function} sb-ext:enable-debugger
Restore the debugger if it has been turned off by @code{disable-debugger}.
@end deffn
