- 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
- DESCRIPTION
- SEE ALSO
- KEYWORDS
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
#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)
- 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.
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_GetAliasObj returns information in the form of a pointer to
a vector of Tcl_Obj structures 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 targetCmdPtr is non-NULL it is set to a
pointer to the string containing the name of the target command.
Tcl_GetAlias is similar to Tcl_GetAliasObj except that it
returns a pointer to a vector of string instead of a vector of
Tcl_Obj structures. Tcl_GetAlias is deprecated.
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(n).
interp
alias, command, exposed commands, hidden commands, interpreter, invoke, parent, child
Copyright © 1995-1996 Sun Microsystems, Inc.