-'\"
-'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-.TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
-.so man.macros
-.BS
-.SH 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
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-int
-\fBTcl_IsSafe\fR(\fIinterp\fR)
-.sp
-int
-\fBTcl_MakeSafe\fR(\fIinterp\fR)
-.sp
-Tcl_Interp *
-\fBTcl_CreateSlave\fR(\fIinterp, slaveName, isSafe\fR)
-.sp
-Tcl_Interp *
-\fBTcl_GetSlave\fR(\fIinterp, slaveName\fR)
-.sp
-Tcl_Interp *
-\fBTcl_GetMaster\fR(\fIinterp\fR)
-.sp
-int
-\fBTcl_GetInterpPath\fR(\fIaskingInterp, slaveInterp\fR)
-.sp
-int
-\fBTcl_CreateAlias\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd,
- argc, argv\fR)
-.sp
-int
-\fBTcl_CreateAliasObj\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd,
- objc, objv\fR)
-.sp
-int
-\fBTcl_GetAlias\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr,
- argcPtr, argvPtr\fR)
-.sp
-int
-\fBTcl_GetAliasObj\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr,
- objcPtr, objvPtr\fR)
-.sp
-int
-\fBTcl_ExposeCommand\fR(\fIinterp, hiddenCmdName, cmdName\fR)
-.sp
-int
-\fBTcl_HideCommand\fR(\fIinterp, cmdName, hiddenCmdName\fR)
-.SH ARGUMENTS
-.AS "const char *const" **targetInterpPtr out
-.AP Tcl_Interp *interp in
-Interpreter in which to execute the specified command.
-.AP "const char" *slaveName in
-Name of slave interpreter to create or manipulate.
-.AP int isSafe in
-If non-zero, a
-.QW safe
-slave that is suitable for running untrusted code
-is created, otherwise a trusted slave is created.
-.AP Tcl_Interp *slaveInterp in
-Interpreter to use for creating the source command for an alias (see
-below).
-.AP "const char" *slaveCmd in
-Name of source command for alias.
-.AP Tcl_Interp *targetInterp in
-Interpreter that contains the target command for an alias.
-.AP "const char" *targetCmd in
-Name of target command for alias in \fItargetInterp\fR.
-.AP int argc in
-Count of additional arguments to pass to the alias command.
-.AP "const char *const" *argv in
-Vector of strings, the additional arguments to pass to the alias command.
-This storage is owned by the caller.
-.AP int objc in
-Count of additional value arguments to pass to the aliased command.
-.AP Tcl_Obj **objv in
-Vector of Tcl_Obj structures, the additional value arguments to pass to
-the aliased command.
-This storage is owned by the caller.
-.AP Tcl_Interp **targetInterpPtr in
-Pointer to location to store the address of the interpreter where a target
-command is defined for an alias.
-.AP "const char" **targetCmdPtr out
-Pointer to location to store the address of the name of the target command
-for an alias.
-.AP 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.
-.AP "const 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.
-.AP 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.
-.AP Tcl_Obj ***objvPtr out
-Pointer to location to store a vector of Tcl_Obj structures, the additional
-arguments to pass to an alias command. The location is in storage
-owned by the caller, the vector of Tcl_Obj structures is owned by the
-called function.
-.AP "const char" *cmdName in
-Name of an exposed command to hide or create.
-.AP "const char" *hiddenCmdName in
-Name under which a hidden command is stored and with which it can be
-exposed or invoked.
-.BE
-
-.SH DESCRIPTION
-.PP
-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 \fBint\fR
-is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
-then the \fBresult\fR field of the interpreter contains an error message.
-.PP
-\fBTcl_CreateSlave\fR creates a new interpreter as a slave of \fIinterp\fR.
-It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which
-allows \fIinterp\fR to manipulate the new slave.
-If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl
-code has access to all the Tcl commands.
-If it is \fB1\fR, the command creates a
-.QW safe
-slave in which Tcl code has access only to set of Tcl commands defined as
-.QW "Safe Tcl" ;
-see the manual entry for the Tcl \fBinterp\fR command for details.
-If the creation of the new slave interpreter failed, \fBNULL\fR is returned.
-.PP
-\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is
-.QW safe
-(was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
-\fB0\fR otherwise.
-.PP
-\fBTcl_MakeSafe\fR marks \fIinterp\fR as
-.QW safe ,
-so that future
-calls to \fBTcl_IsSafe\fR will return 1. It also removes all known
-potentially-unsafe core functionality (both commands and variables)
-from \fIinterp\fR. 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 \fBTcl_MakeSafe\fR.
-Callers will want to take care with their use of \fBTcl_MakeSafe\fR
-to avoid false claims of safety. For many situations, \fBTcl_CreateSlave\fR
-may be a better choice, since it creates interpreters in a known-safe state.
-.PP
-\fBTcl_GetSlave\fR returns a pointer to a slave interpreter of
-\fIinterp\fR. The slave interpreter is identified by \fIslaveName\fR.
-If no such slave interpreter exists, \fBNULL\fR is returned.
-.PP
-\fBTcl_GetMaster\fR returns a pointer to the master interpreter of
-\fIinterp\fR. If \fIinterp\fR has no master (it is a
-top-level interpreter) then \fBNULL\fR is returned.
-.PP
-\fBTcl_GetInterpPath\fR sets the \fIresult\fR field in \fIaskingInterp\fR
-to the relative path between \fIaskingInterp\fR and \fIslaveInterp\fR;
-\fIslaveInterp\fR must be a slave of \fIaskingInterp\fR. If the computation
-of the relative path succeeds, \fBTCL_OK\fR is returned, else
-\fBTCL_ERROR\fR is returned and the \fIresult\fR field in
-\fIaskingInterp\fR contains the error message.
-.PP
-\fBTcl_CreateAlias\fR creates a command named \fIslaveCmd\fR in
-\fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR
-to be invoked in \fItargetInterp\fR. The arguments specified by the strings
-contained in \fIargv\fR are always prepended to any arguments supplied in the
-invocation of \fIslaveCmd\fR and passed to \fItargetCmd\fR.
-This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
-it fails; in that case, an error message is left in the value result
-of \fIslaveInterp\fR.
-Note that there are no restrictions on the ancestry relationship (as
-created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and
-\fItargetInterp\fR. Any two interpreters can be used, without any
-restrictions on how they are related.
-.PP
-\fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except
-that it takes a vector of values to pass as additional arguments instead
-of a vector of strings.
-.PP
-\fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
-in \fIinterp\fR. Any of the result fields can be \fBNULL\fR, in
-which case the corresponding datum is not returned. If a result field is
-non\-\fBNULL\fR, the address indicated is set to the corresponding datum.
-For example, if \fItargetNamePtr\fR is non\-\fBNULL\fR it is set to a
-pointer to the string containing the name of the target command.
-.PP
-\fBTcl_GetAliasObj\fR is similar to \fBTcl_GetAlias\fR except that it
-returns a pointer to a vector of Tcl_Obj structures instead of a vector of
-strings.
-.PP
-\fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from
-the set of hidden commands to the set of exposed commands, putting
-it under the name
-\fIcmdName\fR.
-\fIHiddenCmdName\fR must be the name of an existing hidden
-command, or the operation will return \fBTCL_ERROR\fR and leave an error
-message in the \fIresult\fR field in \fIinterp\fR.
-If an exposed command named \fIcmdName\fR already exists,
-the operation returns \fBTCL_ERROR\fR and leaves an error message in the
-value result of \fIinterp\fR.
-If the operation succeeds, it returns \fBTCL_OK\fR.
-After executing this command, attempts to use \fIcmdName\fR in a call to
-\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed.
-.PP
-\fBTcl_HideCommand\fR moves the command named \fIcmdName\fR from the set of
-exposed commands to the set of hidden commands, under the name
-\fIhiddenCmdName\fR.
-\fICmdName\fR must be the name of an existing exposed
-command, or the operation will return \fBTCL_ERROR\fR and leave an error
-message in the value result of \fIinterp\fR.
-Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain
-namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and
-leave an error message in the value result of \fIinterp\fR.
-The \fICmdName\fR 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 \fIhiddenCmdName\fR already
-exists, the operation also returns \fBTCL_ERROR\fR and the \fIresult\fR
-field in \fIinterp\fR contains an error message.
-If the operation succeeds, it returns \fBTCL_OK\fR.
-After executing this command, attempts to use \fIcmdName\fR in a call to
-\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will fail.
-.PP
-For a description of the Tcl interface to multiple interpreters, see
-\fIinterp(n)\fR.
-.SH "SEE ALSO"
-interp
-
-.SH KEYWORDS
-alias, command, exposed commands, hidden commands, interpreter, invoke,
-master, slave