doc/info/Debugging.texi

   1 @menu
   2 * Source Level Debugging::
   3 * Keyword Commands::
   4 * Functions and Variables for Debugging::
   5 @end menu
   6
   7 @c -----------------------------------------------------------------------------
   8 @node Source Level Debugging, Keyword Commands, , Debugging
   9 @section Source Level Debugging
  10 @c -----------------------------------------------------------------------------
  11
  12 Maxima has a built-in source level debugger.
  13 The user can set a breakpoint at a function,
  14 and then step line by line from there.  The call
  15 stack may be examined, together with the variables bound at that level.
  16
  17 The command @code{:help} or @code{:h} shows the list of debugger commands.
  18 (In general,
  19 commands may be abbreviated if the abbreviation is unique.  If not
  20 unique, the alternatives will be listed.)
  21 Within the debugger, the user can also use any ordinary Maxima
  22 functions to examine, define, and manipulate variables and expressions.
  23
  24 A breakpoint is set by the @code{:br} command at the Maxima prompt.
  25 Within the debugger,
  26 the user can advance one line at a time using the @code{:n} (``next'') command.
  27 The @code{:bt} (``backtrace'') command shows a list of stack frames.
  28 The @code{:r} (``resume'') command exits the debugger and continues with
  29 execution.  These commands are demonstrated in the example below.
  30
  31 @example
  32 (%i1) load ("/tmp/foobar.mac");
  33
  34 (%o1)                           /tmp/foobar.mac
  35
  36 (%i2) :br foo
  37 Turning on debugging debugmode(true)
  38 Bkpt 0 for foo (in /tmp/foobar.mac line 1)
  39
  40 (%i2) bar (2,3);
  41 Bkpt 0:(foobar.mac 1)
  42 /tmp/foobar.mac:1::
  43
  44 (dbm:1) :bt                        <-- :bt typed here gives a backtrace
  45 #0: foo(y=5)(foobar.mac line 1)
  46 #1: bar(x=2,y=3)(foobar.mac line 9)
  47
  48 (dbm:1) :n                         <-- Here type :n to advance line
  49 (foobar.mac 2)
  50 /tmp/foobar.mac:2::
  51
  52 (dbm:1) :n                         <-- Here type :n to advance line
  53 (foobar.mac 3)
  54 /tmp/foobar.mac:3::
  55
  56 (dbm:1) u;                         <-- Investigate value of u
  57 28
  58
  59 (dbm:1) u: 33;                     <-- Change u to be 33
  60 33
  61
  62 (dbm:1) :r                         <-- Type :r to resume the computation
  63
  64 (%o2)                                1094
  65 @end example
  66
  67 The file @code{/tmp/foobar.mac} is the following:
  68
  69 @example
  70 foo(y) := block ([u:y^2],
  71   u: u+3,
  72   u: u^2,
  73   u);
  74
  75 bar(x,y) := (
  76   x: x+2,
  77   y: y+2,
  78   x: foo(y),
  79   x+y);
  80 @end example
  81
  82 USE OF THE DEBUGGER THROUGH EMACS
  83
  84 If the user is running the code under GNU emacs in a shell
  85 window (dbl shell), or is running the graphical interface version,
  86 Xmaxima, then if he stops at a break point, he will see his
  87 current position in the source file which will be displayed in the
  88 other half of the window, either highlighted in red, or with a little
  89 arrow pointing at the right line.  He can advance single lines at a
  90 time by typing M-n (Alt-n).
  91
  92 Under Emacs you should run in a @code{dbl} shell, which requires the
  93 @code{dbl.el} file in the elisp directory.
  94 Make sure you install the elisp files or add the Maxima elisp directory to
  95 your path:
  96 e.g., add the following to your @file{.emacs} file or the @file{site-init.el}
  97
  98 @example
  99 (setq load-path (cons "/usr/share/maxima/5.9.1/emacs" load-path))
 100 (autoload 'dbl "dbl")
 101 @end example
 102
 103 then in emacs
 104
 105 @example
 106 M-x dbl
 107 @end example
 108
 109 should start a shell window in which you can run programs, for example
 110 Maxima, gcl, gdb etc.   This shell window also knows about source level
 111 debugging, and display of source code in the other window.
 112
 113 The user may set a break point at a certain line of the
 114 file by typing @code{C-x space}.  This figures out which function
 115 the cursor is in, and then it sees which line of that function
 116 the cursor is on.   If the cursor is on, say, line 2 of @code{foo}, then it will
 117 insert in the other window the command, ``@code{:br foo 2}'', to
 118 break @code{foo} at its second line.   To have this enabled, the user must have
 119 maxima-mode.el turned on in the window in which the file @code{foobar.mac} is
 120 visiting.  There are additional commands available in that file window, such as
 121 evaluating the function into the Maxima, by typing @code{Alt-Control-x}.
 122
 123 @opencatbox{Categories:}
 124 @category{Debugging}
 125 @closecatbox
 126
 127 @c -----------------------------------------------------------------------------
 128 @node Keyword Commands, Functions and Variables for Debugging, Source Level Debugging, Debugging
 129 @section Keyword Commands
 130 @c -----------------------------------------------------------------------------
 131
 132 Keyword commands are special keywords which are not interpreted as Maxima
 133 expressions.  A keyword command can be entered at the Maxima prompt or the
 134 debugger prompt, although not at the break prompt.
 135 Keyword commands start with a colon, '@code{:}'.
 136 For example, to evaluate a Lisp form you
 137 may type @code{:lisp} followed by the form to be evaluated.
 138
 139 @example
 140 (%i1) :lisp (+ 2 3)
 141 5
 142 @end example
 143
 144 The number of arguments taken depends on the particular command.  Also,
 145 you need not type the whole command, just enough to be unique among
 146 the break keywords.   Thus @code{:br} would suffice for @code{:break}.
 147
 148 The keyword commands are listed below.
 149
 150 @table @code
 151 @item :break F n
 152 Set a breakpoint in function @code{F} at line offset @code{n}
 153 from the beginning of the function.
 154 If @code{F} is given as a string, then it is assumed to be
 155 a file, and @code{n} is the offset from the beginning of the file.
 156 The offset is optional. If not given, it is assumed to be zero
 157 (first line of the function or file).
 158 @item :bt
 159 Print a backtrace of the stack frames
 160 @item :continue
 161 Continue the computation
 162 @c CAN'T SEEM TO GET :delete TO WORK !!!
 163 @item :delete
 164 Delete the specified breakpoints, or all if none are specified
 165 @c CAN'T SEEM TO GET :disable TO WORK !!!
 166 @item :disable
 167 Disable the specified breakpoints, or all if none are specified
 168 @c CAN'T SEEM TO GET :enable TO WORK !!!
 169 @item :enable
 170 Enable the specified breakpoints, or all if none are specified
 171 @item :frame n
 172 Print stack frame @code{n}, or the current frame if none is specified
 173 @c CAN'T SEEM TO GET :help TO WORK !!!
 174 @item :help
 175 Print help on a debugger command, or all commands if none is specified
 176 @c CAN'T SEEM TO GET :info TO WORK !!!
 177 @item :info
 178 Print information about item
 179 @item :lisp some-form
 180 Evaluate @code{some-form} as a Lisp form
 181 @item :lisp-quiet some-form
 182 Evaluate Lisp form @code{some-form} without any output
 183 @item :next
 184 Like @code{:step}, except @code{:next} steps over function calls
 185 @item :quit
 186 Quit the current debugger level without completing the computation
 187 @item :resume
 188 Continue the computation
 189 @item :step
 190 Continue the computation until it reaches a new source line
 191 @item :top
 192 Return to the Maxima prompt (from any debugger level) without
 193 completing the computation
 194 @end table
 195
 196 @c Document the issue reported as https://sourceforge.net/p/maxima/bugs/4086/
 197
 198 Note: Keyword commands must (currently) start at the beginning of a line.
 199 Not even a single space character is allowed before the colon.
 200
 201 @opencatbox{Categories:}
 202 @category{Debugging}
 203 @closecatbox
 204
 205 @c -----------------------------------------------------------------------------
 206 @node Functions and Variables for Debugging, , Keyword Commands, Debugging
 207 @section Functions and Variables for Debugging
 208 @c -----------------------------------------------------------------------------
 209
 210 @c -----------------------------------------------------------------------------
 211 @anchor{debugmode}
 212 @defvr {Option variable} debugmode
 213 Default value: @code{false}
 214
 215 When @code{debugmode} is @code{true}, Maxima will start the Maxima debugger
 216 when a Maxima error occurs.  At this point the user may enter commands to
 217 examine the call stack, set breakpoints, step through Maxima code, and so on.
 218 See @code{debugging} for a list of Maxima debugger commands.
 219
 220 When @code{debugmode} is @code{lisp}, Maxima will start the Lisp debugger
 221 when a Maxima error occurs.
 222
 223 In either case, enabling @code{debugmode} will not catch Lisp errors.
 224
 225 @c DO WE WANT TO SAY MORE ABOUT DEBUGGING LISP ERRORS ???
 226 @c I'M NOT CONVINCED WE WANT TO OPEN THAT CAN OF WORMS !!!
 227
 228 @opencatbox{Categories:}
 229 @category{Debugging}
 230 @category{Global flags}
 231 @closecatbox
 232 @end defvr
 233
 234 @c -----------------------------------------------------------------------------
 235 @anchor{refcheck}
 236 @defvr {Option variable} refcheck
 237 Default value: @code{false}
 238
 239 When @code{refcheck} is @code{true}, Maxima prints a message
 240 each time a bound variable is used for the first time in a
 241 computation.
 242
 243 @opencatbox{Categories:}
 244 @category{Evaluation}
 245 @category{Console interaction}
 246 @category{Global flags}
 247 @closecatbox
 248 @end defvr
 249
 250 @c -----------------------------------------------------------------------------
 251 @anchor{setcheck}
 252 @defvr {Option variable} setcheck
 253 Default value: @code{false}
 254
 255 If @code{setcheck} is set to a list of variables (which can
 256 be subscripted),
 257 Maxima prints a message whenever the variables, or
 258 subscripted occurrences of them, are bound with the
 259 ordinary assignment operator @code{:}, the @code{::} assignment
 260 operator, or function argument binding,
 261 but not the function assignment @code{:=} nor the macro assignment
 262 @code{::=} operators.
 263 The message comprises the name of the variable and the
 264 value it is bound to.
 265
 266 @code{setcheck} may be set to @code{all} or @code{true} thereby
 267 including all variables.
 268
 269 Each new assignment of @code{setcheck} establishes a new list of variables to
 270 check, and any variables previously assigned to @code{setcheck} are forgotten.
 271
 272 The names assigned to @code{setcheck} must be quoted if they would otherwise
 273 evaluate to something other than themselves.
 274 For example, if @code{x}, @code{y}, and @code{z} are already bound, then enter
 275
 276 @example
 277 setcheck: ['x, 'y, 'z]$
 278 @end example
 279
 280 to put them on the list of variables to check.
 281
 282 No printout is generated when a
 283 variable on the @code{setcheck} list is assigned to itself, e.g., @code{X: 'X}.
 284
 285 @opencatbox{Categories:}
 286 @category{Console interaction}
 287 @category{Global flags}
 288 @closecatbox
 289 @end defvr
 290
 291 @c -----------------------------------------------------------------------------
 292 @anchor{setcheckbreak}
 293 @defvr {Option variable} setcheckbreak
 294 Default value: @code{false}
 295
 296 When @code{setcheckbreak} is @code{true},
 297 Maxima will present a break prompt
 298 whenever a variable on the @code{setcheck} list is assigned a new value.
 299 The break occurs before the assignment is carried out.
 300 At this point, @code{setval} holds the value to which the variable is
 301 about to be assigned.
 302 Hence, one may assign a different value by assigning to @code{setval}.
 303
 304 See also @mref{setcheck} and @mrefdot{setval}
 305
 306 @opencatbox{Categories:}
 307 @category{Console interaction}
 308 @category{Global flags}
 309 @closecatbox
 310 @end defvr
 311
 312 @c -----------------------------------------------------------------------------
 313 @anchor{setval}
 314 @defvr {System variable} setval
 315
 316 Holds the value to which a variable is about to be set when
 317 a @mref{setcheckbreak} occurs.
 318 Hence, one may assign a different value by assigning to @mref{setval}.
 319
 320 See also @mref{setcheck} and @mrefdot{setcheckbreak}
 321
 322 @opencatbox{Categories:}
 323 @category{Console interaction}
 324 @category{Global variables}
 325 @closecatbox
 326 @end defvr
 327
 328 @c -----------------------------------------------------------------------------
 329 @anchor{timer}
 330 @deffn  {Function} timer (@var{f_1}, @dots{}, @var{f_n}) @
 331 @fname{timer} (all) @
 332 @fname{timer} ()
 333
 334 Given functions @var{f_1}, @dots{}, @var{f_n}, @code{timer} puts each one on the
 335 list of functions for which timing statistics are collected.
 336 @code{timer(f)$ timer(g)$} puts @code{f} and then @code{g} onto the list;
 337 the list accumulates from one call to the next.
 338
 339 @code{timer(all)} puts all user-defined functions (as named by the global
 340 variable @code{functions}) on the list of timed functions.
 341
 342 With no arguments,  @code{timer} returns the list of timed functions.
 343
 344 Maxima records how much time is spent executing each function
 345 on the list of timed functions.
 346 @code{timer_info} returns the timing statistics, including the
 347 average time elapsed per function call, the number of calls, and the
 348 total time elapsed.
 349 @code{untimer} removes functions from the list of timed functions.
 350
 351 @code{timer} quotes its arguments.
 352 @code{f(x) := x^2$ g:f$ timer(g)$} does not put @code{f} on the timer list.
 353
 354 If @code{trace(f)} is in effect, then @code{timer(f)} has no effect;
 355 @code{trace} and @code{timer} cannot both be in effect at the same time.
 356
 357 See also @mrefdot{timer_devalue}
 358
 359 @opencatbox{Categories:}
 360 @category{Debugging}
 361 @closecatbox
 362 @end deffn
 363
 364 @c -----------------------------------------------------------------------------
 365 @anchor{untimer}
 366 @deffn  {Function} untimer (@var{f_1}, @dots{}, @var{f_n}) @
 367 @fname{untimer} ()
 368
 369 Given functions @var{f_1}, @dots{}, @var{f_n},
 370 @code{untimer} removes each function from the timer list.
 371
 372 With no arguments, @code{untimer} removes all functions currently on the timer
 373 list.
 374
 375 After @code{untimer (f)} is executed, @code{timer_info (f)} still returns
 376 previously collected timing statistics,
 377 although @code{timer_info()} (with no arguments) does not
 378 return information about any function not currently on the timer list.
 379 @code{timer (f)} resets all timing statistics to zero
 380 and puts @code{f} on the timer list again.
 381
 382 @opencatbox{Categories:}
 383 @category{Debugging}
 384 @closecatbox
 385 @end deffn
 386
 387 @c -----------------------------------------------------------------------------
 388 @anchor{timer_devalue}
 389 @defvr {Option variable} timer_devalue
 390 Default value: @code{false}
 391
 392 When @code{timer_devalue} is @code{true}, Maxima subtracts from each timed
 393 function the time spent in other timed functions.  Otherwise, the time reported
 394 for each function includes the time spent in other functions.
 395 Note that time spent in untimed functions is not subtracted from the
 396 total time.
 397
 398 See also @mref{timer} and @mrefdot{timer_info}
 399
 400 @opencatbox{Categories:}
 401 @category{Debugging}
 402 @category{Global flags}
 403 @closecatbox
 404 @end defvr
 405
 406 @c -----------------------------------------------------------------------------
 407 @anchor{timer_info}
 408 @deffn {Function} timer_info (@var{f_1}, ..., @var{f_n}) @
 409 @fname{timer_info} ()
 410
 411 Given functions @var{f_1}, ..., @var{f_n}, @code{timer_info} returns a matrix
 412 containing timing information for each function.
 413 With no arguments, @code{timer_info} returns timing information for
 414 all functions currently on the timer list.
 415
 416 The matrix returned by @code{timer_info} contains the function name,
 417 time per function call, number of function calls, total time,
 418 and @code{gctime}, which meant "garbage collection time" in the original Macsyma
 419 but is now always zero.
 420
 421 The data from which @code{timer_info} constructs its return value
 422 can also be obtained by the @code{get} function:
 423
 424 @example
 425 get(f, 'calls);  get(f, 'runtime);  get(f, 'gctime);
 426 @end example
 427
 428 See also @mrefdot{timer}
 429
 430 @opencatbox{Categories:}
 431 @category{Debugging}
 432 @closecatbox
 433 @end deffn
 434
 435 @c -----------------------------------------------------------------------------
 436 @anchor{trace}
 437 @deffn  {Function} trace (@var{f_1}, @dots{}, @var{f_n}) @
 438 @fname{trace} (all) @
 439 @fname{trace} ()
 440
 441 Given functions @var{f_1}, @dots{}, @var{f_n}, @code{trace} instructs Maxima to
 442 print out debugging information whenever those functions are called.
 443 @code{trace(f)$ trace(g)$} puts @code{f} and then @code{g} onto the list of
 444 functions to be traced; the list accumulates from one call to the next.
 445
 446 @code{trace(all)} puts all user-defined functions (as named by the global
 447 variable @code{functions}) on the list of functions to be traced.
 448
 449 With no arguments,
 450 @code{trace} returns a list of all the functions currently being traced.
 451
 452 The @code{untrace} function disables tracing.
 453 See also @mrefdot{trace_options}
 454
 455 @code{trace} quotes its arguments.  Thus,
 456 @code{f(x) := x^2$ g:f$ trace(g)$} does not put @code{f} on the trace list.
 457
 458 When a function is redefined, it is removed from the timer list.
 459 Thus after @code{timer(f)$ f(x) := x^2$},
 460 function @code{f} is no longer on the timer list.
 461
 462 If @code{timer (f)} is in effect, then @code{trace (f)} has no effect;
 463 @code{trace} and @code{timer} can't both be in effect for the same function.
 464
 465 @opencatbox{Categories:}
 466 @category{Debugging}
 467 @closecatbox
 468 @end deffn
 469
 470 @c -----------------------------------------------------------------------------
 471 @anchor{trace_options}
 472 @deffn  {Function} trace_options @
 473 @fname{trace_options} (@var{f}, @var{option_1}, @dots{}, @var{option_n}) @
 474 @fname{trace_options} (@var{f})
 475
 476 Sets the trace options for function @var{f}.
 477 Any previous options are superseded.
 478 @code{trace_options (@var{f}, ...)} has no effect unless @code{trace (@var{f})}
 479 is also called (either before or after @code{trace_options}).
 480
 481 @code{trace_options (@var{f})} resets all options to their default values.
 482
 483 The following option keywords are recognized.
 484 The presence of the option keyword alone enables the option unconditionally.
 485 Specifying an option keyword with a predicate function @var{p} as its argument
 486 makes the option conditional on the predicate.
 487
 488 @itemize @bullet
 489 @item
 490 @code{noprint}, @code{noprint(@var{p})}
 491 Do not print a message at function entry and exit.
 492 @item
 493 @code{break}, @code{break(@var{p})}
 494 Stop execution before the function is entered, and after the function is exited.
 495 See also @code{break}.
 496 The arguments of the function and its return value are available as @code{trace_break_arg}
 497 when entering and exiting the function, respectively.
 498 @item
 499 @code{lisp_print}, @code{lisp_print(@var{p})}
 500 Display arguments and return values as Lisp objects.
 501 @item
 502 @code{info}, @code{info(@var{p})}
 503 Display the return value of @var{p} at function entry and exit.
 504 The function @var{p} may also have side effects,
 505 such as displaying output or modifying global variables.
 506 @item
 507 @code{errorcatch}, @code{errorcatch(@var{p})}
 508 Catch errors, giving the option to signal an error,
 509 retry the function call, or specify a return value.
 510 @end itemize
 511
 512 The predicate function, if supplied, is called with four arguments.
 513
 514 @itemize
 515 @item
 516 The recursion level for the function, an integer.
 517 @item
 518 Whether the function is being entered or exited, indicated by a symbol, either @code{enter} or @code{exit}, respectively.
 519 @item
 520 The name of the function, a symbol.
 521 @item
 522 The arguments of the traced function (on entering) or the function return value (on exiting).
 523 @end itemize
 524
 525 If the predicate function returns @code{false},
 526 the corresponding trace option is disabled;
 527 if any value other than @code{false} value is returned, the trace option is enabled.
 528
 529 @code{trace_options} quotes (does not evaluate) its arguments.
 530
 531 Examples:
 532
 533 The presence of the option keyword alone enables the option unconditionally.
 534
 535 @c Omit beg/end markers for this next example, since it triggers user interaction.
 536 @c ff(n) := if equal(n, 0) then 1 else n * ff(n - 1);
 537 @c trace (ff);
 538 @c trace_options (ff, lisp_print, break);
 539 @c ff(3);
 540 @example
 541 (%i1) ff(n) := if equal(n, 0) then 1 else n * ff(n - 1);
 542 (%o1)    ff(n) := if equal(n, 0) then 1 else n ff(n - 1)
 543 (%i2) trace (ff);
 544 (%o2)                         [ff]
 545 (%i3) trace_options (ff, lisp_print, break);
 546 (%o3)                  [lisp_print, break]
 547 (%i4) ff(3);
 548 Trace entering ff level 1
 549
 550 Entering a Maxima break point. Type 'exit;' to resume.
 551 _trace_break_arg;
 552 [3]
 553 _exit;
 554 (1 ENTER $FF (3))
 555 Trace entering ff level 2
 556
 557 Entering a Maxima break point. Type 'exit;' to resume.
 558 _exit;
 559  (2 ENTER $FF (2))
 560 Trace entering ff level 3
 561
 562 Entering a Maxima break point. Type 'exit;' to resume.
 563 _exit;
 564   (3 ENTER $FF (1))
 565 Trace entering ff level 4
 566
 567 Entering a Maxima break point. Type 'exit;' to resume.
 568 _exit;
 569    (4 ENTER $FF (0))
 570 Trace exiting ff level 4
 571
 572 Entering a Maxima break point. Type 'exit;' to resume.
 573 _exit;
 574    (4 EXIT $FF 1)
 575 Trace exiting ff level 3
 576
 577 Entering a Maxima break point. Type 'exit;' to resume.
 578 _exit;
 579   (3 EXIT $FF 1)
 580 Trace exiting ff level 2
 581
 582 Entering a Maxima break point. Type 'exit;' to resume.
 583 _exit;
 584  (2 EXIT $FF 2)
 585 Trace exiting ff level 1
 586
 587 Entering a Maxima break point. Type 'exit;' to resume.
 588 _trace_break_arg;
 589 6
 590 _exit;
 591 (1 EXIT $FF 6)
 592 (%o4)                           6
 593 @end example
 594
 595 Specifying an option keyword with a predicate function @var{p} as its argument
 596 makes the option conditional on the predicate.
 597
 598 @c Omit beg/end markers for this next example, since it triggers user interaction.
 599 @c ff(n) := if equal(n, 0) then 1 else n * ff(n - 1);
 600 @c trace (ff);
 601 @c trace_options (ff, break(pp));
 602 @c pp (level, direction, fnname, item) := (print (item), fnname = 'ff and level = 3 and direction = 'exit);
 603 @c ff(6);
 604 @example
 605 (%i1) ff(n) := if equal(n, 0) then 1 else n * ff(n - 1);
 606 (%o1)    ff(n) := if equal(n, 0) then 1 else n ff(n - 1)
 607 (%i2) trace (ff);
 608 (%o2)                         [ff]
 609 (%i3) trace_options (ff, break(pp));
 610 (%o3)                      [break(pp)]
 611 (%i4) pp (level, direction, fnname, item) := (print (item), fnname = 'ff and level = 3 and direction = 'exit);
 612 (%o4) pp(level, direction, fnname, item) :=
 613 (print(item), (fnname = 'ff) and (level = 3)
 614  and (direction = 'exit))
 615 (%i5) ff(6);
 616 [6]
 617 1 Enter ff [6]
 618 [5]
 619  2 Enter ff [5]
 620 [4]
 621   3 Enter ff [4]
 622 [3]
 623    4 Enter ff [3]
 624 [2]
 625     5 Enter ff [2]
 626 [1]
 627      6 Enter ff [1]
 628 [0]
 629       7 Enter ff [0]
 630 1
 631       7 Exit  ff 1
 632 1
 633      6 Exit  ff 1
 634 2
 635     5 Exit  ff 2
 636 6
 637    4 Exit  ff 6
 638 24
 639 Trace exiting ff level 3
 640
 641 Entering a Maxima break point. Type 'exit;' to resume.
 642 _trace_break_arg;
 643 24
 644 _exit;
 645   3 Exit  ff 24
 646 120
 647  2 Exit  ff 120
 648 720
 649 1 Exit  ff 720
 650 (%o5)                          720
 651 @end example
 652
 653 @opencatbox{Categories:}
 654 @category{Debugging}
 655 @closecatbox
 656 @end deffn
 657
 658 @c -----------------------------------------------------------------------------
 659 @anchor{trace_break_arg}
 660 @defvr {Debugging variable} trace_break_arg
 661
 662 When a traced function stops at a breakpoint,
 663 @code{trace_break_arg} is bound to the value of function arguments when entering the function,
 664 or the return value of the function, when exiting.
 665
 666 Breakpoints for traced functions are specified by the option keyword @code{break} of the function @code{trace_options},
 667 which see.
 668
 669 @opencatbox{Categories:}
 670 @category{Debugging}
 671 @closecatbox
 672 @end defvr
 673
 674 @c -----------------------------------------------------------------------------
 675 @anchor{untrace}
 676 @deffn {Function} untrace @
 677 @fname{untrace} (@var{f_1}, @dots{}, @var{f_n}) @
 678 @fname{untrace} ()
 679
 680 Given functions @var{f_1}, @dots{}, @var{f_n},
 681 @code{untrace} disables tracing enabled by the @code{trace} function.
 682 With no arguments, @code{untrace} disables tracing for all functions.
 683
 684 @code{untrace} returns a list of the functions for which
 685 it disabled tracing.
 686
 687 @opencatbox{Categories:}
 688 @category{Debugging}
 689 @closecatbox
 690 @end deffn
 691