Name

trace — Follow execution of functions

Synopsis

(trace function-name*)

function-name

{symbol | (symbol [option form]*)}

symbol

A symbol which is bound to a function in the global environment. Not evaluated.

option

One of :BREAK, :BREAK-AFTER, :COND-BEFORE, :COND-AFTER, :COND, :PRINT, :PRINT-AFTER, :STEP

form

A lisp form evaluated in an special environment.

returns

List of symbols with traced functions.

Macro

Causes one or more functions to be traced. Each function-name can be a symbol which is bound to a function, or a list containing that symbol plus additional options. If the function bound to that symbol is called, information about the argumetns and output of this function will be printed. Trace options will modify the amount of information and when it is printed.

Not that if the function is called from another function compiled in the same file, tracing might not be enabled. If this is the case, to enable tracing, recompile the caller with a notinline declaration for the called function.

trace returns a name list of those functions that were traced by the call to trace. If no function-name is given, trace simply returns a name list of all the currently traced functions.

Trace options cause the normal printout to be suppressed, or cause extra information to be printed. Each option is a pair of an option keyword and a value form. If an already traced function is traced again, any new options replace the old options and a warning might be printed. The lisp form accompanying the option is evaluated in an environment where sys::arglist is contains the list of arguments to the function.

The following options are defined:

:cond, :cond-before, :cond-after

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

:step

If form evaluates to true, the stepper is entered.

:break, :break-after

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

:print, :print-after

In addition to the usual printout, the result of evaluating form is printed at the start of the function or at the end of the function, depending on the option. Multiple print options cause multiple values to be output, in the order in which they were introduced.