Tcl_IsSafe - Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, 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_CreateSlave(3tcl) Tcl Library Procedures Tcl_CreateSlave(3tcl)
______________________________________________________________________________
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, 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)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which
to execute the speci-
fied command.
const char *slaveName (in) Name of slave inter-
preter to create or
manipulate.
int isSafe (in) If non-zero, a "safe"
slave that is suit-
able for running
untrusted code is
created, otherwise a
trusted slave is cre-
ated.
Tcl_Interp *slaveInterp (in) Interpreter to use
for creating the
source command for an
alias (see below).
const char *slaveCmd (in) Name of source com-
mand for alias.
Tcl_Interp *targetInterp (in) Interpreter that con-
tains the target com-
mand for an alias.
const 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.
const char *const *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
value arguments to
pass to the aliased
command.
Tcl_Obj **objv (in) Vector of Tcl_Obj
structures, the addi-
tional value argu-
ments to pass to the
aliased 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 com-
mand 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 location
is in storage owned
by the caller.
const 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 stor-
age 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 value
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
alias command. The
location is in stor-
age owned by the
caller, the vector 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.
______________________________________________________________________________
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 cre-
ation 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 potentially-unsafe core func-
tionality (both commands and variables) from interp. However, it can-
not 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 situa-
tions, Tcl_CreateSlave may be a better choice, since it creates inter-
preters 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 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 a command named slaveCmd in slaveInterp that
when invoked, will cause the command targetCmd to be invoked in target-
Interp. The arguments specified 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 value 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 values 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 value 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 value
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 value 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).
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | runtime/tcl-8 |
+---------------+------------------+
|Stability | Uncommitted |
+---------------+------------------+
SEE ALSO
interp
KEYWORDS
alias, command, exposed commands, hidden commands, interpreter, invoke,
master, slave
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://prdownloads.sourceforge.net/tcl/tcl-
core8.6.7-src.tar.gz.
Further information about this software can be found on the open source
community website at https://www.tcl.tk/.
Tcl 7.6 Tcl_CreateSlave(3tcl)