Tcl Library Procedures Tcl_CreateSlave(3TCL)
_________________________________________________________________
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
intTcl_IsSafe(interp)
intTcl_MakeSafe(interp)
Tcl_Interp *
Tcl_CreateSlave(interp, slaveName, isSafe)
Tcl_Interp *
Tcl_GetSlave(interp, slaveName)
Tcl_Interp *
Tcl_GetMaster(interp)
intTcl_GetInterpPath(askingInterp, slaveInterp)
int |Tcl_CreateAlias(slaveInterp, slaveCmd, targetInterp, targetCmd, argc, argv)|
int |Tcl_CreateAliasObj(slaveInterp, slaveCmd, targetInterp, targetCmd, objc, objv)|
intTcl_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) ||
Inter- |
preter in | Tcl Last change: 7.6 1Tcl Library Procedures Tcl_CreateSlave(3TCL)
which to | execute | the | specified | command. | CONST char *slaveName (in) || Name of | slave |inter- |
preter to | create or |manipu- |
late. | int isSafe (in) ||If non- |
zero, a | ``safe'' | slave | that is | suitable |for run- |
ning | untrusted | code is | created, | otherwise | a trusted | slave is | created. |Tcl_Interp *slaveInterp (in) ||
Inter- |
preter to | use for | creating | the | source | command | for an | alias | (see | below). | CONST char *slaveCmd (in) || Name of | source | command | for | alias. | Tcl Last change: 7.6 2Tcl Library Procedures Tcl_CreateSlave(3TCL)
Tcl_Interp *targetInterp (in) ||
Inter- |
preter |that con- |
tains the | target | command | for an | alias. | CONST char *targetCmd (in) || Name of | target | command | for alias |in tar- |
getIn- |
terp. | int argc (in) || Count of |addi- |
tional | arguments | to pass | to the | alias | command. | CONST char * CONST *argv (in) || Vector of | strings, |the addi- |
tional | arguments | to pass | to the | alias | command. | This | storage | is owned | by the | caller. | int objc (in) || Count of |addi- |
tional | object | arguments | to pass | Tcl Last change: 7.6 3Tcl Library Procedures Tcl_CreateSlave(3TCL)
to the | alias | object | command. |Tcl_Object **objv (in) ||
Vector of |Tcl_Obj |
struc- |
tures, |the addi- |
tional | object | arguments | to pass | to the | alias | object | command. | This | storage | is owned | by the | caller. |Tcl_Interp **targetInterpPtr (in) ||
Pointer |to loca- |
tion to | store the | address | of the |inter- |
preter | where a | target | command | is | defined | for an | alias. | CONST char **targetCmdPtr (out) || Pointer |to loca- |
tion to | store the | address | of the | name of |the tar- |
get | Tcl Last change: 7.6 4Tcl Library Procedures Tcl_CreateSlave(3TCL)
command | for an | alias. | int *argcPtr (out) || Pointer |to loca- |
tion to | store | count of |addi- |
tional | arguments | to be | passed to | the | alias. |The loca- |
tion is | in | storage | owned by | the | caller. | CONST char ***argvPtr (out) || Pointer |to loca- |
tion to | store a | vector of | strings, |the addi- |
tional | arguments | to pass | to an | alias. |The loca- |
tion is | in | storage | owned by | the | caller, |the vec- |
tor of | strings | is owned | by the | called | function. | Tcl Last change: 7.6 5Tcl Library Procedures Tcl_CreateSlave(3TCL)
int *objcPtr (out) || Pointer |to loca- |
tion to | store | count of |addi- |
tional | object | arguments | to be | passed to | the | alias. |The loca- |
tion is | in | storage | owned by | the | caller. |Tcl_Obj ***objvPtr (out) ||
Pointer |to loca- |
tion to | store a | vector of |Tcl_Obj |
struc- |
tures, |the addi- |
tional | arguments | to pass | to an | object | alias | command. |The loca- |
tion is | in | storage | owned by | the | caller, |the vec- |
tor of |Tcl_Obj |
struc- |
tures is | owned by | Tcl Last change: 7.6 6Tcl Library Procedures Tcl_CreateSlave(3TCL)
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 enablemanaging multiple interpreters in a hierarchical relation-
ship, and the management of aliases, commands that when invoked in one interpreter execute a command in another interpreter. The return value for those procedures thatreturn 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 Last change: 7.6 7Tcl Library Procedures Tcl_CreateSlave(3TCL)
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 notguaranteed 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 aknown-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 inter-
preter) 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 computa-
tion 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 tar- |
getCmd to be invoked in targetInterp. The arguments speci- |
fied 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 tar- |
getInterp. 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 fieldis non-NULL, the address indicated is set to the correspond-
ing datum. For example, if targetNamePtr is non-NULL it is
Tcl Last change: 7.6 8Tcl Library Procedures Tcl_CreateSlave(3TCL)
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 inter- |
preters, see interp(1T). |SEE ALSO |
interp | KEYWORDS |alias, command, exposed commands, hidden commands, inter- |
preter, invoke, master, slave |ATTRIBUTES |
See attributes(5) for descriptions of the following attri- |
butes: | Tcl Last change: 7.6 9Tcl Library Procedures Tcl_CreateSlave(3TCL)
_______________________________________ |
| ATTRIBUTE TYPE | ATTRIBUTE VALUE| |
|____________________|__________________|_ |
| Availability | runtime/tcl-8 | |
|____________________|__________________|_ |
| Interface Stability| Uncommitted | ||____________________|_________________| ||||
NOTES | Source for Tcl is available on http://opensolaris.org. | Tcl Last change: 7.6 10