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)
    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 (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.

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

`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()}))
    ## End(Not run)

[Package utils version 2.6.2 Index]