debugger                package:base                R Documentation

_P_o_s_t-_M_o_r_t_e_m _D_e_b_u_g_g_i_n_g

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

  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'.

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     None.

_N_o_t_e:

     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.

_A_u_t_h_o_r(_s):

     B. D. Ripley

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

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

