Subversion Repositories or1k_old

'\"

'\" 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.

'\"

'\" RCS: @(#) $Id: CrtSlave.3,v 1.1.1.1 2002-01-16 10:25:23 markom Exp $

'\"

.so man.macros

.TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"

.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 \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

.VS

int

\fBTcl_CreateAlias\fR(\fIslaveInterp, srcCmd, targetInterp, targetCmd, argc, argv\fR)

.sp

int

\fBTcl_CreateAliasObj\fR(\fIslaveInterp, srcCmd, targetInterp, targetCmd, objc, objv\fR)

.VE

.sp

int

\fBTcl_GetAlias\fR(\fIinterp, srcCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr\fR)

.sp

.VS

int

\fBTcl_GetAliasObj\fR(\fIinterp, srcCmd, 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 Tcl_InterpDeleteProc **hiddenCmdName

.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

If non-zero, a ``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 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 int objc in

Count of additional object arguments to pass to the alias object command.

.AP 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.

.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.

.AP 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.

.AP 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.

.VS

.AP char *cmdName in

Name of an exposed command to hide or create.

.AP char *hiddenCmdName in

Name under which a hidden command is stored and with which it can be

exposed or invoked.

.VE

.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 ``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 \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 ``safe'' (was created

with the \fBTCL_SAFE_INTERPRETER\fR flag specified),

\fB0\fR otherwise.

.PP

\fBTcl_MakeSafe\fR makes \fIinterp\fR ``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.

.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

.VS

\fBTcl_CreateAlias\fR creates an object command named \fIsrcCmd\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 \fIsrcCmd\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 object 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_CreateAliasObj\fR except

that it takes a vector of objects to pass as additional arguments instead

of a vector of strings.

.VE

.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.

.VS

.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

object 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 object 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 object 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

.SH "SEE ALSO"

For a description of the Tcl interface to multiple interpreters, see

\fIinterp(n)\fR.

.SH KEYWORDS

alias, command, exposed commands, hidden commands, interpreter, invoke,

master, slave,