ABCDEFGHIJKLMNOPQRSTUVWXYZ

Tcl_CreateAlias

Tcl_CreateSlave(3)          Tcl Library Procedures          Tcl_CreateSlave(3)



______________________________________________________________________________

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, srcCmd, targetInterp, targetCmd, argc, argv)|

       int                                                                     |
       Tcl_CreateAliasObj(slaveInterp, srcCmd, targetInterp, targetCmd, objc, objv)|

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

       int                                                                     |
       Tcl_GetAliasObj(interp, srcCmd, 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 spec- |
                                                          ified command.       |

       char                   *slave-                                          |
       Name        (in)                           |                            |
                                                          Name of slave inter- |
                                                          preter  to create or |
                                                          manipulate.          |

       int                    isSafe            (in)                           ||
                                                          If    non-zero,    a |
                                                          ``safe'' slave  that |
                                                          is suitable for run- |
                                                          ning untrusted  code |
                                                          is  created,  other- |
                                                          wise a trusted slave |
                                                          is created.          |

       Tcl_Interp             *slaveIn-                                        |
       terp      (in)                           |                              |
                                                          Interpreter  to  use |
                                                          for   creating   the |
                                                          source  command  for |
                                                          an     alias    (see |
                                                          below).              |

       char                   *src-                                            |
       Cmd           (in)                           |                          |
                                                          Name  of source com- |
                                                          mand for alias.      |

       Tcl_Interp             *target-                                         |
       Interp     (in)                           |                             |
                                                          Interpreter     that |
                                                          contains the  target |
                                                          command    for    an |
                                                          alias.               |

       char                   *tar-                                            |
       getCmd        (in)                           |                          |
                                                          Name  of target com- |
                                                          mand  for  alias  in |
                                                          targetInterp.        |

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

       char                   **argv            (in)                           ||
                                                          Vector  of  strings, |
                                                          the additional argu- |
                                                          ments 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 |
                                                          argumenst to pass to |
                                                          the   alias   object |
                                                          command.  This stor- |
                                                          age  is owned by the |
                                                          caller.              |

       Tcl_Interp             **target-                                        |
       InterpPtr (in)                           |                              |
                                                          Pointer  to location |
                                                          to store the address |
                                                          of  the  interpreter |
                                                          where a target  com- |
                                                          mand  is defined for |
                                                          an alias.            |

       char                   **tar-                                           |
       getCmdPtr    (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.       |

       char                   ***argvPtr        (out)                          ||
                                                          Pointer  to location |
                                                          to store a vector of |
                                                          strings,  the  addi- |
                                                          tional arguments  to |
                                                          pass  to  an  alias. |
                                                          The location  is  in |
                                                          storage owned by the |
                                                          caller,  the  vector |
                                                          of  strings is owned |
                                                          by the called  func- |
                                                          tion.                |

       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 argu- |
                                                          ments to pass to  an |
                                                          object   alias  com- |
                                                          mand.  The  location |
                                                          is  in storage owned |
                                                          by the  caller,  the |
                                                          vector   of  Tcl_Obj |
                                                          structures is  owned |
                                                          by  the called func- |
                                                          tion.                |

       char                   *cmd-                                            |
       Name          (in)                           |                          |
                                                          Name  of  an exposed |
                                                          command to  hide  or |
                                                          create.              |

       char                   *hiddenCmd-                                      |
       Name    (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  inter-
       preters  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  makes  interp  ``safe'' by removing all non-core and core
       unsafe functionality. Note that if you  call  this  after  adding  some
       extension  to  an  interpreter,  all  traces  of that extension will be
       removed from the interpreter.

       Tcl_GetSlave returns a pointer to a slave interpreter  of  interp.  The
       slave  interpreter is identified by slaveName.  If no such slave inter-
       preter 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 srcCmd  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 |
       srcCmd 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_Cre- |
       ateSlave) 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 indi-
       cated 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 mes- |
       sage in the result field in interp.  If an exposed command  named  cmd- |
       Name  already  exists,  the  operation  returns TCL_ERROR and leaves an |
       error message in the object result of interp.  If  the  operation  suc- |
       ceeds,  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 opera- |
       tion 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 cur- |
       rent  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 con- |
       tains 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(n).                                                              |

SEE ALSO                                                                       |
       interp                                                                  |


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




Tcl                                   7.6                   Tcl_CreateSlave(3)