Next: Single Stepping, Previous: Information Commands, Up: Debugger

### 5.9 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.

— Macro: cl:trace &rest specs

> `trace` {Option Global-Value}* {Name {Option Value}*}*

> `trace` is a debugging tool that provides information when specified functions are called. In its simplest form:

>                      (TRACE NAME-1 NAME-2 ...)

> The NAMEs are not evaluated. Each may be a symbol, denoting an individual function, or a string, denoting all functions fbound to symbols whose home package is the package with the given name.

> 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 `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, `trace` causes a printout on `*trace-output*` each time that one of the named functions is entered or returns. (This is the basic, `ansi` Common Lisp behavior of `trace`.) As an `sbcl` extension, the `:report` `sb-ext:profile` option can be used to instead cause information to be silently recorded to be inspected later using the `sb-ext:profile` function.

> The following options are defined:

> `:report` Report-Type
>   If Report-Type is `trace` (the default) then information is reported by printing immediately. If Report-Type is `sb-ext:profile`, information is recorded for later summary by calls to `sb-ext:profile`. If Report-Type is `nil`, then the only effect of the trace is to execute other options (e.g. `print` or BREAK).
> `:condition` Form
> `:condition-after` Form
> `:condition-all` Form
>   If `:condition` is specified, then `trace` does nothing unless Form evaluates to true at the time of the call. `:condition-after` is similar, but suppresses the initial printout, and is tested when the function returns. `:condition-all` tries both before and after. This option is not supported with `:report` `profile`.
> `:break` Form
> `:break-after` Form
> `:break-all` Form
>   If specified, and 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.
> `:print` Form
> `:print-after` Form
> `:print-all` Form
>   In addition to the usual printout, the result of evaluating 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.
> `:wherein` Names
>   If specified, Names is a function name or list of names. `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". This option is not supported with `:report` `profile`.
> `:encapsulate` {:DEFAULT | `t` | NIL}
>   If `t`, the tracing is done via encapsulation (redefining the function name) rather than by modifying the function. `:default` is the default, and 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 `sb-debug:arg` can still be used.
> `:methods` {T | NIL}
>   If `t`, any function argument naming a generic function will have its methods traced in addition to the generic function itself.
> `:function` Function-Form
>   This is a not really an option, but rather another way of specifying what function to trace. The Function-Form is evaluated immediately, and the resulting function is instrumented, i.e. traced or profiled as specified in `report`.

> `:condition`, `:break` and `:print` forms are evaluated in a context which mocks up the lexical environment of the called function, so that `sb-debug:var` and `sb-debug:arg` can be used. The `-after` and `-all` forms are evaluated in the null environment.

— Macro: cl:untrace &rest specs

> Remove tracing from the specified functions. Untraces all functions when called with no arguments.

— Variable: sb-debug:*trace-indentation-step*

> the increase in trace indentation at each call level

— Variable: sb-debug:*max-trace-indentation*

> If the trace indentation exceeds this value, then indentation restarts at 0.

— Variable: sb-debug:*trace-encapsulate-default*

> the default value for the `:encapsulate` option to `trace`

— Variable: sb-debug:*trace-values*

> This is bound to the returned values when evaluating `:break-after` and `:print-after` forms.