1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
|
<h4 class="subsection">Internals of the Debugger</h4> <p>This section describes functions and variables used internally by the debugger. </p> <dl> <dt id="debugger">Variable: <strong>debugger</strong>
</dt> <dd>
<p>The value of this variable is the function to call to invoke the debugger. Its value must be a function of any number of arguments, or, more typically, the name of a function. This function should invoke some kind of debugger. The default value of the variable is <code>debug</code>. </p> <p>The first argument that Lisp hands to the function indicates why it was called. The convention for arguments is detailed in the description of <code>debug</code> (see <a href="invoking-the-debugger">Invoking the Debugger</a>). </p>
</dd>
</dl> <dl> <dt id="backtrace">Function: <strong>backtrace</strong>
</dt> <dd>
<p>This function prints a trace of Lisp function calls currently active. The trace is identical to the one that <code>debug</code> would show in the <samp>*Backtrace*</samp> buffer. The return value is always nil. </p> <p>In the following example, a Lisp expression calls <code>backtrace</code> explicitly. This prints the backtrace to the stream <code>standard-output</code>, which, in this case, is the buffer ‘<samp>backtrace-output</samp>’. </p> <p>Each line of the backtrace represents one function call. The line shows the function followed by a list of the values of the function’s arguments if they are all known; if they are still being computed, the line consists of a list containing the function and its unevaluated arguments. Long lists or deeply nested structures may be elided. </p> <div class="example"> <pre class="example">(with-output-to-temp-buffer "backtrace-output"
(let ((var 1))
(save-excursion
(setq var (eval '(progn
(1+ var)
(list 'testing (backtrace))))))))
⇒ (testing nil)
</pre>
<pre class="example">----------- Buffer: backtrace-output ------------
backtrace()
(list 'testing (backtrace))
</pre>
<pre class="example"> (progn ...)
eval((progn (1+ var) (list 'testing (backtrace))))
(setq ...)
(save-excursion ...)
(let ...)
(with-output-to-temp-buffer ...)
eval((with-output-to-temp-buffer ...))
eval-last-sexp-1(nil)
</pre>
<pre class="example"> eval-last-sexp(nil)
call-interactively(eval-last-sexp)
----------- Buffer: backtrace-output ------------
</pre>
</div> </dd>
</dl> <dl> <dt id="debugger-stack-frame-as-list">User Option: <strong>debugger-stack-frame-as-list</strong>
</dt> <dd>
<p>If this variable is non-<code>nil</code>, every stack frame of the backtrace is displayed as a list. This aims at improving the backtrace readability at the cost of special forms no longer being visually different from regular function calls. </p> <p>With <code>debugger-stack-frame-as-list</code> non-<code>nil</code>, the above example would look as follows: </p> <div class="example"> <pre class="example">----------- Buffer: backtrace-output ------------
(backtrace)
(list 'testing (backtrace))
</pre>
<pre class="example"> (progn ...)
(eval (progn (1+ var) (list 'testing (backtrace))))
(setq ...)
(save-excursion ...)
(let ...)
(with-output-to-temp-buffer ...)
(eval (with-output-to-temp-buffer ...))
(eval-last-sexp-1 nil)
</pre>
<pre class="example"> (eval-last-sexp nil)
(call-interactively eval-last-sexp)
----------- Buffer: backtrace-output ------------
</pre>
</div> </dd>
</dl> <dl> <dt id="debug-on-next-call">Variable: <strong>debug-on-next-call</strong>
</dt> <dd>
<p>If this variable is non-<code>nil</code>, it says to call the debugger before the next <code>eval</code>, <code>apply</code> or <code>funcall</code>. Entering the debugger sets <code>debug-on-next-call</code> to <code>nil</code>. </p> <p>The <kbd>d</kbd> command in the debugger works by setting this variable. </p>
</dd>
</dl> <dl> <dt id="backtrace-debug">Function: <strong>backtrace-debug</strong> <em>level flag</em>
</dt> <dd>
<p>This function sets the debug-on-exit flag of the stack frame <var>level</var> levels down the stack, giving it the value <var>flag</var>. If <var>flag</var> is non-<code>nil</code>, this will cause the debugger to be entered when that frame later exits. Even a nonlocal exit through that frame will enter the debugger. </p> <p>This function is used only by the debugger. </p>
</dd>
</dl> <dl> <dt id="command-debug-status">Variable: <strong>command-debug-status</strong>
</dt> <dd>
<p>This variable records the debugging status of the current interactive command. Each time a command is called interactively, this variable is bound to <code>nil</code>. The debugger can set this variable to leave information for future debugger invocations during the same command invocation. </p> <p>The advantage of using this variable rather than an ordinary global variable is that the data will never carry over to a subsequent command invocation. </p> <p>This variable is obsolete and will be removed in future versions. </p>
</dd>
</dl> <dl> <dt id="backtrace-frame">Function: <strong>backtrace-frame</strong> <em>frame-number &optional base</em>
</dt> <dd>
<p>The function <code>backtrace-frame</code> is intended for use in Lisp debuggers. It returns information about what computation is happening in the stack frame <var>frame-number</var> levels down. </p> <p>If that frame has not evaluated the arguments yet, or is a special form, the value is <code>(nil <var>function</var> <var>arg-forms</var>…)</code>. </p> <p>If that frame has evaluated its arguments and called its function already, the return value is <code>(t <var>function</var>
<var>arg-values</var>…)</code>. </p> <p>In the return value, <var>function</var> is whatever was supplied as the <small>CAR</small> of the evaluated list, or a <code>lambda</code> expression in the case of a macro call. If the function has a <code>&rest</code> argument, that is represented as the tail of the list <var>arg-values</var>. </p> <p>If <var>base</var> is specified, <var>frame-number</var> counts relative to the topmost frame whose <var>function</var> is <var>base</var>. </p> <p>If <var>frame-number</var> is out of range, <code>backtrace-frame</code> returns <code>nil</code>. </p>
</dd>
</dl> <dl> <dt id="mapbacktrace">Function: <strong>mapbacktrace</strong> <em>function &optional base</em>
</dt> <dd>
<p>The function <code>mapbacktrace</code> calls <var>function</var> once for each frame in the backtrace, starting at the first frame whose function is <var>base</var> (or from the top if <var>base</var> is omitted or <code>nil</code>). </p> <p><var>function</var> is called with four arguments: <var>evald</var>, <var>func</var>, <var>args</var>, and <var>flags</var>. </p> <p>If a frame has not evaluated its arguments yet or is a special form, <var>evald</var> is <code>nil</code> and <var>args</var> is a list of forms. </p> <p>If a frame has evaluated its arguments and called its function already, <var>evald</var> is <code>t</code> and <var>args</var> is a list of values. <var>flags</var> is a plist of properties of the current frame: currently, the only supported property is <code>:debug-on-exit</code>, which is <code>t</code> if the stack frame’s <code>debug-on-exit</code> flag is set. </p>
</dd>
</dl><div class="_attribution">
<p class="_attribution-p">
Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
<a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Internals-of-Debugger.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Internals-of-Debugger.html</a>
</p>
</div>
|
