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