| % File src/library/utils/man/debugger.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2016 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{debugger} |
| \alias{debugger} |
| \alias{dump.frames} |
| \title{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{ |
| \item{dumpto}{a character string. The name of the object or file to |
| dump to.} |
| \item{to.file}{logical. Should the dump be to an \R object or to a |
| file?} |
| \item{include.GlobalEnv}{logical indicating if a \emph{copy} of the |
| \code{\link{.GlobalEnv}} environment should be included in addition |
| to the \code{\link{sys.frames}()}. Will be particularly useful when |
| used in a batch job.} |
| \item{dump}{an \R dump object created by \code{dump.frames}.} |
| } |
| \details{ |
| To use post-mortem debugging, set the option \code{error} to be a call |
| to \code{dump.frames}. By default this dumps to an \R object |
| \code{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 \code{\link{save}}). |
| The dumped object contain the call stack, the active environments and |
| the last error message as returned by \code{\link{geterrmessage}}. |
| |
| When dumping to file, \code{dumpto} gives the name of the dumped |
| object and the file name has \file{.rda} appended. |
| |
| A dump object of class \code{"dump.frames"} can be examined by calling |
| \code{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 \code{\link{browser}} called from |
| within the copy. Note that not all the information in the original |
| frame will be available, e.g.\sspace{}promises which have not yet been |
| evaluated and the contents of any \code{\dots} argument. |
| |
| If \code{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 \code{NULL}. |
| } |
| \note{ |
| Functions such as \code{\link{sys.parent}} and |
| \code{\link{environment}} applied to closures will not work correctly |
| inside \code{debugger}. |
| |
| If the error occurred when computing the default value of a formal |
| argument the debugger will report \dQuote{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) |
| \emph{The New S Language}. |
| Wadsworth & Brooks/Cole. |
| } |
| \seealso{ |
| \code{\link{browser}} for the actions available at the \code{Browse} |
| prompt. |
| |
| \code{\link{options}} for setting \code{error} options; |
| \code{\link{recover}} is an interactive debugger working similarly to |
| \code{debugger} but directly after the error occurs. |
| } |
| \examples{ |
| \dontrun{ |
| 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)})) |
| }} |
| \keyword{utilities} |
| \keyword{error} |