Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)_________________________________________________________________NAME
Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave,
Tcl_GetSlaves, Tcl_GetMaster, Tcl_CreateAlias, Tcl_GetAl-
ias, 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) Inter-
preter in
which to
execute
the speci-
fied com-
mand.
char *slaveName (in) Name of
slave
inter-
preter to
create or
manipu-
late.
int isSafe (in) Zero means
the
Tcl 7.5 1
Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)
inter-
preter may
have all
Tcl func-
tions.
Non-zero
means the
new inter-
preter's
function-
ality
should be
limited to
make it
safe.
Tcl_Interp *slaveInterp (in) Inter-
preter 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) Inter-
preter
that con-
tains the
target
command
for an
alias.
char *targetCmd (in) Name of
target
command
for alias
in target-
Interp.
int argc (in) Count of
additional
arguments
to pass to
the alias
command.
Tcl 7.5 2
Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)
char **argv (in) Vector of
strings,
the addi-
tional
arguments
to pass to
the alias
command.
This stor-
age 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
additional
arguments
to be
passed to
the alias.
The loca-
tion is in
storage
owned by
the
Tcl 7.5 3
Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)
caller.
char ***argvPtr (out) Pointer to
location
to store a
vector of
strings,
the addi-
tional
arguments
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.
_________________________________________________________________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 con-
tains 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
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
Tcl 7.5 4
Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)
from the interpreter. 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
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 compu-
tation of the relative path succeeds, TCL_OK is returned,
else TCL_ERROR is returned and the result field in asking-
Interp contains the error message.
Tcl_GetAlias returns information about an alias of a spec-
ified 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 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.
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 com-
mand 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
Tcl 7.5 5
