interp(3tcl)


NAME

   interp - Create and manipulate Tcl interpreters

SYNOPSIS

   interp subcommand ?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, and by resource limit exceeded callbacks.  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 subcommand argument:

   interp alias srcPath srcToken
          Returns  a  Tcl  list  whose elements are the targetCmd and args
          associated with the alias represented by srcToken (this  is  the
          value  returned  when the alias was created; it is possible that
          the name of the source command in the slave  is  different  from
          srcToken).

   interp alias srcPath srcToken {}
          Deletes   the  alias  for  srcToken  in  the  slave  interpreter
          identified by srcPath.  srcToken refers to  the  value  returned
          when  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.  The
          command returns a token that  uniquely  identifies  the  command
          created  srcCmd,  even if the command is renamed afterwards. The
          token may but does not have to be equal to srcCmd.

   interp aliases ?path?
          This command returns a Tcl list of the tokens of all the  source
          commands  for  aliases  defined in the interpreter identified by
          path. The tokens correspond to  the  values  returned  when  the
          aliases  were  created (which may not be the same as the current
          names of the commands).

   interp bgerror path ?cmdPrefix?
          This command either gets or sets the  current  background  error 
          handler  for the interpreter identified by path. If cmdPrefix is 
          absent, the current background error handler is returned, and if 
          it  is  present,  it  is a list of words (of minimum length one) 
          that describes what to set the  interpreter's  background  error 
          to. See the BACKGROUND ERROR HANDLING section for more details.

   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.
          The initial recursion limit of the slave interpreter is  set  to
          the current recursion limit of its parent interpreter.

   interp debug path ?-frame ?bool??
          Controls  whether  frame-level  stack information is captured in
          the slave interpreter identified by path.  If no  arguments  are
          given,  option  and  current setting are returned.  If -frame is
          given, the debug setting is set to the given boolean if provided
          and  the  current  setting  is  returned.  This only effects the
          output of info frame, in that exact frame-level information  for
          command  invocation  at the bytecode level is only captured with
          this setting on.

          For example, with code like

                 proc mycontrol {... script} {
                   ...
                   uplevel 1 $script
                   ...
                 }

                 proc dosomething {...} {
                   ...
                   mycontrol {
                     somecode
                   }
                 }

          the standard setting will provide a relative line number for the
          command  somecode  and  the relevant frame will be of type eval.
          With frame-debug active on the other hand the  tracking  extends
          so  far  that  the system will be able to determine the file and
          absolute line number of this command, and return a frame of type
          source.  This  more  exact  information  is paid for with slower
          execution of all commands.

   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  all return
          options, such as -errorinfo and -errorcode  information,  if  an
          error  occurs)  is  returned  to the invoking interpreter.  Note
          that the script will be executed in the  current  context  stack
          frame   of   the   path   interpreter;   this  is  so  that  the
          implementations (in a master interpreter) of aliases in a  slave
          interpreter  can  execute  scripts  in  the  slave that find out
          information about the slave's current state and stack frame.

   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 targeted  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 targeted 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 ?-option ...? 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.  Three  -options  are
          supported,  all of which start with -: -namespace (which takes a
          single argument afterwards, nsName), -global, and  --.   If  the
          -namespace flag is present, the hidden command is invoked in the
          namespace called nsName  in  the  target  interpreter.   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.  The --  flag  allows  the  hiddenCmdName
          argument  to  start  with  a  "-"  character,  and  is otherwise
          unnecessary.  If both  the  -namespace  and  -global  flags  are
          present,  the  -namespace flag is ignored.  Note that the hidden
          command will be executed (by default)  in  the  current  context
          stack  frame  of  the  path  interpreter.   Hidden  commands are
          explained in more detail in HIDDEN COMMANDS, below.

   interp limit path limitType ?-option? ?value ...?
          Sets up,  manipulates  and  queries  the  configuration  of  the 
          resource  limit  limitType  for the interpreter denoted by path. 
          If no -option is specified, return the current configuration  of 
          the limit.  If -option is the sole argument, return the value of 
          that option.  Otherwise, a list of -option/value argument  pairs 
          must  supplied.  See  RESOURCE  LIMITS below for a more detailed 
          explanation of what limits and options are supported.

   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 recursionlimit path ?newlimit?
          Returns the maximum allowable nesting depth for the  interpreter
          specified  by  path.   If newlimit is specified, the interpreter
          recursion limit will  be  set  so  that  nesting  of  more  than
          newlimit  calls  to  Tcl_Eval()  and  related procedures in that
          interpreter will return an error.  The newlimit  value  is  also
          returned.  The newlimit value must be a positive integer between
          1 and the maximum value of a non-long integer on the platform.

          The command sets the maximum size of the Tcl call stack only. It
          cannot  by  itself  prevent stack overflows on the C stack being
          used by the application. If your machine has a limit on the size
          of  the C stack, you may get stack overflows before reaching the
          limit set by the command. If this happens, see  if  there  is  a
          mechanism  in your system for increasing the maximum size of the
          C stack.

   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  tokens  of  all  the
          aliases  in slave.  The tokens correspond to the values returned
          when the aliases were created (which may not be the same as  the
          current names of the commands).

   slave alias srcToken
          Returns  a  Tcl  list  whose elements are the targetCmd and args
          associated with the alias represented by srcToken (this  is  the
          value  returned  when the alias was created; it is possible that
          the actual  source  command  in  the  slave  is  different  from
          srcToken).

   slave alias srcToken {}
          Deletes  the  alias  for  srcToken  in  the  slave  interpreter.
          srcToken refers  to  the  value  returned  when  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.  The command returns a token  that
          uniquely  identifies  the  command  created  srcCmd, even if the
          command is renamed afterwards. The token may but does  not  have
          to be equal to srcCmd.

   slave bgerror ?cmdPrefix?
          This  command  either  gets or sets the current background error 
          handler for the slave interpreter. If cmdPrefix is  absent,  the 
          current  background  error  handler  is  returned,  and if it is 
          present, it is a list of words  (of  minimum  length  one)  that 
          describes what to set the interpreter's background error to. See 
          the BACKGROUND ERROR HANDLING section for more 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 all return options, such as -errorinfo and -errorcode
          information, if an error occurs) is  returned  to  the  invoking
          interpreter.   Note  that  the  script  will  be executed in the
          current context stack frame  of  slave;  this  is  so  that  the
          implementations  (in a master interpreter) of aliases in a slave
          interpreter can execute scripts  in  the  slave  that  find  out
          information about the slave's current state and stack frame.

   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
          targeted  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 argument is not given, in the slave  interpreter.   If  a
          hidden  command  with  the  targeted  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 ?-option ...? hiddenName ?arg ..?
          This  command  invokes  the  hidden  command hiddenName with the
          supplied arguments, in slave. No  substitutions  or  evaluations
          are  applied to the arguments. Three -options are supported, all
          of which start with -: -namespace (which takes a single argument
          afterwards, nsName), -global, and --.  If the -namespace flag is
          given, the hidden command is invoked in the specified  namespace
          in  the  slave.   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.   The  --  flag  allows   the
          hiddenCmdName  argument  to  start  with a "-" character, and is
          otherwise unnecessary.  If both the -namespace and -global flags
          are given, the -namespace flag is ignored.  Note that the hidden
          command will be executed (by default)  in  the  current  context
          stack  frame of slave.  For more details on hidden commands, see
          HIDDEN COMMANDS, below.

   slave issafe
          Returns  1 if the slave interpreter is safe, 0 otherwise.

   slave limit limitType ?-option? ?value ...?
          Sets up,  manipulates  and  queries  the  configuration  of  the 
          resource  limit  limitType  for  the  slave  interpreter.  If no 
          -option is specified, return the current  configuration  of  the 
          limit.   If  -option  is  the sole argument, return the value of 
          that option.  Otherwise, a list of -option/value argument  pairs 
          must  supplied.  See  RESOURCE  LIMITS below for a more detailed 
          explanation of what limits and options are supported.

   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.

   slave recursionlimit ?newlimit?
          Returns  the  maximum  allowable  nesting  depth  for  the slave
          interpreter.  If newlimit is specified, the recursion  limit  in
          slave will be set so that nesting of more than newlimit calls to
          Tcl_Eval() and related procedures in slave will return an error.
          The newlimit value is also returned.  The newlimit value must be
          a positive integer between 1 and the maximum value of a non-long
          integer on the platform.

          The command sets the maximum size of the Tcl call stack only. It
          cannot by itself prevent stack overflows on the  C  stack  being
          used by the application. If your machine has a limit on the size
          of the C stack, you may get stack overflows before reaching  the
          limit  set  by  the  command. If this happens, see if there is a
          mechanism in your system for increasing the maximum size of  the
          C stack.

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      apply       array
          binary      break       catch       chan
          clock       close       concat      continue
          dict        eof         error       eval
          expr        fblocked    fcopy       fileevent
          flush       for         foreach     format
          gets        global      if          incr
          info        interp      join        lappend
          lassign     lindex      linsert     list
          llength     lrange      lrepeat     lreplace
          lsearch     lset        lsort       namespace
          package     pid         proc        puts
          read        regexp      regsub      rename
          return      scan        seek        set
          split       string      subst       switch
          tell        time        trace       unset
          update      uplevel     upvar       variable
          vwait       while

   The following commands are hidden by interp create when  it  creates  a
   safe interpreter:

          cd          encoding    exec        exit
          fconfigure  file        glob        load
          open        pwd         socket      source
          unload

   These  commands can be recreated later as Tcl procedures or aliases, or
   re-exposed by interp expose.

   The following commands from Tcl's library of support procedures are not
   present in a safe interpreter:

          auto_exec_ok    auto_import     auto_load
          auto_load_index auto_qualify    unknown

   Note  in  particular  that  safe  interpreters  have no default unknown
   command, so Tcl's default autoloading  facilities  are  not  available.
   Autoload access to Tcl's commands that are normally autoloaded:

          auto_mkindex         auto_mkindex_old
          auto_reset           history
          parray               pkg_mkIndex
          ::pkg::create        ::safe::interpAddToAccessPath
          ::safe::interpCreate ::safe::interpConfigure
          ::safe::interpDelete ::safe::interpFindInAccessPath
          ::safe::interpInit   ::safe::setLogCmd
          tcl_endOfWord        tcl_findLibrary
          tcl_startOfNextWord  tcl_startOfPreviousWord
          tcl_wordBreakAfter   tcl_wordBreakBefore

   can  only  be  provided by explicit definition of an unknown command in
   the safe interpreter.  This will involve exposing the  source  command.
   This  is most easily accomplished by creating the safe interpreter with
   Tcl's Safe-Tcl mechanism.  Safe-Tcl provides safe versions  of  source,
   load,  and other Tcl commands needed to support autoloading of commands
   and the loading of packages.

   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.

   A  safe  interpreter  may  not  alter  the  recursion  limit   of   any
   interpreter, including itself.

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 targeted 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.

