Manual Pages for UNIX Darwin command on man Tcl

Manual Pages for UNIX Darwin command on man Tcl_ExposeCommand

TclCreateSlave(3) Tcl Library Procedures TclCreateSlave(3)

NAME

TclIsSafe, TclMakeSafe, TclCreateSlave, TclGetSlave, TclGetMaster, TclGetInterpPath, TclCreateAlias, TclCreateAliasObj, TclGetAlias,

TclGetAliasObj, TclExposeCommand, TclHideCommand - manage multiple

Tcl interpreters, aliases and hidden commands.

SYNOPSIS

##iinncclluuddee <>

int TTccllIIssSSaaffee(interp) int TTccllMMaakkeeSSaaffee(interp) TclInterp * TTccllCCrreeaatteeSSllaavvee(interp, slaveName, isSafe) TclInterp * TTccllGGeettSSllaavvee(interp, slaveName) TclInterp * TTccllGGeettMMaasstteerr(interp) int TTccllGGeettIInntteerrppPPaatthh(askingInterp, slaveInterp) int | TTccllCCrreeaatteeAAlliiaass(slaveInterp, slaveCmd, targetInterp, targetCmd, argc, argv)| int | TTccllCCrreeaatteeAAlliiaassOObbjj(slaveInterp, slaveCmd, targetInterp, targetCmd, objc, objv)| int TTccllGGeettAAlliiaass(interp, slaveCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr) int | TTccllGGeettAAlliiaassOObbjj(interp, slaveCmd, targetInterpPtr, targetCmdPtr, objcPtr, objvPtr)| int | TTccllEExxppoosseeCCoommmmaanndd(interp, hiddenCmdName, cmdName) | int | TTccllHHiiddeeCCoommmmaanndd(interp, cmdName, hiddenCmdName) | AARRGGUUMMEENNTTSS | TclInterp *interp (in) || Interpreter in which |

to execute the spec- |

ified command. |

CONST char *slave- |

Name (in) | |

Name of slave inter- |

preter to create or | manipulate. | int isSafe (in) ||

If non-zero, a |

``safe'' slave that |

is suitable for run- |

ning untrusted code |

is created, other- |

wise a trusted slave | is created. |

TclInterp *slaveIn- |

Name of source com- |

mand for alias. |

TclInterp *target- |

CONST char *tar- |

getCmd (in) | |

Name of target com- |

mand for alias in | targetInterp. | int argc (in) || Count of additional | arguments to pass to | the alias command. | CONST char * | CONST *argv (in) | | Vector of strings, |

the additional argu- |

ments to pass to the | alias command. This | storage is owned by | the caller. | int objc (in) || Count of additional | object arguments to | pass to the alias | object command. | TclObject **objv (in) || Vector of TclObj | structures, the | additional object | arguments to pass to | the alias object |

command. This stor- |

age is owned by the | caller. |

TclInterp **target- |

where a target com- |

mand is defined for | an alias. |

CONST char **tar- |

getCmdPtr (out) | | Pointer to location | to store the address | of the name of the | target command for | an alias. | 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. | CONST | char ***argvPtr (out) | | Pointer to location | to store a vector of |

strings, the addi- |

by the called func- |

tion. | 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. | TclObj ***objvPtr (out) || Pointer to location | to store a vector of | TclObj structures, |

the additional argu- |

ments to pass to an |

object alias com- |

by the called func- |

tion. |

CONST char *cmd- |

Name (in) | | Name of an exposed command to hide or create. |

CONST char *hiddenCmd- |

Name (in) | | Name under which a hidden command is stored and with which it can be exposed or invoked.

DESCRIPTION

These procedures are intended for access to the multiple interpreter

facility from inside C programs. They enable managing multiple inter-

preters 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 iinntt is either TTCCLLOOKK or TTCCLLEERRRROORR. If TTCCLLEERRRROORR is returned then the rreessuulltt field of the interpreter contains an error message. TTccllCCrreeaatteeSSllaavvee creates a new interpreter as a slave of interp. It also creates a slave command named slaveName in interp which allows interp to manipulate the new slave. If isSafe is zero, the command creates a trusted slave in which Tcl code has access to all the Tcl commands. If it is 11, 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 iinntteerrpp command for details. If the creation of the new slave interpreter failed, NNUULLLL is returned. TTccllIIssSSaaffee returns 11 if interp is ``safe'' (was created with the TTCCLLSSAAFFEEIINNTTEERRPPRREETTEERR flag specified), 00 otherwise. TTccllMMaakkeeSSaaffee marks interp as ``safe'', so that future calls to

