tcl7.6 User Commands - interp






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 mas-
     ter 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 vari-
     ables.  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 inter-
     preter or in another slave interpreter.  The only other con-
     nections  between interpreters are through environment vari-
     ables (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 com-
     mand)  is  no  longer  shared between interpreters. Explicit
     commands are provided to share files and to transfer  refer-
     ences 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  execute
     untrusted scripts without fear of them damaging other inter-
     preters or the application's environment. For  example,  all
     IO  channel  creation  commands and subprocess creation com-
     mands are removed from safe interpreters.  See  SAFE  INTER-
     PRETERS  below  for  more  information  on what features are
     present in a safe interpreter.  The alias mechanism  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  contain-
     ing  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 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 com-
          mand, 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 ele-
          ments 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 inter-
          preter.  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 inter-
          preter identified by the path ``a b''.  The slave  com-
          mand  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 issafe ?path?
          Returns 1 if the interpreter identified by  the  speci-
          fied 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 inter-
          preters  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  des-
          troyed.

     interp slaves ?path?
          Returns a Tcl list of the names of all the slave inter-
          preters  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 inter-
          preter 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 invok-
          ing  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 com-
          mands, 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 issafe
          Returns  1 if the slave interpreter is safe,  0  other-
          wise.



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  mas-
     ter.   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  inter-
     preter, the usual Tcl substitutions are performed when pars-
     ing 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  ``tar-
     getCmd 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  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 interpreter
     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 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 inter-
     preter which check their  arguments  carefully  and  provide
     restricted access to a safe subset of facilities.  For exam-
     ple, file creation might be allowed  in  a  particular  sub-
     directory  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       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 environ-
     ment variable. For example, the PGP manual recommends  stor-
     ing  the PGP private key protection password in the environ-
     ment 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 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 ALSO

     load(n), package(n) Tcl_CreateSlave(3)



KEYWORDS

     alias, master interpreter, safe  interpreter,  slave  inter-
     preter