evalREX
Evaluating Expressions in Restricted Execution Mode
Description
Warning: evalREX is deprecated. It is included for compatibility with earlier
versions, and might be removed in a future release. It is not recommended
to use the evalREX function.
If you do use evalREX, it is recommended to use the doNotReturn flag.
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, doNotReturn=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.
|
doNotReturn |
a logical flag. If TRUE, evalREX evaluates the expression and
then exits without returning any value. Default is FALSE.
|
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.
Warning: It is possible for malicious code executed in evalREX to affect execution
after evalREX has returned. Use the doNotReturn flag to make evalREX
exit abruptly after evaluating the expression, preventing evalREX from returning
any value.
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).
The following shows a
non-exhaustive list of operations disallowed in restricted execution
mode.
- Calling evalREX itself.
- Performing any I/O to the file system or the internet.
- Loading new packages, except for the libraries included with Spotfire Enterprise Runtime for R (stats, terrUtils, and so on).
- Spawning new OS processes (calling 'system').
- Calling .Call, which is used to call Rapi code in CRAN packages.
- Calling .C or .Fortran.
- Calling into Java using the terrJava package (which allows executing
arbitrary Java methods).
- Calling any functions in the 'parallel' package (which uses
terrJava).
- Accessing any function environments in the stack above the call to
evalREX using sys.frame or parent.frame. This
prevents malicious code from installing functions or expressions that
could be executed after leaving restricted execution mode.
- Changing the variable lookup path by setting parent.env of
an environment, or reading or setting the environment of a closure.
- Defining S4 classes and methods using setClass or setMethod.
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
evalREX | returns the result of evaluating expr. |
getREX | returns 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. |
stopIfREX | if 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
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.