doc/ref/scheme-debug.texi

   1 @page
   2 @node Debugging
   3 @chapter Internal Debugging Interface
   4
   5 --- The name of this chapter needs to clearly distinguish it
   6     from the appendix describing the debugger UI.  The intro
   7     should have a pointer to the UI appendix.
   8
   9 @deffn {Scheme Procedure} display-error stack port subr message args rest
  10 @deffnx {C Function} scm_display_error (stack, port, subr, message, args, rest)
  11 Display an error message to the output port @var{port}.
  12 @var{stack} is the saved stack for the error, @var{subr} is
  13 the name of the procedure in which the error occurred and
  14 @var{message} is the actual error message, which may contain
  15 formatting instructions. These will format the arguments in
  16 the list @var{args} accordingly.  @var{rest} is currently
  17 ignored.
  18 @end deffn
  19
  20 @deffn {Scheme Procedure} display-application frame [port [indent]]
  21 @deffnx {C Function} scm_display_application (frame, port, indent)
  22 Display a procedure application @var{frame} to the output port
  23 @var{port}. @var{indent} specifies the indentation of the
  24 output.
  25 @end deffn
  26
  27 @deffn {Scheme Procedure} display-backtrace stack port [first [depth]]
  28 @deffnx {C Function} scm_display_backtrace (stack, port, first, depth)
  29 Display a backtrace to the output port @var{port}. @var{stack}
  30 is the stack to take the backtrace from, @var{first} specifies
  31 where in the stack to start and @var{depth} how much frames
  32 to display. Both @var{first} and @var{depth} can be @code{#f},
  33 which means that default values will be used.
  34 @end deffn
  35
  36 @deffn {Scheme Procedure} backtrace
  37 @deffnx {C Function} scm_backtrace ()
  38 Display a backtrace of the stack saved by the last error
  39 to the current output port.
  40 @end deffn
  41
  42 @deffn {Scheme Procedure} malloc-stats
  43 Return an alist ((@var{what} . @var{n}) ...) describing number
  44 of malloced objects.
  45 @var{what} is the second argument to @code{scm_must_malloc},
  46 @var{n} is the number of objects of that type currently
  47 allocated.
  48 @end deffn
  49
  50 @deffn {Scheme Procedure} debug-options-interface [setting]
  51 @deffnx {C Function} scm_debug_options (setting)
  52 Option interface for the debug options. Instead of using
  53 this procedure directly, use the procedures @code{debug-enable},
  54 @code{debug-disable}, @code{debug-set!} and @var{debug-options}.
  55 @end deffn
  56
  57 @deffn {Scheme Procedure} with-traps thunk
  58 @deffnx {C Function} scm_with_traps (thunk)
  59 Call @var{thunk} with traps enabled.
  60 @end deffn
  61
  62 @deffn {Scheme Procedure} memoized? obj
  63 @deffnx {C Function} scm_memoized_p (obj)
  64 Return @code{#t} if @var{obj} is memoized.
  65 @end deffn
  66
  67 @deffn {Scheme Procedure} unmemoize m
  68 @deffnx {C Function} scm_unmemoize (m)
  69 Unmemoize the memoized expression @var{m},
  70 @end deffn
  71
  72 @deffn {Scheme Procedure} memoized-environment m
  73 @deffnx {C Function} scm_memoized_environment (m)
  74 Return the environment of the memoized expression @var{m}.
  75 @end deffn
  76
  77 @deffn {Scheme Procedure} procedure-name proc
  78 @deffnx {C Function} scm_procedure_name (proc)
  79 Return the name of the procedure @var{proc}
  80 @end deffn
  81
  82 @deffn {Scheme Procedure} procedure-source proc
  83 @deffnx {C Function} scm_procedure_source (proc)
  84 Return the source of the procedure @var{proc}.
  85 @end deffn
  86
  87 @deffn {Scheme Procedure} procedure-environment proc
  88 @deffnx {C Function} scm_procedure_environment (proc)
  89 Return the environment of the procedure @var{proc}.
  90 @end deffn
  91
  92 @deffn {Scheme Procedure} debug-object? obj
  93 @deffnx {C Function} scm_debug_object_p (obj)
  94 Return @code{#t} if @var{obj} is a debug object.
  95 @end deffn
  96
  97 @deffn {Scheme Procedure} frame-arguments frame
  98 @deffnx {C Function} scm_frame_arguments (frame)
  99 Return the arguments of @var{frame}.
 100 @end deffn
 101
 102 @deffn {Scheme Procedure} frame-evaluating-args? frame
 103 @deffnx {C Function} scm_frame_evaluating_args_p (frame)
 104 Return @code{#t} if @var{frame} contains evaluated arguments.
 105 @end deffn
 106
 107 @deffn {Scheme Procedure} frame-next frame
 108 @deffnx {C Function} scm_frame_next (frame)
 109 Return the next frame of @var{frame}, or @code{#f} if
 110 @var{frame} is the last frame in its stack.
 111 @end deffn
 112
 113 @deffn {Scheme Procedure} frame-number frame
 114 @deffnx {C Function} scm_frame_number (frame)
 115 Return the frame number of @var{frame}.
 116 @end deffn
 117
 118 @deffn {Scheme Procedure} frame-overflow? frame
 119 @deffnx {C Function} scm_frame_overflow_p (frame)
 120 Return @code{#t} if @var{frame} is an overflow frame.
 121 @end deffn
 122
 123 @deffn {Scheme Procedure} frame-previous frame
 124 @deffnx {C Function} scm_frame_previous (frame)
 125 Return the previous frame of @var{frame}, or @code{#f} if
 126 @var{frame} is the first frame in its stack.
 127 @end deffn
 128
 129 @deffn {Scheme Procedure} frame-procedure frame
 130 @deffnx {C Function} scm_frame_procedure (frame)
 131 Return the procedure for @var{frame}, or @code{#f} if no
 132 procedure is associated with @var{frame}.
 133 @end deffn
 134
 135 @deffn {Scheme Procedure} frame-procedure? frame
 136 @deffnx {C Function} scm_frame_procedure_p (frame)
 137 Return @code{#t} if a procedure is associated with @var{frame}.
 138 @end deffn
 139
 140 @deffn {Scheme Procedure} frame-real? frame
 141 @deffnx {C Function} scm_frame_real_p (frame)
 142 Return @code{#t} if @var{frame} is a real frame.
 143 @end deffn
 144
 145 @deffn {Scheme Procedure} frame-source frame
 146 @deffnx {C Function} scm_frame_source (frame)
 147 Return the source of @var{frame}.
 148 @end deffn
 149
 150 @deffn {Scheme Procedure} frame? obj
 151 @deffnx {C Function} scm_frame_p (obj)
 152 Return @code{#t} if @var{obj} is a stack frame.
 153 @end deffn
 154
 155 @deffn {Scheme Procedure} last-stack-frame obj
 156 @deffnx {C Function} scm_last_stack_frame (obj)
 157 Return a stack which consists of a single frame, which is the
 158 last stack frame for @var{obj}. @var{obj} must be either a
 159 debug object or a continuation.
 160 @end deffn
 161
 162 @deffn {Scheme Procedure} make-stack obj . args
 163 @deffnx {C Function} scm_make_stack (obj, args)
 164 Create a new stack. If @var{obj} is @code{#t}, the current
 165 evaluation stack is used for creating the stack frames,
 166 otherwise the frames are taken from @var{obj} (which must be
 167 either a debug object or a continuation).
 168
 169 @var{args} should be a list containing any combination of
 170 integer, procedure and @code{#t} values.
 171
 172 These values specify various ways of cutting away uninteresting
 173 stack frames from the top and bottom of the stack that
 174 @code{make-stack} returns.  They come in pairs like this:
 175 @code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2}
 176 @var{outer_cut_2} @dots{})}.
 177
 178 Each @var{inner_cut_N} can be @code{#t}, an integer, or a
 179 procedure.  @code{#t} means to cut away all frames up to but
 180 excluding the first user module frame.  An integer means to cut
 181 away exactly that number of frames.  A procedure means to cut
 182 away all frames up to but excluding the application frame whose
 183 procedure matches the specified one.
 184
 185 Each @var{outer_cut_N} can be an integer or a procedure.  An
 186 integer means to cut away that number of frames.  A procedure
 187 means to cut away frames down to but excluding the application
 188 frame whose procedure matches the specified one.
 189
 190 If the @var{outer_cut_N} of the last pair is missing, it is
 191 taken as 0.
 192 @end deffn
 193
 194 @deffn {Scheme Procedure} stack-id stack
 195 @deffnx {C Function} scm_stack_id (stack)
 196 Return the identifier given to @var{stack} by @code{start-stack}.
 197 @end deffn
 198
 199 @deffn {Scheme Procedure} stack-length stack
 200 @deffnx {C Function} scm_stack_length (stack)
 201 Return the length of @var{stack}.
 202 @end deffn
 203
 204 @deffn {Scheme Procedure} stack-ref stack index
 205 @deffnx {C Function} scm_stack_ref (stack, index)
 206 Return the @var{index}'th frame from @var{stack}.
 207 @end deffn
 208
 209 @deffn {Scheme Procedure} stack? obj
 210 @deffnx {C Function} scm_stack_p (obj)
 211 Return @code{#t} if @var{obj} is a calling stack.
 212 @end deffn
 213
 214
 215 @c Local Variables:
 216 @c TeX-master: "guile.texi"
 217 @c End: