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 hiddencommands 

Tcl Library Procedures


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 reference page 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.


PORTABILITY

Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Commands:
interp


PTC MKS Toolkit 10.4 Documentation Build 39.