143 lines
5.8 KiB
Groff
143 lines
5.8 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.
|
|
'\"
|
|
'\" SCCS: @(#) CrtSlave.3 1.13 96/03/25 20:00:42
|
|
'\"
|
|
.so man.macros
|
|
.TH Tcl_CreateSlave 3 7.5 Tcl "Tcl Library Procedures"
|
|
.BS
|
|
.SH 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.
|
|
.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, srcCmd, targetInterp, targetCmd, argc, argv\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_GetAlias\fR(\fIinterp, srcCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr\fR)
|
|
.SH ARGUMENTS
|
|
.AS Tcl_InterpDeleteProc **delProcPtr
|
|
.AP Tcl_Interp *interp in
|
|
Interpreter in which to execute the specified command.
|
|
.AP char *slaveName in
|
|
Name of slave interpreter to create or manipulate.
|
|
.AP int isSafe in
|
|
Zero means the interpreter may have all Tcl functions. Non-zero means the
|
|
new interpreter's functionality should be limited to make it safe.
|
|
.AP Tcl_Interp *slaveInterp in
|
|
Interpreter to use for creating the source command for an alias (see
|
|
below).
|
|
.AP char *srcCmd in
|
|
Name of source command for alias.
|
|
.AP Tcl_Interp *targetInterp in
|
|
Interpreter that contains the target command for an alias.
|
|
.AP 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 char **argv in
|
|
Vector of strings, the additional arguments to pass to the alias 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 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 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.
|
|
.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 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 \fIisSafe\fR
|
|
is \fB1\fR, the new slave interpreter is made ``safe'' by removing all
|
|
unsafe functionality. If the creation failed, \fBNULL\fR is returned.
|
|
.PP
|
|
\fBTcl_IsSafe\fR returns \fB1\fR if the given interpreter is ``safe'',
|
|
\fB0\fR otherwise.
|
|
.PP
|
|
\fBTcl_MakeSafe\fR 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 from the interpreter. This operation always succeeds and returns
|
|
\fBTCL_OK\fR.
|
|
.PP
|
|
\fBTcl_GetSlave\fR 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, \fBNULL\fR is returned.
|
|
.PP
|
|
\fBTcl_GetMaster\fR 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 \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_GetAlias\fR returns information about an alias of a specified name
|
|
in a given interpreter. 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
|
|
In order to map over all slave interpreters, use \fBTcl_Eval\fR with the
|
|
command \fBinterp slaves\fR and use the value (a Tcl list) deposited in the
|
|
\fBresult\fR field of the interpreter. Similarly, to map over all aliases
|
|
whose source commands are defined in an interpreter, use \fBTcl_Eval\fR
|
|
with the command \fBinterp aliases\fR and use the value (a Tcl list)
|
|
deposited in the \fBresult\fR 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.
|
|
.SH "SEE ALSO"
|
|
For a description of the Tcl interface to multiple interpreters, see
|
|
\fIinterp(n)\fR.
|
|
|
|
.SH KEYWORDS
|
|
alias, command, interpreter, master, slave
|
|
|