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 be- |
low). |
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 ad- |
ditional object ar- |
gumenst 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 ex- |
posed 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 an-
other 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 in-
terp to manipulate the new slave. If isSafe is zero, the command cre-
ates a trusted slave in which Tcl code has access to all the Tcl com-
mands. 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 ex-
tension 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 re-
turned.
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 sr- |
cCmd and passed to targetCmd. This operation returns TCL_OK if it suc- |
ceeds, 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 restric- |
tions on the ancestry relationship (as created by Tcl_CreateSlave) be- |
tween slaveInterp and targetInterp. Any two interpreters can be used, |
without any restrictions on how they are related. |
Tcl_CreateAliasObj is similar to Tcl_CreateAliasObj 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 er- |
ror message in the object result of interp. If the operation succeeds, |
it returns TCL_OK. After executing this command, attempts to use cmd- |
Name in a call to Tcl_Eval or with the Tcl eval command will again suc- |
ceed. |
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 re- |
sult of interp. Currently both cmdName and hiddenCmdName must not con- |
tain 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 op- |
eration 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. |
SEE ALSO |
For a description of the Tcl interface to multiple interpreters, see |
interp(n). |
KEYWORDS |
alias, command, exposed commands, hidden commands, interpreter, invoke, |
master, slave, |
Tcl 7.6 Tcl_CreateSlave(3)