Tcl_CreateAliasObj

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       │
                                                          specified command.   │

       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).              │

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

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

       char                   *targetCmd        (in)                           │
                                                          Name of target       │
                                                          command 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       │
                                                          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    │
                                                          argumenst 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.        │

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

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

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

       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 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
       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 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_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.           │

SEE ALSO                                                                       │
       For a description of the Tcl interface to multiple interpreters, see    │
       interp(n).                                                              │


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




Tcl                                   7.6                   Tcl_CreateSlave(3)