|
|
Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3) _________________________________________________________________
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
#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, slaveCmd, targetInterp, targetCmd,
argc, argv)
int
Tcl_CreateAliasObj(slaveInterp, slaveCmd, targetInterp, targetCmd,
objc, objv)
int
Tcl_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)
Tcl Last change: 7.6 1
Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)
Tcl_Interp *interp (in) Interpreter
in which
to execute
the speci-
fied com-
mand.
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 suit-
able 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).
const char *slaveCmd (in) Name of
source
command
for alias.
Tcl_Interp *targetInterp (in) Interpreter
that con-
tains the
target
command
for an
alias.
Tcl Last change: 7.6 2
Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)
const char *targetCmd (in) Name of
target
command
for alias
in tar-
getInterp.
int argc (in) Count of
additional
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
additional
object
arguments
to pass to
the alias
object
command.
Tcl_Obj **objv (in) Vector of
Tcl_Obj
struc-
tures, the
additional
object
arguments
to pass to
the alias
object
command.
This
storage is
owned by
the
Tcl Last change: 7.6 3
Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)
caller.
Tcl_Interp **targetInterpPtr (in) Pointer to
location
to store
the
address of
the inter-
preter
where a
target
command is
defined
for an
alias.
const 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 loca-
tion is in
storage
owned by
the
caller.
const char ***argvPtr (out) Pointer to
location
to store a
vector of
strings,
the addi-
tional
arguments
Tcl Last change: 7.6 4
Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)
to pass to
an alias.
The loca-
tion is in
storage
owned by
the
caller,
the vector
of strings
is owned
by the
called
function.
int *objcPtr (out) Pointer to
location
to store
count of
additional
object
arguments
to be
passed to
the alias.
The loca-
tion is in
storage
owned by
the
caller.
Tcl_Obj ***objvPtr (out) Pointer to
location
to store a
vector of
Tcl_Obj
struc-
tures, the
additional
arguments
to pass to
an object
alias com-
mand. The
location
is in
storage
owned by
the
caller,
the vector
Tcl Last change: 7.6 5
Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)
of Tcl_Obj
structures
is owned
by 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.
_________________________________________________________________
These procedures are intended for access to the multiple
interpreter facility from inside C programs. They enable
managing 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 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 marks interp as "safe", so that future calls to
Tcl_IsSafe will return 1. It also removes all known
Tcl Last change: 7.6 6
Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)
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 not
guaranteed 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 a
known-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 field
is non-NULL, the address indicated is set to the correspond-
ing 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
Tcl Last change: 7.6 7
Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)
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(n).
interp
alias, command, exposed commands, hidden commands, inter-
preter, invoke, master, slave
Tcl Last change: 7.6 8