traceback: Get and Print Call Stacks

tracebackR Documentation

Get and Print Call Stacks

Description

By default traceback() prints the call stack of the last uncaught error, i.e., the sequence of calls that lead to the error. This is useful when an error occurs with an unidentifiable error message. It can also be used to print the current stack or arbitrary lists of calls.

.traceback() now returns the above call stack (and traceback(x, *) can be regarded as convenience function for printing the result of .traceback(x)).

Usage

 traceback(x = NULL, max.lines = getOption("traceback.max.lines",
                                           getOption("deparse.max.lines", -1L)))
.traceback(x = NULL, max.lines = getOption("traceback.max.lines",
                                           getOption("deparse.max.lines", -1L)))

Arguments

x

NULL (default, meaning .Traceback), or an integer count of calls to skip in the current stack, or a list or pairlist of calls. See the details.

max.lines

a number, the maximum number of lines to be printed per call. The default is unlimited. Applies only when x is NULL, a list or a pairlist of calls, see the details.

Details

The default display is of the stack of the last uncaught error as stored as a list of calls in .Traceback, which traceback prints in a user-friendly format. The stack of calls always contains all function calls and all foreign function calls (such as .Call): if profiling is in progress it will include calls to some primitive functions. (Calls to builtins are included, but not to specials.)

Errors which are caught via try or tryCatch do not generate a traceback, so what is printed is the call sequence for the last uncaught error, and not necessarily for the last error.

If x is numeric, then the current stack is printed, skipping x entries at the top of the stack. For example, options(error = function() traceback(3)) will print the stack at the time of the error, skipping the call to traceback() and .traceback() and the error function that called it.

Otherwise, x is assumed to be a list or pairlist of calls or deparsed calls and will be displayed in the same way.

.traceback() and by extension traceback() may trigger deparsing of calls. This is an expensive operation for large calls so it may be advisable to set max.lines to a reasonable value when such calls are on the call stack.

Value

.traceback() returns the deparsed call stack deepest call first as a list or pairlist. The number of lines deparsed from the call can be limited via max.lines. Calls for which max.lines results in truncated output will gain a "truncated" attribute.

traceback() formats, prints, and returns the call stack produced by .traceback() invisibly.

Warning

It is undocumented where .Traceback is stored nor that it is visible, and this is subject to change. As of R 4.0.0 .Traceback contains the calls as language objects, whereas previously these calls were deparsed.

References

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

Examples

foo <- function(x) { print(1); bar(2) }
bar <- function(x) { x + a.variable.which.does.not.exist }
## Not run: 
foo(2) # gives a strange error
traceback()
## End(Not run)
## 2: bar(2)
## 1: foo(2)
bar
## Ah, this is the culprit ...

## This will print the stack trace at the time of the error.
options(error = function() traceback(3))