NAME
interp - Create and manipulate Tcl interpreters
SYNOPSIS
interp 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 made inaccessible to safe interpreters. |
See SAFE INTERPRETERS below for more information on what |
features are present in a safe interpreter. The dangerous |
functionality is not removed from the safe interpreter; |
instead, it is hidden, so that only trusted interpreters |
can obtain access to it. For a detailed explanation of |
hidden commands, see HIDDEN COMMANDS, below. The alias |
mechanism can be used for protected communication (analo |
gous to a kernel call) between a slave interpreter and its |
master. See ALIAS INVOCATION, below, for more details on |
how the alias mechanism works.
A qualified interpreter name is a proper Tcl lists
hierarchy, 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.
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 |
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
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
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 created
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 inter
preter 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 func
tionality; 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
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
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 expose path hiddenName |
?exposedCmdName? | |
Makes the hidden command hiddenName exposed, even |
tually bringing it back under a new exposedCmdName |
name (this name is currently accepted only if it is |
a valid global name space name without any ::), in |
the interpreter denoted by path. If an exposed |
command with the targetted name already exists, |
this command fails. Hidden commands are explained |
in more detail in HIDDEN COMMANDS, below. |
interp hide path exposedCmdName |
?hiddenCmdName? | |
Makes the exposed command exposedCmdName hidden, |
renaming it to the hidden command hiddenCmdName, or |
keeping the same name if hiddenCmdName is not |
given, in the interpreter denoted by path. If a |
hidden command with the targetted name already |
exists, this command fails. Currently both |
exposedCmdName and hiddenCmdName can not contain |
namespace qualifiers, or an error is raised. Com |
mands to be hidden by interp hide are looked up in |
the global namespace even if the current namespace |
is not the global one. This prevents slaves from |
fooling a master interpreter into hiding the wrong |
command, by making the current namespace be differ |
ent from the global one. Hidden commands are |
explained in more detail in HIDDEN COMMANDS, below. |
interp hidden |
path ||
Returns a list of the names of all hidden commands |
in the interpreter identified by path. |
interp invokehidden path ?-global? hiddenCmdName ?arg |
...? | |
Invokes the hidden command hiddenCmdName with the |
path. No substitutions or evaluation are applied to |
the arguments. If the -global flag is present, the |
hidden command is invoked at the global level in |
the target interpreter; otherwise it is invoked at |
the current call frame and can access local vari |
ables in that and outer call frames. Hidden com |
mands are explained in more detail in HIDDEN COM |
MANDS, below.
interp issafe ?path?
Returns 1 if the interpreter identified by the
specified path is safe, 0 otherwise.
interp marktrusted |
path | |
Marks the interpreter identified by path as |
trusted. Does not expose the hidden commands. This |
command can only be invoked from a trusted inter |
preter. The command has no effect if the inter |
preter identified by path is already trusted.
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
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 ...?
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.
?exposedCmdName? | |
This command exposes the hidden command hiddenName, |
eventually bringing it back under a new exposedCmd |
Name name (this name is currently accepted only if |
it is a valid global name space name without any |
::), in slave. If an exposed command with the tar |
getted name already exists, this command fails. |
For more details on hidden commands, see HIDDEN |
COMMANDS, below. |
slave hide exposedCmdName |
?hiddenCmdName? | |
This command hides the exposed command exposedCmd |
Name, renaming it to the hidden command hiddenCmd |
Name, or keeping the same name if the the argument |
is not given, in the slave interpreter. If a hid |
den command with the targetted name already exists, |
this command fails. Currently both exposedCmdName |
and hiddenCmdName can not contain namespace quali |
fiers, or an error is raised. Commands to be hid |
den are looked up in the global namespace even if |
the current namespace is not the global one. This |
prevents slaves from fooling a master interpreter |
into hiding the wrong command, by making the cur |
rent namespace be different from the global one. |
For more details on hidden commands, see HIDDEN |
COMMANDS, below. |
slave |
hidden ||
Returns a list of the names of all hidden commands |
in slave. |
slave invokehidden ?-global hiddenName ?arg |
..? | |
This command invokes the hidden command hiddenName |
with the supplied arguments, in slave. No substitu |
tions or evaluations are applied to the arguments. |
If the -global flag is given, the command is |
invoked at the global level in the slave; otherwise |
it is invoked at the current call frame and can |
access local variables in that or outer call |
frames. For more details on hidden commands, see |
HIDDEN COMMANDS, below.
slave issafe
Returns 1 if the slave interpreter is safe, 0 oth
erwise.
slave |
marktrusted ||
Marks the slave interpreter as trusted. Can only be |
invoked by a trusted interpreter. This command does |
preter. The command has no effect if the slave is |
already trusted.
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.
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 binary
break case catch clock
close concat continue eof
error eval expr fblocked
fcopy fileevent flush for
foreach format gets global
history if incr info
interp join lappend lindex
linsert list llength lrange
lreplace lsearch lsort namespace
package pid proc puts
read regexp regsub rename
return scan seek set
split string subst switch
tell trace unset update
uplevel upvar variable vwait
while
The following commands are hidden by interp create when it |
creates a safe interpreter: |
cd exec exit fconfigure |
file glob load open |
pwd socket source vwait |
aliases, or re-exposed by interp expose.
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 Safe-Tcl and the load
Tcl command.
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;
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.
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.
HIDDEN COMMANDS |
Safe interpreters greatly restrict the functionality |
available to Tcl programs executing within them. Allowing |
the untrusted Tcl program to have direct access to this |
functionality is unsafe, because it can be used for a |
variety of attacks on the environment. However, there are |
times when there is a legitimate need to use the dangerous |
functionality in the context of the safe interpreter. For |
example, sometimes a program must be sourced into the |
interpreter. Another example is Tk, where windows are |
bound to the hierarchy of windows for a specific inter |
preter; some potentially dangerous functions, e.g. window |
management, must be performed on these windows within the |
interpreter context. |
The interp command provides a solution to this problem in |
the form of hidden commands. Instead of removing the dan |
gerous commands entirely from a safe interpreter, these |
commands are hidden so they become unavailable to Tcl |
scripts executing in the interpreter. However, such hidden |
commands can be invoked by any trusted ancestor of the |
safe interpreter, in the context of the safe interpreter, |
using interp invoke. Hidden commands and exposed commands |
reside in separate name spaces. It is possible to define a |
hidden command and an exposed command by the same name |
within one interpreter. |
Hidden commands in a slave interpreter can be invoked in |
the body of procedures called in the master during alias |
invocation. For example, an alias for source could be cre |
ated in a slave interpreter. When it is invoked in the |
slave interpreter, a procedure is called in the master |
interpreter to check that the operation is allowable (e.g. |
it asks to source a file that the slave interpreter is |
allowed to access). The procedure then it invokes the hid |
den source command in the slave interpreter to actually |
source in the contents of the file. Note that two commands |
named source exist in the slave interpreter: the alias, |
and the hidden command. |
Because a master interpreter may invoke a hidden command |
as part of handling an alias invocation, great care must |
be taken to avoid evaluating any arguments passed in |
through the alias invocation. Otherwise, malicious slave |
interpreters could cause a trusted master interpreter to |
execute dangerous commands on their behalf. See the |
of this topic. To help avoid this problem, no substitu |
tions or evaluations are applied to arguments of interp |
invokehidden. |
Safe interpreters are not allowed to invoke hidden com |
mands in themselves or in their descendants. This prevents |
safe slaves from gaining access to hidden functionality in |
themselves or their descendants. |
The set of hidden commands in an interpreter can be manip |
ulated by a trusted interpreter using interp expose and |
interp hide. The interp expose command moves a hidden com |
mand to the set of exposed commands in the interpreter |
identified by path, potentially renaming the command in |
the process. If an exposed command by the targetted name |
already exists, the operation fails. Similarly, interp |
hide moves an exposed command to the set of hidden com |
mands in that interpreter. Safe interpreters are not |
allowed to move commands between the set of hidden and |
exposed commands, in either themselves or their descen |
dants. |
Currently, the names of hidden commands cannot contain |
namespace qualifiers, and you must first rename a command |
in a namespace to the global namespace before you can hide |
it. Commands to be hidden by interp hide are looked up in |
the global namespace even if the current namespace is not |
the global one. This prevents slaves from fooling a master |
interpreter into hiding the wrong command, by making the |
current namespace be different from the global one.
CREDITS
This mechanism is based on the Safe-Tcl prototype imple
mented by Nathaniel Borenstein and Marshall Rose.
SEE ALSO
load(n), safe(n), Tcl_CreateSlave(3)
KEYWORDS
alias, master interpreter, safe interpreter, slave inter
preter
Man(1) output converted with
man2html