RESOURCE LIMITS

   Every interpreter has two kinds of resource limits that may be  imposed 
   by  any  master  interpreter  upon  its slaves. Command limits (of type 
   command) restrict the total number of Tcl commands that may be executed 
   by  an interpreter (as can be inspected via the info cmdcount command), 
   and time limits (of type time) place a limit by which execution  within 
   the  interpreter  must complete. Note that time limits are expressed as 
   absolute times (as in clock seconds) and  not  relative  times  (as  in 
   after) because they may be modified after creation.                     

   When  a  limit  is  exceeded  for  an  interpreter,  first  any handler 
   callbacks defined by master interpreters are called. If those callbacks 
   increase or remove the limit, execution within the (previously) limited 
   interpreter continues. If the limit is still  in  force,  an  error  is 
   generated  at  that  point  and  normal processing of errors within the 
   interpreter (by the catch command) is disabled, so the error propagates 
   outwards  (building  a  stack-trace  as it goes) to the point where the 
   limited interpreter was invoked (e.g. by interp eval) where it  becomes 
   the responsibility of the calling code to catch and handle.             

   LIMIT OPTIONS                                                               
   Every  limit  has a number of options associated with it, some of which 
   are common across  all  kinds  of  limits,  and  others  of  which  are 
   particular to the kind of limit.

   -command
          This  option  (common  for  all  limit types) specifies (if non- 
          empty) a Tcl script to be executed in the  global  namespace  of 
          the   interpreter  reading  and  writing  the  option  when  the 
          particular limit in the limited interpreter  is  exceeded.   The 
          callback  may  modify  the limit on the interpreter if it wishes 
          the limited interpreter to continue executing. If  the  callback 
          generates  an error, it is reported through the background error 
          mechanism  (see  BACKGROUND  ERROR  HANDLING).  Note  that   the 
          callbacks  defined  by  one  interpreter are completely isolated 
          from the callbacks defined by another, and  that  the  order  in 
          which those callbacks are called is undefined.

   -granularity
          This   option   (common  for  all  limit  types)  specifies  how 
          frequently (out of the points when the Tcl interpreter is  in  a 
          consistent  state  where  limit  checking  is possible) that the 
          limit is  actually  checked.  This  allows  the  tuning  of  how 
          frequently  a  limit  is checked, and hence how often the limit- 
          checking overhead (which may be substantial in the case of  time 
          limits) is incurred.

   -milliseconds
          This  option  specifies  the  number  of  milliseconds after the 
          moment defined in the -seconds option that the time  limit  will 
          fire.  It  should only ever be specified in conjunction with the 
          -seconds option (whether it was set previously or is  being  set 
          this invocation.)

   -seconds
          This option specifies the number of seconds after the epoch (see 
          clock seconds) that the time limit for the interpreter  will  be 
          triggered.  The  limit  will  be  triggered  at the start of the 
          second  unless  specified  at  a  sub-second  level  using   the 
          -milliseconds option. This option may be the empty string, which 
          indicates that a time limit is not set for the interpreter.

   -value This  option  specifies  the  number  of   commands   that   the 
          interpreter  may  execute  before  triggering the command limit. 
          This option may be the empty  string,  which  indicates  that  a 
          command limit is not set for the interpreter.                    

   Where  an  interpreter  with a resource limit set on it creates a slave 
   interpreter, that slave interpreter will have resource  limits  imposed 
   on  it  that  are at least as restrictive as the limits on the creating 
   master interpreter. If the master interpreter  of  the  limited  master 
   wishes  to relax these conditions, it should hide the interp command in 
   the child and then use aliases and the interp  invokehidden  subcommand 
   to  provide  such  access  as  it  chooses to the interp command to the 
   limited master as necessary.                                            

