Provided by: tcl8.4-doc_8.4.20-7_all bug

NAME

       Tcl_IsSafe,    Tcl_MakeSafe,    Tcl_CreateSlave,    Tcl_GetSlave,    Tcl_GetMaster,    Tcl_GetInterpPath,
       Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand  -
       manage multiple Tcl interpreters, aliases and hidden commands.

SYNOPSIS

       #include <tcl.h>

       int
       Tcl_IsSafe(interp)

       int
       Tcl_MakeSafe(interp)

       Tcl_Interp *
       Tcl_CreateSlave(interp, slaveName, isSafe)

       Tcl_Interp *
       Tcl_GetSlave(interp, slaveName)

       Tcl_Interp *
       Tcl_GetMaster(interp)

       int
       Tcl_GetInterpPath(askingInterp, slaveInterp)

       int                                                                                                       │
       Tcl_CreateAlias(slaveInterp, slaveCmd, targetInterp, targetCmd, argc, argv)                               │

       int                                                                                                       │
       Tcl_CreateAliasObj(slaveInterp, slaveCmd, targetInterp, targetCmd, objc, objv)                            │

       int
       Tcl_GetAlias(interp, slaveCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr)

       int                                                                                                       │
       Tcl_GetAliasObj(interp, slaveCmd, targetInterpPtr, targetCmdPtr, objcPtr, objvPtr)                        │

       int                                                                                                       │
       Tcl_ExposeCommand(interp, hiddenCmdName, cmdName)                                                         │

       int                                                                                                       │
       Tcl_HideCommand(interp, cmdName, hiddenCmdName)                                                           │

ARGUMENTS                                                                                                        │
       Tcl_Interp             *interp           (in)                                                             │
                                                          Interpreter in which to execute the specified command. │

       CONST char             *slaveName        (in)                                                             │
                                                          Name of slave interpreter to create or manipulate.     │

       int                    isSafe            (in)                                                             │
                                                          If  non-zero,  a  ``safe''  slave that is suitable for │
                                                          running untrusted code is created, otherwise a trusted │
                                                          slave is created.                                      │

       Tcl_Interp             *slaveInterp      (in)                                                             │
                                                          Interpreter to use for creating the source command for │
                                                          an alias (see below).                                  │

       CONST char             *slaveCmd         (in)                                                             │
                                                          Name of source command for alias.                      │

       Tcl_Interp             *targetInterp     (in)                                                             │
                                                          Interpreter that contains the target  command  for  an │
                                                          alias.                                                 │

       CONST char             *targetCmd        (in)                                                             │
                                                          Name of target command for alias in targetInterp.      │

       int                    argc              (in)                                                             │
                                                          Count  of  additional  arguments  to pass to the alias │
                                                          command.                                               │

       CONST char * CONST     *argv             (in)                                                             │
                                                          Vector of strings, the additional arguments to pass to │
                                                          the  alias  command.   This  storage  is  owned by the │
                                                          caller.                                                │

       int                    objc              (in)                                                             │
                                                          Count of additional object arguments to  pass  to  the │
                                                          alias object command.                                  │

       Tcl_Object             **objv            (in)                                                             │
                                                          Vector  of  Tcl_Obj  structures, the additional object │
                                                          arguments to pass to the alias object  command.   This │
                                                          storage is owned by the caller.                        │

       Tcl_Interp             **targetInterpPtr (in)                                                             │
                                                          Pointer  to  location  to  store  the  address  of the │
                                                          interpreter where a target command is defined  for  an │
                                                          alias.                                                 │

       CONST char             **targetCmdPtr    (out)                                                            │
                                                          Pointer  to  location to store the address of the name │
                                                          of the target command for an alias.                    │

       int                    *argcPtr          (out)                                                            │
                                                          Pointer to  location  to  store  count  of  additional │
                                                          arguments  to  be passed to the alias. The location is │
                                                          in storage owned by the caller.                        │

       CONST char             ***argvPtr        (out)                                                            │
                                                          Pointer to location to store a vector of strings,  the │
                                                          additional arguments to pass to an alias. The location │
                                                          is in storage owned  by  the  caller,  the  vector  of │
                                                          strings is owned by the called function.               │

       int                    *objcPtr          (out)                                                            │
                                                          Pointer  to  location  to  store  count  of additional │
                                                          object arguments  to  be  passed  to  the  alias.  The │
                                                          location is in storage owned by the caller.            │

       Tcl_Obj                ***objvPtr        (out)                                                            │
                                                          Pointer  to  location  to  store  a  vector of Tcl_Obj │
                                                          structures, the additional arguments  to  pass  to  an │
                                                          object alias command. The location is in storage owned │
                                                          by the caller, the vector  of  Tcl_Obj  structures  is │
                                                          owned by the called function.                          │

       CONST char             *cmdName          (in)                                                             │
                                                          Name of an exposed command to hide or create.          │

       CONST char             *hiddenCmdName    (in)                                                             │
                                                          Name  under  which a hidden command is stored and with
                                                          which it can be exposed or invoked.
_________________________________________________________________

