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 *slave- |
Name (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 *slaveIn- |
terp (in) | |
Interpreter to use |
for creating the |
source command for |
an alias (see |
below). |
char *src- |
Cmd (in) | |
Name of source com- |
mand for alias. |
Tcl_Interp *target- |
Interp (in) | |
Interpreter that |
contains the target |
command for an |
alias. |
char *tar- |
getCmd (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 **target- |
InterpPtr (in) | |
Pointer to location |
to store the address |
of the interpreter |
where a target com- |
mand is defined for |
an alias. |
char **tar- |
getCmdPtr (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 *cmd- |
Name (in) | |
Name of an exposed |
command to hide or |
create. |
char *hiddenCmd- |
Name (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, |
Tcl 7.6 Tcl_CreateSlave(3)