TTccllIIssSSaaffee will return 1. It also removes all known potentially-unsafe

core functionality (both commands and variables) from interp. 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 guar-

anteed after calling TTccllMMaakkeeSSaaffee. Callers will want to take care with their use of TTccllMMaakkeeSSaaffee to avoid false claims of safety. For many situations, TTccllCCrreeaatteeSSllaavvee may be a better choice, since it creates

interpreters in a known-safe state.

TTccllGGeettSSllaavvee returns a pointer to a slave interpreter of interp. The

slave interpreter is identified by slaveName. If no such slave inter-

preter exists, NNUULLLL is returned. TTccllGGeettMMaasstteerr returns a pointer to the master interpreter of interp. If

interp has no master (it is a top-level interpreter) then NNUULLLL is

returned. TTccllGGeettIInntteerrppPPaatthh sets the result field in askingInterp to the relative path between askingInterp and slaveInterp; slaveInterp must be a slave of askingInterp. If the computation of the relative path succeeds, TTCCLLOOKK is returned, else TTCCLLEERRRROORR is returned and the result field in askingInterp contains the error message. TTccllCCrreeaatteeAAlliiaass creates an object command named slaveCmd in slaveInterp | that when invoked, will cause the command targetCmd to be invoked in | targetInterp. The arguments specified by the strings contained in argv | are always prepended to any arguments supplied in the invocation of | slaveCmd and passed to targetCmd. This operation returns TTCCLLOOKK if it | succeeds, or TTCCLLEERRRROORR if it fails; in that case, an error message is | left in the object result of slaveInterp. Note that there are no |

restrictions on the ancestry relationship (as created by TTccllCCrree- |

aatteeSSllaavvee) between slaveInterp and targetInterp. Any two interpreters | can be used, without any restrictions on how they are related. | TTccllCCrreeaatteeAAlliiaassOObbjj is similar to TTccllCCrreeaatteeAAlliiaass except that it takes a | vector of objects to pass as additional arguments instead of a vector | of strings. TTccllGGeettAAlliiaass returns information about an alias aliasName in interp. Any of the result fields can be NNUULLLL, in which case the corresponding

datum is not returned. If a result field is non-NNUULLLL, the address indi-

cated is set to the corresponding datum. For example, if targetNamePtr

is non-NNUULLLL it is set to a pointer to the string containing the name of

the target command. | TTccllGGeettAAlliiaassOObbjj is similar to TTccllGGeettAAlliiaass except that it returns a | pointer to a vector of TclObj structures instead of a vector of | strings. | TTccllEExxppoosseeCCoommmmaanndd moves the command named hiddenCmdName from the set of | hidden commands to the set of exposed commands, putting it under the | name cmdName. HiddenCmdName must be the name of an existing hidden |

command, or the operation will return TTCCLLEERRRROORR and leave an error mes- |

sage in the result field in interp. If an exposed command named cmd- |

Name already exists, the operation returns TTCCLLEERRRROORR and leaves an |

error message in the object result of interp. If the operation suc- |

ceeds, it returns TTCCLLOOKK. After executing this command, attempts to | use cmdName in a call to TTccllEEvvaall or with the Tcl eevvaall command will | again succeed. | TTccllHHiiddeeCCoommmmaanndd moves the command named cmdName from the set of exposed | commands to the set of hidden commands, under the name hiddenCmdName. |

CmdName must be the name of an existing exposed command, or the opera- |

tion will return TTCCLLEERRRROORR and leave an error message in the object | result of interp. Currently both cmdName and hiddenCmdName must not | contain namespace qualifiers, or the operation will return TTCCLLEERRRROORR | and leave an error message in the object result of interp. The CmdName |

will be looked up in the global namespace, and not relative to the cur- |

rent namespace, even if the current namespace is not the global one. | If a hidden command whose name is hiddenCmdName already exists, the |

operation also returns TTCCLLEERRRROORR and the result field in interp con- |

tains an error message. If the operation succeeds, it returns TTCCLLOOKK. | After executing this command, attempts to use cmdName in a call to | TTccllEEvvaall or with the Tcl eevvaall command will fail. | For a description of the Tcl interface to multiple interpreters, see | interp(n). |