Tcl_CreateSlave (3)
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_InterpDeleteProc **hiddenCmdName
Tcl_Interp *interp in
Interpreter in which 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
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.
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
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 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 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.
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 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,
'\"
'\" Copyright (c) 1996-7 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" RCS: @(#) $Id: OpenTcp.3,v 1.2 1998/09/14 18:39:49 stanton Exp $
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\" Start paragraph describing an argument to a library procedure.
'\" type is type of argument (int, etc.), in/out is either "in", "out",
'\" or "in/out" to describe whether procedure reads or modifies arg,
'\" and indent is equivalent to second arg of .IP (shouldn't ever be
'\" needed; use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\" Give maximum sizes of arguments for setting tab stops. Type and
'\" name are examples of largest possible arguments that will be passed
'\" to .AP later. If args are omitted, default tab stops are used.
'\"
'\" .BS
'\" Start box enclosure. From here until next .BE, everything will be
'\" enclosed in one large box.
'\"
'\" .BE
'\" End of box enclosure.
'\"
'\" .CS
'\" Begin code excerpt.
'\"
'\" .CE
'\" End code excerpt.
'\"
'\" .VS ?version? ?br?
'\" Begin vertical sidebar, for use in marking newly-changed parts
'\" of man pages. The first argument is ignored and used for recording
'\" the version when the .VS was added, so that the sidebars can be
'\" found and removed when they reach a certain age. If another argument
'\" is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\" End of vertical sidebar.
'\"
'\" .DS
'\" Begin an indented unfilled display.
'\"
'\" .DE
'\" End of indented unfilled display.
'\"
'\" .SO
'\" Start of list of standard options for a Tk widget. The
'\" options follow on successive lines, in four columns separated
'\" by tabs.
'\"
'\" .SE
'\" End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\" Start of description of a specific option. cmdName gives the
'\" option's name as specified in the class command, dbName gives
'\" the option's name in the option database, and dbClass gives
'\" the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\" Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.2 1998/09/14 18:39:54 stanton Exp $
'\"
'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
t .wh -1.3i ^B
^l \n(.l
b
'\" # Start an argument description
AP
!"\\$4"" .TP \\$4
\{\
!"\\$2"" .TP \\n()Cu
.TP 15
|