Seth Woolley's Man Viewer

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

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

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, 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(1,8))                           ||
                                                          Interpreter in(1,8) which |
                                                          to execute the spec- |
                                                          ified command.       |

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

       int                    isSafe            (in(1,8))                           ||
                                                          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(1,8))                           |                              |
                                                          Interpreter  to  use |
                                                          for   creating   the |
                                                          source  command  for |
                                                          an     alias    (see |
                                                          below).              |

       CONST                                                                   |
       char             *slaveCmd         (in(1,8))                           |     |
                                                          Name  of source com- |
                                                          mand for alias.      |

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

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

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

       CONST char *                                                            |
       CONST     *argv             (in(1,8))                           |            |
                                                          Vector  of  strings, |
                                                          the additional argu- |
                                                          ments to pass to the |
                                                          alias command.  This |
                                                          storage  is owned by |
                                                          the caller.          |

       int                    objc              (in(1,8))                           ||
                                                          Count  of additional |
                                                          object arguments  to |
                                                          pass  to  the  alias |
                                                          object command.      |

       Tcl_Object             **objv            (in(1,8))                           ||
                                                          Vector   of  Tcl_Obj |
                                                          structures,      the |
                                                          additional    object |
                                                          arguments to pass to |
                                                          the   alias   object |
                                                          command.  This stor- |
                                                          age  is owned by the |
                                                          caller.              |

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

       CONST 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(1,8) storage owned |
                                                          by the caller.       |

       CONST                                                                   |
       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(1,8) |
                                                          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(1,8) |
                                                          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(1,8) storage owned |
                                                          by the  caller,  the |
                                                          vector   of  Tcl_Obj |
                                                          structures is  owned |
                                                          by  the called func- |
                                                          tion.                |

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

       CONST char             *hiddenCmd-                                      |
       Name    (in(1,8))                           |                                |
                                                          Name under  which  a
                                                          hidden   command  is
                                                          stored   and    with
                                                          which   it   can  be
                                                          exposed or  invoked.
_________________________________________________________________


DESCRIPTION
       These  procedures  are  intended for access(2,5) to the multiple interpreter
       facility from inside C programs. They enable managing  multiple  inter-
       preters  in(1,8) a hierarchical relationship, and the management of aliases,
       commands that when invoked in(1,8) one  interpreter  execute  a  command  in(1,8)
       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(8,n) message.

       Tcl_CreateSlave  creates  a  new  interpreter as a slave of interp.  It
       also creates a slave command named(5,8) slaveName  in(1,8)  interp  which  allows
       interp  to  manipulate  the  new slave.  If isSafe is zero, the command
       creates a trusted slave in(1,8) which Tcl code has access(2,5)  to  all  the  Tcl
       commands.   If  it  is 1, the command creates a ``safe'' slave in(1,8) which
       Tcl code has access(2,5) only to set(7,n,1 builtins)  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(3,n)  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 guar-
       anteed 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(1,8) 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  inter-
       preter exists, NULL is returned.

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

       Tcl_GetInterpPath sets the result field in(1,8) 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(1,8)
       askingInterp contains the error(8,n) message.

       Tcl_CreateAlias creates an object command named(5,8) slaveCmd in(1,8) slaveInterp |
       that when invoked, will cause the command targetCmd to  be  invoked  in(1,8) |
       targetInterp.  The arguments specified by the strings contained in(1,8) argv |
       are always prepended to any arguments supplied  in(1,8)  the  invocation  of |
       slaveCmd  and passed to targetCmd.  This operation returns TCL_OK if(3,n) it |
       succeeds, or TCL_ERROR if(3,n) it fails; in(1,8) that case, an error(8,n)  message  is |
       left  in(1,8)  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(1,8)  interp.
       Any  of  the result fields can be NULL, in(1,8) which case the corresponding
       datum is not returned. If a result field is non-NULL, the address indi-
       cated is set(7,n,1 builtins) to the corresponding datum.  For example, if(3,n) targetNamePtr
       is non-NULL it is set(7,n,1 builtins) to a pointer to the string(3,n) 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(5,8) hiddenCmdName from the set(7,n,1 builtins) of |
       hidden commands to the set(7,n,1 builtins) 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(8,n) mes- |
       sage  in(1,8)  the result field in(1,8) interp.  If an exposed command named(5,8) cmd- |
       Name already exists, the operation  returns  TCL_ERROR  and  leaves  an |
       error(8,n)  message  in(1,8)  the object result of interp.  If the operation suc- |
       ceeds, it returns TCL_OK.  After executing this  command,  attempts  to |
       use  cmdName  in(1,8)  a  call to Tcl_Eval or with the Tcl eval command will |
       again succeed.                                                          |

       Tcl_HideCommand moves the command named(5,8) cmdName from the set(7,n,1 builtins) of exposed |
       commands  to  the set(7,n,1 builtins) 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(8,n) message in(1,8) 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(8,n) message in(1,8) the object result of interp.  The CmdName |
       will be looked up in(1,8) the global namespace, and not relative to the cur- |
       rent namespace, even if(3,n) 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(1,8)  interp  con- |
       tains  an error(8,n) message.  If the operation succeeds, it returns TCL_OK. |
       After executing this command, attempts to use  cmdName  in(1,8)  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(5,8), slave                                                           |



Tcl                                   7.6                   Tcl_CreateSlave(3)

References for this manual (incoming links)