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)
- Interpreter in which to execute the specified command.
- const 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).
- const char *slaveCmd (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 object arguments to pass to the alias
object command.
- Tcl_Obj **objv (in)
- Vector of Tcl_Obj structures, the additional object
arguments 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.
- 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 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.
- 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
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 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 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
slaveCmd 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
slaveCmd 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.
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, master,
slave