1 files changed, 142 insertions, 0 deletions
diff --git a/contrib/tcl/doc/CrtSlave.3 b/contrib/tcl/doc/CrtSlave.3
new file mode 100644
index 0000000..7979bbb
--- /dev/null
+++ b/contrib/tcl/doc/CrtSlave.3
@@ -0,0 +1,142 @@
+'\"
+'\" 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
+