BACKGROUND ERROR HANDLING                                                      
   When an error happens in  a  situation  where  it  cannot  be  reported 
   directly  up  the  stack  (e.g.  when processing events in an update or 
   vwait call) the error is instead reported through the background  error 
   handling  mechanism.   Every interpreter has a background error handler 
   registered; the default error handler arranges for the bgerror  command 
   in  the  interpreter's  global  namespace to be called, but other error 
   handlers  may  be  installed   and   process   background   errors   in 
   substantially different ways.                                           

   A  background  error  handler  consists of a non-empty list of words to 
   which will be appended two further words at invocation time. The  first 
   word will be the error message string, and the second will a dictionary 
   of return options (this is also the sort of  information  that  can  be 
   obtained  by  trapping  a  normal  error  using  catch  of course.) The 
   resulting list will  then  be  executed  in  the  interpreter's  global 
   namespace without further substitutions being performed.

CREDITS

   The  safe  interpreter  mechanism  is  based  on the Safe-Tcl prototype
   implemented by Nathaniel Borenstein and Marshall Rose.

EXAMPLES

   Creating and using an alias for a command in the current interpreter:
          interp alias {} getIndex {} lsearch {alpha beta gamma delta}
          set idx [getIndex delta]

   Executing an arbitrary  command  in  a  safe  interpreter  where  every
   invocation of lappend is logged:
          set i [interp create -safe]
          interp hide $i lappend
          interp alias $i lappend {} loggedLappend $i
          proc loggedLappend {i args} {
             puts "logged invocation of lappend $args"
             interp invokehidden $i lappend {*}$args
          }
          interp eval $i $someUntrustedScript

   Setting  a  resource  limit  on an interpreter so that an infinite loop 
   terminates.                                                             
          set i [interp create]                                            
          interp limit $i command -value 1000                              
          interp eval $i {                                                 
             set x 0                                                       
             while {1} {                                                   
                puts "Counting up... [incr x]"                             
             }                                                             
          }                                                                

SEE ALSO

   bgerror(3tcl), load(3tcl), safe(3tcl), Tcl_CreateSlave(3tcl)

KEYWORDS

   alias, master interpreter, safe interpreter, slave interpreter





Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.





Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.


Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.





Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.


Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.





Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.


Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.