tcl7.6 C API - CrtSlave
NAME
Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave,
Tcl_GetSlaves, Tcl_GetMaster, Tcl_CreateAlias, Tcl_GetAlias,
Tcl_GetAliases - manage multiple Tcl interpreters and
aliases.
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_GetAlias(interp, srcCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter
in which to
execute the
specified
command.
char *slaveName (in) Name of
slave inter-
preter to
create or
manipulate.
int isSafe (in) Zero means
the inter-
preter may
have all Tcl
functions.
Non-zero
means the
new
interpreter's
functional-
ity should
be limited
to make it
safe.
Tcl_Interp *slaveInterp (in) Interpreter
to use for
creating the
source com-
mand for an
alias (see
below).
char *srcCmd (in) Name of
source com-
mand for
alias.
Tcl_Interp *targetInterp (in) Interpreter
that con-
tains the
target com-
mand for an
alias.
char *targetCmd (in) Name of tar-
get command
for alias in
targetIn-
terp.
int argc (in) Count of
additional
arguments to
pass to the
alias com-
mand.
char **argv (in) Vector of
strings, the
additional
arguments to
pass to the
alias com-
mand. This
storage is
owned by the
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.
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 addi-
tional argu-
ments to be
passed to
the alias.
The location
is in
storage
owned by the
caller.
char ***argvPtr (out) Pointer to
location to
store a vec-
tor 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 func-
tion.
DESCRIPTION
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 the
given interpreter. It also creates a slave command in the
given interpreter which allows the master interpreter to
manipulate the slave. The slave interpreter and the slave
command have the specified name. If isSafe is 1, the new
slave interpreter is made ``safe'' by removing all unsafe
functionality. If the creation failed, NULL is returned.
Tcl_IsSafe returns 1 if the given interpreter is ``safe'', 0
otherwise.
Tcl_MakeSafe makes the given interpreter ``safe'' by remov-
ing 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 inter-
preter. This operation always succeeds and returns TCL_OK.
Tcl_GetSlave returns a pointer to a slave interpreter of the
given interpreter. The slave interpreter is identified by
the name specified. If no such slave interpreter exists,
NULL is returned.
Tcl_GetMaster returns a pointer to the master interpreter of
the given interpreter. If the given interpreter has no mas-
ter (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 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_GetAlias returns information about an alias of a speci-
fied name in a given interpreter. 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.
In order to map over all slave interpreters, use Tcl_Eval
with the command interp slaves and use the value (a Tcl
list) deposited in the result field of the interpreter.
Similarly, to map over all aliases whose source commands are
defined in an interpreter, use Tcl_Eval with the command
interp aliases and use the value (a Tcl list) deposited in
the result field. Note that the storage of this list belongs
to Tcl, so you should copy it before invoking any other Tcl
commands in that interpreter.
SEE ALSO
For a description of the Tcl interface to multiple inter-
preters, see interp(n).
KEYWORDS
alias, command, interpreter, master, slave