Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)______________________________________________________________________________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, 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 spec‐ │
ified command. │
char *slaveName (in) │
Name of slave inter‐ │
preter to create or │
manipulate. │
int isSafe (in) │
If non-zero, a │
``safe'' slave that │
is suitable for run‐ │
ning untrusted code │
is created, other‐ │
wise 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 com‐ │
mand for alias. │
Tcl_Interp *targetInterp (in) │
Interpreter that │
contains the target │
command for an │
alias. │
char *targetCmd (in) │
Name of target com‐ │
mand 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 argu‐ │
ments 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 stor‐ │
age is owned by the │
caller. │
Tcl_Interp **targetInterpPtr (in) │
Pointer to location │
to store the address │
of the interpreter │
where a target com‐ │
mand 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 addi‐ │
tional arguments to │
pass to an alias. │
The location is in │
storage owned by the │
caller, the vector │
of strings is owned │
by the called func‐ │
tion. │
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 argu‐ │
ments to pass to an │
object alias com‐ │
mand. The location │
is in storage owned │
by the caller, the │
vector of Tcl_Obj │
structures is owned │
by the called func‐ │
tion. │
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 inter‐
preters 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 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 inter‐
preter 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_Cre‐ │
ateSlave) 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 indi‐
cated 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 mes‐ │
sage in the result field in interp. If an exposed command named cmd‐ │
Name already exists, the operation returns TCL_ERROR and leaves an │
error message in the object result of interp. If the operation suc‐ │
ceeds, 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 opera‐ │
tion 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 cur‐ │
rent 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 con‐ │
tains 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(n). │
SEE ALSO │
interp │
KEYWORDS │
alias, command, exposed commands, hidden commands, interpreter, invoke, │
master, slave, │
ATTRIBUTES │
See attributes(5) for descriptions of the following attributes: │
┌────────────────────┬─────────────────┐ ││
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │ ││
├────────────────────┼─────────────────┤ ││
│Availability │ SUNWTcl │ ││
├────────────────────┼─────────────────┤ ││
│Interface Stability │ External │ ││
└────────────────────┴─────────────────┘ ││
NOTES │
Source for Tcl is available in the SUNWTclS package. │
Tcl 7.6 Tcl_CreateSlave(3)
