R: Post-Mortem Debugging

debugger {utils} | 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,
                include.GlobalEnv = 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?
`include.GlobalEnv` | logical indicating if a copy of the `.GlobalEnv` environment should be included in addition to the `sys.frames()`. Will be particularly useful when used in a batch job.
`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 (a 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. Note that not all the information in the original frame will be available, e.g. promises which have not yet been evaluated and the contents of any `...` argument.

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

Invisible `NULL`.

### Note

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

If the error occurred when computing the default value of a formal argument the debugger will report “recursive default argument reference” when trying to examine that environment.

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.

### References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

### See Also

`browser` for the actions available at the `Browse` prompt.

`options` for setting `error` options; `recover` is an interactive debugger working similarly to `debugger` but directly after the error occurs.

### Examples

    ## Not run:
    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(status = 1)}))

    ## End(Not run)

[Package utils version 3.5.1 Index]