Commit | Line | Data |
---|---|---|
a0e07ba4 NJ |
1 | @page |
2 | @node Debugging | |
f2ba76ae | 3 | @chapter Debugging Infrastructure |
a0e07ba4 | 4 | |
8f85c0c6 NJ |
5 | @deffn {Scheme Procedure} debug-options-interface [setting] |
6 | @deffnx {C Function} scm_debug_options (setting) | |
a0e07ba4 NJ |
7 | Option interface for the debug options. Instead of using |
8 | this procedure directly, use the procedures @code{debug-enable}, | |
198586ed | 9 | @code{debug-disable}, @code{debug-set!} and @code{debug-options}. |
a0e07ba4 NJ |
10 | @end deffn |
11 | ||
f2ba76ae NJ |
12 | |
13 | @section Using Traps | |
14 | ||
8f85c0c6 NJ |
15 | @deffn {Scheme Procedure} with-traps thunk |
16 | @deffnx {C Function} scm_with_traps (thunk) | |
a0e07ba4 NJ |
17 | Call @var{thunk} with traps enabled. |
18 | @end deffn | |
19 | ||
8f85c0c6 NJ |
20 | @deffn {Scheme Procedure} debug-object? obj |
21 | @deffnx {C Function} scm_debug_object_p (obj) | |
a0e07ba4 NJ |
22 | Return @code{#t} if @var{obj} is a debug object. |
23 | @end deffn | |
24 | ||
a0e07ba4 | 25 | |
f2ba76ae | 26 | @section Capturing the Stack or Innermost Stack Frame |
a0e07ba4 | 27 | |
ce9d0562 NJ |
28 | When an error occurs in a running program, or the program hits a |
29 | breakpoint, its state at that point can be represented by a @dfn{stack} | |
30 | of all the evaluations and procedure applications that are logically in | |
31 | progress at that time, each of which is known as a @dfn{frame}. The | |
32 | programmer can learn more about the program's state at the point of | |
33 | interruption or error by inspecting the stack and its frames. | |
34 | ||
8f85c0c6 NJ |
35 | @deffn {Scheme Procedure} make-stack obj . args |
36 | @deffnx {C Function} scm_make_stack (obj, args) | |
a0e07ba4 NJ |
37 | Create a new stack. If @var{obj} is @code{#t}, the current |
38 | evaluation stack is used for creating the stack frames, | |
39 | otherwise the frames are taken from @var{obj} (which must be | |
40 | either a debug object or a continuation). | |
41 | ||
42 | @var{args} should be a list containing any combination of | |
43 | integer, procedure and @code{#t} values. | |
44 | ||
45 | These values specify various ways of cutting away uninteresting | |
46 | stack frames from the top and bottom of the stack that | |
47 | @code{make-stack} returns. They come in pairs like this: | |
48 | @code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2} | |
49 | @var{outer_cut_2} @dots{})}. | |
50 | ||
51 | Each @var{inner_cut_N} can be @code{#t}, an integer, or a | |
52 | procedure. @code{#t} means to cut away all frames up to but | |
53 | excluding the first user module frame. An integer means to cut | |
54 | away exactly that number of frames. A procedure means to cut | |
55 | away all frames up to but excluding the application frame whose | |
56 | procedure matches the specified one. | |
57 | ||
58 | Each @var{outer_cut_N} can be an integer or a procedure. An | |
59 | integer means to cut away that number of frames. A procedure | |
60 | means to cut away frames down to but excluding the application | |
61 | frame whose procedure matches the specified one. | |
62 | ||
63 | If the @var{outer_cut_N} of the last pair is missing, it is | |
64 | taken as 0. | |
65 | @end deffn | |
66 | ||
f2ba76ae NJ |
67 | @deffn {Scheme Procedure} last-stack-frame obj |
68 | @deffnx {C Function} scm_last_stack_frame (obj) | |
69 | Return a stack which consists of a single frame, which is the | |
70 | last stack frame for @var{obj}. @var{obj} must be either a | |
71 | debug object or a continuation. | |
72 | @end deffn | |
73 | ||
74 | ||
75 | @section Examining the Stack | |
76 | ||
77 | @deffn {Scheme Procedure} stack? obj | |
78 | @deffnx {C Function} scm_stack_p (obj) | |
79 | Return @code{#t} if @var{obj} is a calling stack. | |
80 | @end deffn | |
81 | ||
8f85c0c6 NJ |
82 | @deffn {Scheme Procedure} stack-id stack |
83 | @deffnx {C Function} scm_stack_id (stack) | |
a0e07ba4 NJ |
84 | Return the identifier given to @var{stack} by @code{start-stack}. |
85 | @end deffn | |
86 | ||
8f85c0c6 NJ |
87 | @deffn {Scheme Procedure} stack-length stack |
88 | @deffnx {C Function} scm_stack_length (stack) | |
a0e07ba4 NJ |
89 | Return the length of @var{stack}. |
90 | @end deffn | |
91 | ||
8f85c0c6 NJ |
92 | @deffn {Scheme Procedure} stack-ref stack index |
93 | @deffnx {C Function} scm_stack_ref (stack, index) | |
9401323e | 94 | Return the @var{index}'th frame from @var{stack}. |
a0e07ba4 NJ |
95 | @end deffn |
96 | ||
f2ba76ae NJ |
97 | @deffn {Scheme Procedure} display-backtrace stack port [first [depth]] |
98 | @deffnx {C Function} scm_display_backtrace (stack, port, first, depth) | |
99 | Display a backtrace to the output port @var{port}. @var{stack} | |
100 | is the stack to take the backtrace from, @var{first} specifies | |
101 | where in the stack to start and @var{depth} how much frames | |
102 | to display. Both @var{first} and @var{depth} can be @code{#f}, | |
103 | which means that default values will be used. | |
104 | @end deffn | |
105 | ||
106 | ||
107 | @section Examining Stack Frames | |
108 | ||
109 | @deffn {Scheme Procedure} frame? obj | |
110 | @deffnx {C Function} scm_frame_p (obj) | |
111 | Return @code{#t} if @var{obj} is a stack frame. | |
112 | @end deffn | |
113 | ||
114 | @deffn {Scheme Procedure} frame-number frame | |
115 | @deffnx {C Function} scm_frame_number (frame) | |
116 | Return the frame number of @var{frame}. | |
117 | @end deffn | |
118 | ||
119 | @deffn {Scheme Procedure} frame-previous frame | |
120 | @deffnx {C Function} scm_frame_previous (frame) | |
121 | Return the previous frame of @var{frame}, or @code{#f} if | |
122 | @var{frame} is the first frame in its stack. | |
123 | @end deffn | |
124 | ||
125 | @deffn {Scheme Procedure} frame-next frame | |
126 | @deffnx {C Function} scm_frame_next (frame) | |
127 | Return the next frame of @var{frame}, or @code{#f} if | |
128 | @var{frame} is the last frame in its stack. | |
129 | @end deffn | |
130 | ||
131 | @deffn {Scheme Procedure} frame-source frame | |
132 | @deffnx {C Function} scm_frame_source (frame) | |
133 | Return the source of @var{frame}. | |
134 | @end deffn | |
135 | ||
136 | @deffn {Scheme Procedure} frame-procedure? frame | |
137 | @deffnx {C Function} scm_frame_procedure_p (frame) | |
138 | Return @code{#t} if a procedure is associated with @var{frame}. | |
139 | @end deffn | |
140 | ||
141 | @deffn {Scheme Procedure} frame-procedure frame | |
142 | @deffnx {C Function} scm_frame_procedure (frame) | |
143 | Return the procedure for @var{frame}, or @code{#f} if no | |
144 | procedure is associated with @var{frame}. | |
145 | @end deffn | |
146 | ||
147 | @deffn {Scheme Procedure} frame-arguments frame | |
148 | @deffnx {C Function} scm_frame_arguments (frame) | |
149 | Return the arguments of @var{frame}. | |
150 | @end deffn | |
151 | ||
152 | @deffn {Scheme Procedure} frame-evaluating-args? frame | |
153 | @deffnx {C Function} scm_frame_evaluating_args_p (frame) | |
154 | Return @code{#t} if @var{frame} contains evaluated arguments. | |
155 | @end deffn | |
156 | ||
157 | @deffn {Scheme Procedure} frame-overflow? frame | |
158 | @deffnx {C Function} scm_frame_overflow_p (frame) | |
159 | Return @code{#t} if @var{frame} is an overflow frame. | |
160 | @end deffn | |
161 | ||
162 | @deffn {Scheme Procedure} frame-real? frame | |
163 | @deffnx {C Function} scm_frame_real_p (frame) | |
164 | Return @code{#t} if @var{frame} is a real frame. | |
165 | @end deffn | |
166 | ||
167 | @deffn {Scheme Procedure} display-application frame [port [indent]] | |
168 | @deffnx {C Function} scm_display_application (frame, port, indent) | |
169 | Display a procedure application @var{frame} to the output port | |
170 | @var{port}. @var{indent} specifies the indentation of the | |
171 | output. | |
172 | @end deffn | |
173 | ||
174 | ||
175 | @section Decoding Memoized Source Expressions | |
176 | ||
177 | @deffn {Scheme Procedure} memoized? obj | |
178 | @deffnx {C Function} scm_memoized_p (obj) | |
179 | Return @code{#t} if @var{obj} is memoized. | |
180 | @end deffn | |
181 | ||
182 | @deffn {Scheme Procedure} unmemoize m | |
183 | @deffnx {C Function} scm_unmemoize (m) | |
184 | Unmemoize the memoized expression @var{m}, | |
185 | @end deffn | |
186 | ||
187 | @deffn {Scheme Procedure} memoized-environment m | |
188 | @deffnx {C Function} scm_memoized_environment (m) | |
189 | Return the environment of the memoized expression @var{m}. | |
a0e07ba4 NJ |
190 | @end deffn |
191 | ||
192 | ||
ce9d0562 NJ |
193 | @section Starting a New Stack |
194 | ||
195 | @deffn {Scheme Syntax} start-stack id exp | |
196 | Evaluate @var{exp} on a new calling stack with identity @var{id}. If | |
197 | @var{exp} is interrupted during evaluation, backtraces will not display | |
198 | frames farther back than @var{exp}'s top-level form. This macro is a | |
199 | way of artificially limiting backtraces and stack procedures, largely as | |
200 | a convenience to the user. | |
201 | @end deffn | |
202 | ||
203 | ||
a0e07ba4 NJ |
204 | @c Local Variables: |
205 | @c TeX-master: "guile.texi" | |
206 | @c End: |