evalREX
Evaluating Expressions in Restricted Execution Mode

Description

evalREX evaluates an expression in "Restricted Execution" mode, where attempting to execute certain operations defined as restricted (such as I/O) generates an error. The other functions are related to evalREX.

Usage

evalREX(expr, envir=NULL, restoreEnv=FALSE, restoreOptions=FALSE, trace=FALSE)
getREX()
stopIfREX(msg)

Arguments

expr any expression or object to evaluate in restricted execution mode. Note that this argument is evaluated like the first argument to eval, before evaluating the result in restricted execution mode. Thus, normally this argument is given as a call to the quote function, wrapping an expression.
envir the environment in which to do the evaluation in restricted execution mode. By default, it is the current environment, where the function is called.
restoreEnv specifies how to handle the envir on exit. Can be one of the following.
FALSE On exit, do not restore envir.
TRUE On exit, restore envir.
An environment On exit, save the contents of envir in restoreEnv, and then restore envir).
restoreOptions a logical value. If TRUE, then evalREX restores the options upon exit. If FALSE (the default), then evalREX leaves the options as they are.
trace a logical value. If TRUE, then executing a "restricted" operation prints a message to stderr and continues, rather than generating an error. The default is FALSE.
msg a character string.

Details

The function evalREX evaluates an expression in restricted execution mode, where attempting to execute certain restricted operations generates an error.
The function getREX returns whether restricted execution mode and tracing mode are enabled.
The function stopIfREX is similar to stop, except that it checks whether restricted execution mode is enabled, and only generates an error if it is enabled (and tracing mode is not enabled).
Restricted execution mode allows executing arbitrary scripts without worrying that the script could do malicious things, such as deleting files or uploading confidential data to a server over the internet. evalREX is fairly conservative, preventing many operations, while still allowing some useful exceptions. The following shows a non-exhaustive list of operations disallowed in restricted execution mode.
It is possible for malicious code to set functions or expressions in the global environment or the options list. You can use the restoreEnv and restoreOptions arguments of evalREX to automatically restore the execution environment or options when evalREX exits normally, or because of an error. Setting restoreEnv to another empty environment copies the variables in envir to this environment before restoring the original contents of envir.
Warning: A common mistake when calling evalREX is to pass it an expression not wrapped in quote. In this case, evalREX evaluates its expr argument outside of the restricted expression mode, and then evaluates the result in restricted expression mode. Thus, evalREX(dir()) evaluates dir(), producing a character vector, and then evaluates the result in restricted mode, which succeeds.
Value
evalREXreturns the result of evaluating expr.
getREXreturns a logical value, which is TRUE if it is executed with restricted execution mode enabled; otherwise, it is FALSE. This value has an attribute "trace", whose value is TRUE if restricted execution mode is enabled, and if tracing is enabled.
stopIfREXif stopIfREX is executed when restricted execution mode is disabled, or if restricted execution mode is enabled with tracing enabled, then stopIfREX returns NULL. Otherwise, stopIfREX generates an error, so it does not have a return value.
See Also
eval, quote, stop.
Examples
evalREX(quote(1:10)) ## returns the vector without an error
evalREX(quote(dir())) ## gives an error, because dir() is restricted
evalREX(dir())
  ## this is a common mistake: this executes dir(),
  ## and passes the result vector to evalREX,
  ## which just returns this result.

evalREX(quote(dir()), trace=TRUE) ## prints "evalREX trace: restricted call to Native[dir]...", ## and evaluates it

getREX() ## structure(FALSE, trace=FALSE) evalREX(quote(getREX())) ## structure(TRUE, trace=FALSE)

stopIfREX("foo") ## no error evalREX(quote(stopIfREX("foo"))) ## error evalREX(quote(stopIfREX("foo")), trace=TRUE) ## prints "evalREX trace:...", but no error.

Package terrUtils version 6.1.1-7
Package Index