264 lines
10 KiB
Groff
264 lines
10 KiB
Groff
'\"
|
|
'\" 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_CreateAlias 3 7.6 Tcl "Tcl Library Procedures"
|
|
.so man.macros
|
|
.BS
|
|
.SH NAME
|
|
Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave, Tcl_GetChild, Tcl_GetSlave, Tcl_GetParent, 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
|
|
.VS "TIP 581"
|
|
Tcl_Interp *
|
|
\fBTcl_CreateChild\fR(\fIinterp, name, isSafe\fR)
|
|
.VE "TIP 581"
|
|
.sp
|
|
Tcl_Interp *
|
|
\fBTcl_CreateSlave\fR(\fIinterp, name, isSafe\fR)
|
|
.sp
|
|
.VS "TIP 581"
|
|
Tcl_Interp *
|
|
\fBTcl_GetChild\fR(\fIinterp, name\fR)
|
|
.VE "TIP 581"
|
|
.sp
|
|
Tcl_Interp *
|
|
\fBTcl_GetSlave\fR(\fIinterp, name\fR)
|
|
.sp
|
|
.VS "TIP 581"
|
|
Tcl_Interp *
|
|
\fBTcl_GetParent\fR(\fIinterp\fR)
|
|
.VE "TIP 581"
|
|
.sp
|
|
Tcl_Interp *
|
|
\fBTcl_GetMaster\fR(\fIinterp\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_GetInterpPath\fR(\fIinterp, childInterp\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_CreateAlias\fR(\fIchildInterp, childCmd, targetInterp, targetCmd,
|
|
argc, argv\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_CreateAliasObj\fR(\fIchildInterp, childCmd, targetInterp, targetCmd,
|
|
objc, objv\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_GetAlias\fR(\fIinterp, childCmd, targetInterpPtr, targetCmdPtr,
|
|
argcPtr, argvPtr\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_GetAliasObj\fR(\fIinterp, childCmd, 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" *name in
|
|
Name of child interpreter to create or manipulate.
|
|
.AP int isSafe in
|
|
If non-zero, a
|
|
.QW safe
|
|
child that is suitable for running untrusted code
|
|
is created, otherwise a trusted child is created.
|
|
.AP Tcl_Interp *childInterp in
|
|
Interpreter to use for creating the source command for an alias (see
|
|
below).
|
|
.AP "const char" *childCmd 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 interpreter's result contains an error message.
|
|
.PP
|
|
\fBTcl_CreateSlave\fR creates a new interpreter as a child of \fIinterp\fR.
|
|
It also creates a child command named \fIchildName\fR in \fIinterp\fR which
|
|
allows \fIinterp\fR to manipulate the new child.
|
|
If \fIisSafe\fR is zero, the command creates a trusted child in which Tcl
|
|
code has access to all the Tcl commands.
|
|
If it is \fB1\fR, the command creates a
|
|
.QW safe
|
|
child 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 child interpreter failed, \fBNULL\fR is returned.
|
|
.PP
|
|
.VS "TIP 581"
|
|
\fBTcl_CreateChild\fR is a synonym for \fBTcl_CreateSlave\fR.
|
|
.VE "TIP 581"
|
|
.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 child interpreter of
|
|
\fIinterp\fR. The child interpreter is identified by \fIchildName\fR.
|
|
If no such child interpreter exists, \fBNULL\fR is returned.
|
|
.PP
|
|
.VS "TIP 581"
|
|
\fBTcl_GetChild\fR is a synonym for \fBTcl_GetSlave\fR.
|
|
.VE "TIP 581"
|
|
.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
|
|
.VS "TIP 581"
|
|
\fBTcl_GetParent\fR is a synonym for \fBTcl_GetMaster\fR.
|
|
.VE "TIP 581"
|
|
.PP
|
|
\fBTcl_GetInterpPath\fR stores in the result of \fIinterp\fR
|
|
the relative path between \fIinterp\fR and \fIchildInterp\fR;
|
|
\fIchildInterp\fR must be a child of \fIinterp\fR. If the computation
|
|
of the relative path succeeds, \fBTCL_OK\fR is returned, else
|
|
\fBTCL_ERROR\fR is returned and an error message is stored as the
|
|
result of \fIinterp\fR.
|
|
.PP
|
|
\fBTcl_CreateAlias\fR creates a command named \fIchildCmd\fR in
|
|
\fIchildInterp\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 \fIchildCmd\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 \fIchildInterp\fR.
|
|
Note that there are no restrictions on the ancestry relationship (as
|
|
created by \fBTcl_CreateSlave\fR) between \fIchildInterp\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 as the result of \fIinterp\fR.
|
|
If an exposed command named \fIcmdName\fR already exists,
|
|
the operation returns \fBTCL_ERROR\fR and leaves an error message as
|
|
the result of \fIinterp\fR.
|
|
If the operation succeeds, it returns \fBTCL_OK\fR.
|
|
After executing this command, attempts to use \fIcmdName\fR in any
|
|
script evaluation mechanism 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 as the 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 as the 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 an error
|
|
message is left as the result of \fIinterp\fR.
|
|
If the operation succeeds, it returns \fBTCL_OK\fR.
|
|
After executing this command, attempts to use \fIcmdName\fR in
|
|
any script evaluation mechanism 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,
|
|
parent, child
|