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
       interpreter   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
       normally 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
       interpreters.    A  safe  interpreter  is  a  slave  whose
       functions have been greatly restricted, so that it is safe
       to execute untrusted scripts without fear of them damaging
       other interpreters or the application's  environment.  For
       example,  all  IO channel creation commands and subprocess
       creation  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  (analogous  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
       containing a subset of its ancestors  in  the  interpreter
       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
       impossible 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   interpreter   created  in  an  application.   Both
       restrictions are motivated by safety concerns.


THE INTERP COMMAND
       The  interp  command  is  used  to  create,  delete,   and
       manipulate  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
              srcCmd if it was renamed).

       interp alias srcPath srcCmd {}
              Deletes  the  alias  for  srcCmd   in   the   slave
              interpreter  identified  by srcPath.  srcCmd refers
              to the name under which the alias was created;   if
              the  source  command  has been renamed, the renamed
              command 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
              creating  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 interpreter and command,  and  the
              arg arguments, if any, specify additional arguments
              to targetCmd which are prepended to  any  arguments
              specified  in  the invocation 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 command 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
              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
              information 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,
              eventually   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.
              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.  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
              arguments supplied in the  interpreter  denoted  by
              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
              variables in that and outer  call  frames.   Hidden
              commands  are  explained  in  more detail in HIDDEN
              COMMANDS, 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
              interpreter.  The command  has  no  effect  if  the
              interpreter  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
              accessible  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
              identified   by  path.  If  path  is  omitted,  the
              invoking interpreter is used.

       interp target path alias
              Returns  a   Tcl   list   describing   the   target
              interpreter  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
              target interpreter for the alias  is  the  invoking
              interpreter  then an empty list is returned. If the
              target  interpreter  for  the  alias  is  not   the
              invoking 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
              identified by srcPath.


SLAVE COMMAND
       For   each  slave  interpreter  created  with  the  interp
       command, a new  Tcl  command  is  created  in  the  master
       interpreter  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
              created (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
              srcCmd if it was renamed).

       slave alias srcCmd {}
              Deletes   the   alias   for  srcCmd  in  the  slave
              interpreter.  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
              master.   The  arg  arguments  will  be  passed  to
              targetCmd as additional arguments, prepended before
              any  arguments  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
              errorCode   variables,   if  an  error  occurs)  is
              returned to the invoking interpreter.

       slave expose hiddenName ?exposedCmdName?
              This command exposes the hidden command hiddenName,
              eventually   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  slave.   If  an  exposed
              command  with  the  targetted  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
              exposedCmdName, renaming it to the  hidden  command
              hiddenCmdName,  or keeping the same name if the the
              argument is not given, in  the  slave  interpreter.
              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.
              Commands  to  be hidden 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.   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
              substitutions 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
              otherwise.

       slave marktrusted
              Marks the slave interpreter as trusted. Can only be
              invoked by a trusted interpreter. This command does
              not   expose  any  hidden  commands  in  the  slave
              interpreter. 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
       environment.   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 carefully 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

       These commands can be recreated later as Tcl procedures or
       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
       recommends storing the PGP private key protection password
       in  the environment variable PGPPASS. Making this variable
       available  to  untrusted  code   executing   in   a   safe
       interpreter 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
       carried 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
       arguments  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  substitutions 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
       interpreters,  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
       interpreter 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
       interpreter; 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
       dangerous 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
       created  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
       hidden 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
       section on ALIAS INVOCATION for a more complete discussion
       of  this  topic.   To  help   avoid   this   problem,   no
       substitutions  or  evaluations are applied to arguments of
       interp invokehidden.

       Safe  interpreters  are  not  allowed  to  invoke   hidden
       commands  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
       manipulated by a trusted interpreter using  interp  expose
       and  interp hide. The interp expose command moves a hidden
       command 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
       commands  in  that  interpreter. Safe interpreters are not
       allowed to move commands between the  set  of  hidden  and
       exposed   commands,   in   either   themselves   or  their
       descendants.

       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
       implemented by Nathaniel Borenstein and Marshall Rose.


SEE ALSO
       load(n), safe(n), Tcl_CreateSlave(3)


KEYWORDS
       alias,  master  interpreter,   safe   interpreter,   slave
