GNU Info

(elisp)Function Debugging

---

Next: Explicit Debug Prev: Infinite Loops Up: Debugger

---

Enter node , (file) or (file)node

Entering the Debugger on a Function Call
----------------------------------------

   To investigate a problem that happens in the middle of a program, one
useful technique is to enter the debugger whenever a certain function is
called.  You can do this to the function in which the problem occurs,
and then step through the function, or you can do this to a function
called shortly before the problem, step quickly over the call to that
function, and then step through its caller.

 - Command: debug-on-entry function-name
     This function requests FUNCTION-NAME to invoke the debugger each
     time it is called.  It works by inserting the form `(debug
     'debug)' into the function definition as the first form.

     Any function defined as Lisp code may be set to break on entry,
     regardless of whether it is interpreted code or compiled code.  If
     the function is a command, it will enter the debugger when called
     from Lisp and when called interactively (after the reading of the
     arguments).  You can't debug primitive functions (i.e., those
     written in C) this way.

     When `debug-on-entry' is called interactively, it prompts for
     FUNCTION-NAME in the minibuffer.  If the function is already set
     up to invoke the debugger on entry, `debug-on-entry' does nothing.
     `debug-on-entry' always returns FUNCTION-NAME.

     *Note:* if you redefine a function after using `debug-on-entry' on
     it, the code to enter the debugger is discarded by the
     redefinition.  In effect, redefining the function cancels the
     break-on-entry feature for that function.

          (defun fact (n)
            (if (zerop n) 1
                (* n (fact (1- n)))))
               => fact
          (debug-on-entry 'fact)
               => fact
          (fact 3)
          
          ------ Buffer: *Backtrace* ------
          Entering:
          * fact(3)
            eval-region(4870 4878 t)
            byte-code("...")
            eval-last-sexp(nil)
            (let ...)
            eval-insert-last-sexp(nil)
          * call-interactively(eval-insert-last-sexp)
          ------ Buffer: *Backtrace* ------
          
          (symbol-function 'fact)
               => (lambda (n)
                    (debug (quote debug))
                    (if (zerop n) 1 (* n (fact (1- n)))))

 - Command: cancel-debug-on-entry function-name
     This function undoes the effect of `debug-on-entry' on
     FUNCTION-NAME.  When called interactively, it prompts for
     FUNCTION-NAME in the minibuffer.  If FUNCTION-NAME is `nil' or the
     empty string, it cancels break-on-entry for all functions.

     Calling `cancel-debug-on-entry' does nothing to a function which is
     not currently set up to break on entry.  It always returns
     FUNCTION-NAME.