DESCRIPTION

       These procedures are intended for access to the multiple interpreter facility  from  inside  C  programs.
       They enable managing multiple interpreters in a hierarchical relationship, and the management of aliases,
       commands that when invoked in one interpreter execute a command in another interpreter. The return  value
       for  those procedures that return an int is either TCL_OK or TCL_ERROR. If TCL_ERROR is returned then the
       result field of the interpreter contains an error message.

       Tcl_CreateSlave creates a new interpreter as a slave of interp.  It also creates a  slave  command  named
       slaveName  in  interp  which  allows  interp to manipulate the new slave.  If isSafe is zero, the command
       creates a trusted slave in which Tcl code has access to all the Tcl commands.  If it is  1,  the  command
       creates  a  ``safe''  slave  in  which  Tcl code has access only to set of Tcl commands defined as ``Safe
       Tcl''; see the manual entry for the Tcl interp command for details.  If the creation  of  the  new  slave
       interpreter failed, NULL is returned.

       Tcl_IsSafe  returns 1 if interp is ``safe'' (was created with the TCL_SAFE_INTERPRETER flag specified), 0
       otherwise.

       Tcl_MakeSafe marks interp as ``safe'', so that future calls to Tcl_IsSafe will return 1.  It also removes
       all  known  potentially-unsafe core functionality (both commands and variables) from interp.  However, it
       cannot know what parts of an extension or application are safe and does not make any  attempt  to  remove
       those parts, so safety is not guaranteed after calling Tcl_MakeSafe.  Callers will want to take care with
       their use of Tcl_MakeSafe to avoid false claims of safety.  For many situations, Tcl_CreateSlave may be a
       better choice, since it creates interpreters in a known-safe state.

       Tcl_GetSlave  returns  a pointer to a slave interpreter of interp. The slave interpreter is identified by
       slaveName.  If no such slave interpreter exists, NULL is returned.

       Tcl_GetMaster returns a pointer to the master interpreter of interp. If interp has no  master  (it  is  a
       top-level interpreter) then NULL is returned.

       Tcl_GetInterpPath  sets  the  result  field in askingInterp to the relative path between askingInterp and
       slaveInterp; slaveInterp must be a slave of  askingInterp.  If  the  computation  of  the  relative  path
       succeeds,  TCL_OK  is  returned, else TCL_ERROR is returned and the result field in askingInterp contains
       the error message.

       Tcl_CreateAlias creates an object command named slaveCmd in slaveInterp that when invoked, will cause the │
       command targetCmd to be invoked in targetInterp. The arguments specified by the strings contained in argv │
       are always prepended to any arguments supplied in the invocation of slaveCmd  and  passed  to  targetCmd. │
       This operation returns TCL_OK if it succeeds, or TCL_ERROR if it fails; in that case, an error message is │
       left in the object result  of  slaveInterp.   Note  that  there  are  no  restrictions  on  the  ancestry │
       relationship  (as  created by Tcl_CreateSlave) between slaveInterp and targetInterp. Any two interpreters │
       can be used, without any restrictions on how they are related.                                            │

       Tcl_CreateAliasObj is similar to Tcl_CreateAlias except that it takes a vector  of  objects  to  pass  as │
       additional arguments instead of a vector of strings.

       Tcl_GetAlias  returns  information  about  an  alias aliasName in interp. Any of the result fields can be
       NULL, in which case the corresponding datum is not returned. If a result field is non-NULL,  the  address
       indicated  is  set  to the corresponding datum.  For example, if targetNamePtr is non-NULL it is set to a
       pointer to the string containing the name of the target command.                                          │

       Tcl_GetAliasObj is similar to Tcl_GetAlias except that it returns  a  pointer  to  a  vector  of  Tcl_Obj │
       structures instead of a vector of strings.                                                                │

       Tcl_ExposeCommand  moves  the  command  named hiddenCmdName from the set of hidden commands to the set of │
       exposed commands, putting it under the name cmdName.  HiddenCmdName must  be  the  name  of  an  existing │
       hidden  command, or the operation will return TCL_ERROR and leave an error message in the result field in │
       interp.  If an exposed command named cmdName already exists, the operation returns TCL_ERROR  and  leaves │
       an  error  message  in the object result of interp.  If the operation succeeds, it returns TCL_OK.  After │
       executing this command, attempts to use cmdName in a call to Tcl_Eval or with the Tcl eval  command  will │
       again succeed.                                                                                            │

       Tcl_HideCommand  moves  the  command  named cmdName from the set of exposed commands to the set of hidden │
       commands, under the name hiddenCmdName.  CmdName must be the name of an existing exposed command, or  the │
       operation  will  return  TCL_ERROR  and leave an error message in the object result of interp.  Currently │
       both cmdName and hiddenCmdName must not contain  namespace  qualifiers,  or  the  operation  will  return │
       TCL_ERROR  and  leave  an error message in the object result of interp.  The CmdName will be looked up in │
       the global namespace, and not relative to the current namespace, even if the current namespace is not the │
       global  one.   If a hidden command whose name is hiddenCmdName already exists, the operation also returns │
       TCL_ERROR and the result field in interp contains an  error  message.   If  the  operation  succeeds,  it │
       returns  TCL_OK.  After executing this command, attempts to use cmdName in a call to Tcl_Eval or with the │
       Tcl eval command will fail.                                                                               │

       For a description of the Tcl interface to multiple interpreters, see interp(3tcl).                        │

SEE ALSO                                                                                                         │
       interp                                                                                                    │

KEYWORDS                                                                                                         │
       alias, command, exposed commands, hidden commands, interpreter, invoke, master, slave                     │