Provided by: tcl8.6-doc_8.6.12+dfsg-1build1_all 
NAME
Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave, Tcl_GetChild, Tcl_GetSlave,
Tcl_GetParent, 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_CreateChild(interp, name, isSafe) │
Tcl_Interp *
Tcl_CreateSlave(interp, name, isSafe)
Tcl_Interp * │
Tcl_GetChild(interp, name) │
Tcl_Interp *
Tcl_GetSlave(interp, name)
Tcl_Interp * │
Tcl_GetParent(interp) │
Tcl_Interp *
Tcl_GetMaster(interp)
int
Tcl_GetInterpPath(interp, childInterp)
int
Tcl_CreateAlias(childInterp, childCmd, targetInterp, targetCmd,
argc, argv)
int
Tcl_CreateAliasObj(childInterp, childCmd, targetInterp, targetCmd,
objc, objv)
int
Tcl_GetAlias(interp, childCmd, targetInterpPtr, targetCmdPtr,
argcPtr, argvPtr)
int
Tcl_GetAliasObj(interp, childCmd, 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 *name (in) Name of child interpreter to create or
manipulate.
int isSafe (in) If non-zero, a “safe” child that is
suitable for running untrusted code is
created, otherwise a trusted child is
created.
Tcl_Interp *childInterp (in) Interpreter to use for creating the
source command for an alias (see below).
const char *childCmd (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 value arguments to
pass to the aliased command.
Tcl_Obj **objv (in) Vector of Tcl_Obj structures, the
additional value arguments to pass to
the aliased 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 value 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 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 interpreter's result contains an
error message.
Tcl_CreateSlave creates a new interpreter as a child of interp. It also creates a child
command named childName in interp which allows interp to manipulate the new child. If
isSafe is zero, the command creates a trusted child in which Tcl code has access to all
the Tcl commands. If it is 1, the command creates a “safe” child 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 child interpreter failed, NULL is
returned.
Tcl_CreateChild is a synonym for Tcl_CreateSlave. │
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 child interpreter of interp. The child interpreter is
identified by childName. If no such child interpreter exists, NULL is returned.
Tcl_GetChild is a synonym for Tcl_GetSlave. │
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_GetParent is a synonym for Tcl_GetMaster. │
Tcl_GetInterpPath stores in the result of interp the relative path between interp and
childInterp; childInterp must be a child of interp. If the computation of the relative
path succeeds, TCL_OK is returned, else TCL_ERROR is returned and an error message is
stored as the result of interp.
Tcl_CreateAlias creates a command named childCmd in childInterp 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 childCmd 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 value result of
childInterp. Note that there are no restrictions on the ancestry relationship (as created
by Tcl_CreateSlave) between childInterp 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 values
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 as the result of interp. If an exposed command named cmdName already
exists, the operation returns TCL_ERROR and leaves an error message as the result of
interp. If the operation succeeds, it returns TCL_OK. After executing this command,
attempts to use cmdName in any script evaluation mechanism 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 as the 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 as the 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 an error message is left as the result of interp. If the operation
succeeds, it returns TCL_OK. After executing this command, attempts to use cmdName in any
script evaluation mechanism 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, parent, child