Tcl_CreateSlave(3) Tcl (7.6) 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 |
Page 1 (printed 2/19/99)
Tcl_CreateSlave(3) Tcl (7.6) Tcl_CreateSlave(3)
to |
execute |
the |
specified |
command. |
char *slaveName (in) ||
Name of |
slave |
interpreter|
to create |
or |
manipulate.|
int isSafe (in) ||
If non- |
zero, a |
``safe'' |
slave |
that is |
suitable |
for |
running |
untrusted |
code is |
created, |
otherwise |
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 |
command |
for |
alias. |
Tcl_Interp *targetInterp (in) ||
Page 2 (printed 2/19/99)
Tcl_CreateSlave(3) Tcl (7.6) Tcl_CreateSlave(3)
Interpreter|
that |
contains |
the |
target |
command |
for an |
alias. |
char *targetCmd (in) ||
Name of |
target |
command |
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 |
arguments |
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. |
Page 3 (printed 2/19/99)
Tcl_CreateSlave(3) Tcl (7.6) Tcl_CreateSlave(3)
Tcl_Object **objv (in) ||
Vector of |
Tcl_Obj |
structures,|
the |
additional |
object |
argumenst |
to pass |
to the |
alias |
object |
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. |
char **targetCmdPtr (out) ||
Pointer |
to |
location |
to store |
the |
address |
of the |
name of |
the |
target |
command |
for an |
alias. |
int *argcPtr (out) ||
Page 4 (printed 2/19/99)
Tcl_CreateSlave(3) Tcl (7.6) Tcl_CreateSlave(3)
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 |
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 |
Page 5 (printed 2/19/99)
Tcl_CreateSlave(3) Tcl (7.6) Tcl_CreateSlave(3)
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 |
arguments |
to pass |
to an |
object |
alias |
command. |
The |
location |
is in |
storage |
owned by |
the |
caller, |
the |
vector of |
Tcl_Obj |
structures |
is owned |
by the |
called |
function. |
char *cmdName (in) ||
Name of |
Page 6 (printed 2/19/99)
Tcl_CreateSlave(3) Tcl (7.6) Tcl_CreateSlave(3)
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 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 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.
Page 7 (printed 2/19/99)
Tcl_CreateSlave(3) Tcl (7.6) Tcl_CreateSlave(3)
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
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_CreateSlave) |
between 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 indicated 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 message in the result |
field in interp. If an exposed command named cmdName |
already exists, the operation returns TCL_ERROR and leaves |
Page 8 (printed 2/19/99)
Tcl_CreateSlave(3) Tcl (7.6) Tcl_CreateSlave(3)
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. |
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, |
Page 9 (printed 2/19/99)
