debugger                package:base                R Documentation

Post-Mortem Debugging

Description:

     Functions to dump the evaluation environments (frames) and to
     examine dumped frames.

Usage:

     dump.frames(dumpto = "last.dump", to.file = FALSE)
     debugger(dump = last.dump)

Arguments:

  dumpto: a character string. The name of the object or file to dump
          to.

 to.file: logical. Should the dump be to an R object or to a file?

    dump: An R dump object created by `dump.frames'.

Details:

     To use post-mortem debugging, set the option `error' to be a call
     to `dump.frames'.  By default this dumps to an R object
     `"last.dump"' in the workspace, but it can be set to dump to a
     file (as dump of the object produced by a call to `save'). The
     dumped object contain the call stack, the active environments and
     the last error message as returned by `geterrmessage'.

     When dumping to file, `dumpto' gives the name of the dumped object
     and the file name has `.rda' appended.

     A dump object of class `"dump.frames"' can be examined by calling
     `debugger'. This will give the error message and a list of
     environments from which to select repeatedly. When an environment
     is selected, it is copied and the `browser' called from within the
     copy.

     If `dump.frames' is installed as the error handler, execution will
     continue even in non-interactive sessions. See the examples for
     how to dump and then quit.

Value:

     None.

Note:

     Functions such as `sys.parent' and `environment' applied to
     closures will not work correctly inside `debugger'.

     Of course post-mortem debugging will not work if R is too damaged
     to produce and save the dump, for example if it has run out of
     workspace.

Author(s):

     B. D. Ripley

See Also:

     `options' for setting `error' options.

Examples:

     options(error=quote(dump.frames("testdump", TRUE)))

     f <- function() {
         g <- function() stop("test dump.frames")
         g()
     }
     f()   # will generate a dump on file "testdump.rda"
     options(error=NULL)

     ## possibly in another R session
     load("testdump.rda")
     debugger(testdump)
     Available environments had calls:
     1: f()
     2: g()
     3: stop("test dump.frames")

     Enter an environment number, or 0 to exit
     Selection: 1
     Browsing in the environment with call:
     f()
     Called from: debugger.look(ind)
     Browse[1]> ls()
     [1] "g"
     Browse[1]> g
     function() stop("test dump.frames")
     <environment: 759818>
     Browse[1]> 
     Available environments had calls:
     1: f()
     2: g()
     3: stop("test dump.frames")

     Enter an environment number, or 0 to exit
     Selection: 0

     ## A possible setting for non-interactive sessions
     options(error=quote({dump.frames(to.file=TRUE); q()}))

