interp(n) Tcl Built-In Commands interp(n)_________________________________________________________________NAMEinterp - Create and manipulate Tcl interpreters
SYNOPSISinterp option ?arg arg ...?
_________________________________________________________________DESCRIPTION
This command makes it possible to create one or more new
Tcl interpreters that co-exist with the creating inter-
preter in the same application. The creating interpreter
is called the master and the new interpreter is called a
slave. A master can create any number of slaves, and each
slave can itself create additional slaves for which it is
master, resulting in a hierarchy of interpreters.
Each interpreter is independent from the others: it has
its own name space for commands, procedures, and global
variables. A master interpreter may create connections
between its slaves and itself using a mechanism called an
alias. An alias is a command in a slave interpreter
which, when invoked, causes a command to be invoked in its
master interpreter or in another slave interpreter. The
only other connections between interpreters are through
environment variables (the env variable), which are nor-
mally shared among all interpreters in the application.
Note that the name space for files (such as the names
returned by the open command) is no longer shared between
interpreters. Explicit commands are provided to share
files and to transfer references to open files from one
interpreter to another.
The interp command also provides support for safe inter-
preters. A safe interpreter is a slave whose functions
have been greatly restricted, so that it is safe to exe-
cute untrusted scripts without fear of them damaging other
interpreters or the application's environment. For exam-
ple, all IO channel creation commands and subprocess cre-
ation commands are removed from safe interpreters. See
SAFE INTERPRETERS below for more information on what fea-
tures are present in a safe interpreter. The alias mecha-
nism can be used for protected communication (analogous to
a kernel call) between a slave interpreter and its master.
A qualified interpreter name is a proper Tcl lists con-
taining a subset of its ancestors in the interpreter hier-
archy, terminated by the string naming the interpreter in
its immediate master. Interpreter names are relative to
the interpreter in which they are used. For example, if a
is a slave of the current interpreter and it has a slave
a1, which in turn has a slave a11, the qualified name of
a11 in a is the list {a1 a11}.
Tcl 7.5 1
interp(n) Tcl Built-In Commands interp(n)
The interp command, described below, accepts qualified
interpreter names as arguments; the interpreter in which
the command is being evaluated can always be referred to
as {} (the empty list or string). Note that it is impossi-
ble to refer to a master (ancestor) interpreter by name in
a slave interpreter except through aliases. Also, there is
no global name by which one can refer to the first inter-
preter created in an application. Both restrictions are
motivated by safety concerns.
The interp command is used to create, delete, and manipu-
late slave interpreters, and to share or transfer channels
between interpreters. It can have any of several forms,
depending on the option argument:
interp alias srcPath srcCmd
Returns a Tcl list whose elements are the targetCmd
and args associated with the alias named srcCmd
(all of these are the values specified when the
alias was created; it is possible that the actual
source command in the slave is different from src-
Cmd if it was renamed).
interp alias srcPath srcCmd {}
Deletes the alias for srcCmd in the slave inter-
preter identified by srcPath. srcCmd refers to the
name under which the alias was created; if the
source command has been renamed, the renamed com-
mand will be deleted.
interp alias srcPath srcCmd targetPath targetCmd ?arg arg
...?
This command creates an alias between one slave and
another (see the alias slave command below for cre-
ating aliases between a slave and its master). In
this command, either of the slave interpreters may
be anywhere in the hierarchy of interpreters under
the interpreter invoking the command. SrcPath and
srcCmd identify the source of the alias. SrcPath
is a Tcl list whose elements select a particular
interpreter. For example, ``a b'' identifies an
interpreter b, which is a slave of interpreter a,
which is a slave of the invoking interpreter. An
empty list specifies the interpreter invoking the
command. srcCmd gives the name of a new command,
which will be created in the source interpreter.
TargetPath and targetCmd specify a target inter-
preter and command, and the arg arguments, if any,
specify additional arguments to targetCmd which are
prepended to any arguments specified in the invoca-
tion of srcCmd. TargetCmd may be undefined at the
time of this call, or it may already exist; it is
not created by this command. The alias arranges
for the given target command to be invoked in the
Tcl 7.5 2
interp(n) Tcl Built-In Commands interp(n)
target interpreter whenever the given source com-
mand is invoked in the source interpreter. See
ALIAS INVOCATION below for more details.
interp aliases ?path?
This command returns a Tcl list of the names of all
the source commands for aliases defined in the
interpreter identified by path.
interp create ?-safe? ?--? ?path?
Creates a slave interpreter identified by path and
a new command, called a slave command. The name of
the slave command is the last component of path.
The new slave interpreter and the slave command are
created in the interpreter identified by the path
obtained by removing the last component from path.
For example, if path is ``a b c'' then a new slave
interpreter and slave command named ``c'' are cre-
ated in the interpreter identified by the path ``a
b''. The slave command may be used to manipulate
the new interpreter as described below. If path is
omitted, Tcl creates a unique name of the form
interpx, where x is an integer, and uses it for the
interpreter and the slave command. If the -safe
switch is specified (or if the master interpreter
is a safe interpreter), the new slave interpreter
will be created as a safe interpreter with limited
functionality; otherwise the slave will include the
full set of Tcl built-in commands and variables.
The -- switch can be used to mark the end of
switches; it may be needed if path is an unusual
value such as -safe. The result of the command is
the name of the new interpreter. The name of a
slave interpreter must be unique among all the
slaves for its master; an error occurs if a slave
interpreter by the given name already exists in
this master.
interp delete ?path ...?
Deletes zero or more interpreters given by the
optional path arguments, and for each interpreter,
it also deletes its slaves. The command also
deletes the slave command for each interpreter
deleted. For each path argument, if no interpreter
by that name exists, the command raises an error.
interp eval path arg ?arg ...?
This command concatenates all of the arg arguments
in the same fashion as the concat command, then
evaluates the resulting string as a Tcl script in
the slave interpreter identified by path. The
result of this evaluation (including error informa-
tion such as the errorInfo and errorCode variables,
if an error occurs) is returned to the invoking
Tcl 7.5 3
interp(n) Tcl Built-In Commands interp(n)
interpreter.
interp exists path
Returns 1 if a slave interpreter by the specified
path exists in this master, 0 otherwise. If path is
omitted, the invoking interpreter is used.
interp issafe ?path?
Returns 1 if the interpreter identified by the
specified path is safe, 0 otherwise.
interp share srcPath channelId destPath
Causes the IO channel identified by channelId to
become shared between the interpreter identified by
srcPath and the interpreter identified by destPath.
Both interpreters have the same permissions on the
IO channel. Both interpreters must close it to
close the underlying IO channel; IO channels acces-
sible in an interpreter are automatically closed
when an interpreter is destroyed.
interp slaves ?path?
Returns a Tcl list of the names of all the slave
interpreters associated with the interpreter iden-
tified by path. If path is omitted, the invoking
interpreter is used.
interp target path alias
Returns a Tcl list describing the target inter-
preter for an alias. The alias is specified with an
interpreter path and source command name, just as
in interp alias above. The name of the target
interpreter is returned as an interpreter path,
relative to the invoking interpreter. If the tar-
get interpreter for the alias is the invoking
interpreter then an empty list is returned. If the
target interpreter for the alias is not the invok-
ing interpreter or one of its descendants then an
error is generated. The target command does not
have to be defined at the time of this invocation.
interp transfer srcPath channelId destPath
Causes the IO channel identified by channelId to
become available in the interpreter identified by
destPath and unavailable in the interpreter identi-
fied by srcPath.
SLAVE COMMAND
For each slave interpreter created with the interp com-
mand, a new Tcl command is created in the master inter-
preter with the same name as the new interpreter. This
command may be used to invoke various operations on the
interpreter. It has the following general form:
slave command ?arg arg ...?
Tcl 7.5 4
interp(n) Tcl Built-In Commands interp(n)
Slave is the name of the interpreter, and command and the
args determine the exact behavior of the command. The
valid forms of this command are:
slave aliases
Returns a Tcl list whose elements are the names of
all the aliases in slave. The names returned are
the srcCmd values used when the aliases were cre-
ated (which may not be the same as the current
names of the commands, if they have been renamed).
slave alias srcCmd
Returns a Tcl list whose elements are the targetCmd
and args associated with the alias named srcCmd
(all of these are the values specified when the
alias was created; it is possible that the actual
source command in the slave is different from src-
Cmd if it was renamed).
slave alias srcCmd {}
Deletes the alias for srcCmd in the slave inter-
preter. srcCmd refers to the name under which the
alias was created; if the source command has been
renamed, the renamed command will be deleted.
slave alias srcCmd targetCmd ?arg ..?
Creates an alias such that whenever srcCmd is
invoked in slave, targetCmd is invoked in the mas-
ter. The arg arguments will be passed to targetCmd
as additional arguments, prepended before any argu-
ments passed in the invocation of srcCmd. See
ALIAS INVOCATION below for details.
slave eval arg ?arg ..?
This command concatenates all of the arg arguments
in the same fashion as the concat command, then
evaluates the resulting string as a Tcl script in
slave. The result of this evaluation (including
error information such as the errorInfo and error-
Code variables, if an error occurs) is returned to
the invoking interpreter.
slave issafe
Returns 1 if the slave interpreter is safe, 0 oth-
erwise.
ALIAS INVOCATION
The alias mechanism has been carefully designed so that it
can be used safely when an untrusted script is executing
in a safe slave and the target of the alias is a trusted
master. The most important thing in guaranteeing safety
is to ensure that information passed from the slave to the
master is never evaluated or substituted in the master;
Tcl 7.5 5
interp(n) Tcl Built-In Commands interp(n)
if this were to occur, it would enable an evil script in
the slave to invoke arbitrary functions in the master,
which would compromise security.
When the source for an alias is invoked in the slave
interpreter, the usual Tcl substitutions are performed
when parsing that command. These substitutions are car-
ried out in the source interpreter just as they would be
for any other command invoked in that interpreter. The
command procedure for the source command takes its argu-
ments and merges them with the targetCmd and args for the
alias to create a new array of arguments. If the words of
srcCmd were ``srcCmd arg1 arg2 ... argN'', the new set of
words will be ``targetCmd arg arg ... arg arg1 arg2 ...
argN'', where targetCmd and args are the values supplied
when the alias was created. TargetCmd is then used to
locate a command procedure in the target interpreter, and
that command procedure is invoked with the new set of
arguments. An error occurs if there is no command named
targetCmd in the target interpreter. No additional sub-
stitutions are performed on the words: the target command
procedure is invoked directly, without going through the
normal Tcl evaluation mechanism. Substitutions are thus
performed on each word exactly once: targetCmd and args
were substituted when parsing the command that created the
alias, and arg1 - argN are substituted when the alias's
source command is parsed in the source interpreter.
When writing the targetCmds for aliases in safe inter-
preters, it is very important that the arguments to that
command never be evaluated or substituted, since this
would provide an escape mechanism whereby the slave inter-
preter could execute arbitrary code in the master. This
in turn would compromise the security of the system.
SAFE INTERPRETERS
A safe interpreter is one with restricted functionality,
so that is safe to execute an arbitrary script from your
worst enemy without fear of that script damaging the
enclosing application or the rest of your computing envi-
ronment. In order to make an interpreter safe, certain
commands and variables are removed from the interpreter.
For example, commands to create files on disk are removed,
and the exec command is removed, since it could be used to
cause damage through subprocesses. Limited access to
these facilities can be provided, by creating aliases to
the master interpreter which check their arguments care-
fully and provide restricted access to a safe subset of
facilities. For example, file creation might be allowed
in a particular subdirectory and subprocess invocation
might be allowed for a carefully selected and fixed set of
programs.
Tcl 7.5 6
interp(n) Tcl Built-In Commands interp(n)
A safe interpreter is created by specifying the -safe
switch to the interp create command. Furthermore, any
slave created by a safe interpreter will also be safe.
A safe interpreter is created with exactly the following
set of built-in commands:
after append array break
case catch clock close
concat continue eof error
eval expr fblocked fileevent
flush for foreach format
gets global history if
incr info interp join
lappend lindex linsert list
llength lower lrange lreplace
lsearch lsort package pid
proc puts read rename
return scan seek set
split string subst switch
tell trace unset update
uplevel upvar vwait while
All commands not on this list are removed by interp create
when it creates a safe interpreter. These commands can be
recreated later as Tcl procedures or aliases.
In addition, the env variable is not present in a safe
interpreter, so it cannot share environment variables with
other interpreters. The env variable poses a security
risk, because users can store sensitive information in an
environment variable. For example, the PGP manual recom-
mends storing the PGP private key protection password in
the environment variable PGPPASS. Making this variable
available to untrusted code executing in a safe inter-
preter would incur a security risk.
If extensions are loaded into a safe interpreter, they may
also restrict their own functionality to eliminate unsafe
commands. For a discussion of management of extensions for
safety see the manual entries for the package and load Tcl
commands.
CREDITS
This mechanism is based on the Safe-Tcl prototype imple-
mented by Nathaniel Borenstein and Marshall Rose.
SEE ALSOload(n), package(n)Tcl_CreateSlave(3)KEYWORDS
alias, master interpreter, safe interpreter, slave
Tcl 7.5 7
interp(n) Tcl Built-In Commands interp(n)
interpreter
Tcl 7.5 8
