2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
11 .\" .AP type name in/out ?indent?
12 .\" Start paragraph describing an argument to a library procedure.
13 .\" type is type of argument (int, etc.), in/out is either "in", "out",
14 .\" or "in/out" to describe whether procedure reads or modifies arg,
15 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 .\" needed; use .AS below instead)
19 .\" Give maximum sizes of arguments for setting tab stops. Type and
20 .\" name are examples of largest possible arguments that will be passed
21 .\" to .AP later. If args are omitted, default tab stops are used.
24 .\" Start box enclosure. From here until next .BE, everything will be
25 .\" enclosed in one large box.
28 .\" End of box enclosure.
31 .\" Begin code excerpt.
36 .\" .VS ?version? ?br?
37 .\" Begin vertical sidebar, for use in marking newly-changed parts
38 .\" of man pages. The first argument is ignored and used for recording
39 .\" the version when the .VS was added, so that the sidebars can be
40 .\" found and removed when they reach a certain age. If another argument
41 .\" is present, then a line break is forced before starting the sidebar.
44 .\" End of vertical sidebar.
47 .\" Begin an indented unfilled display.
50 .\" End of indented unfilled display.
53 .\" Start of list of standard options for a Tk widget. The manpage
54 .\" argument defines where to look up the standard options; if
55 .\" omitted, defaults to "options". The options follow on successive
56 .\" lines, in three columns separated by tabs.
59 .\" End of list of standard options for a Tk widget.
61 .\" .OP cmdName dbName dbClass
62 .\" Start of description of a specific option. cmdName gives the
63 .\" option's name as specified in the class command, dbName gives
64 .\" the option's name in the option database, and dbClass gives
65 .\" the option's class in the option database.
68 .\" Print arg1 underlined, then print arg2 normally.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 .\" # Special macro to handle page bottom: finish off current
170 .\" # box/sidebar if in box/sidebar mode, then invoked standard
171 .\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
277 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
280 \fB#include <tcl.h>\fR
283 \fBTcl_IsSafe\fR(\fIinterp\fR)
286 \fBTcl_MakeSafe\fR(\fIinterp\fR)
289 \fBTcl_CreateSlave\fR(\fIinterp, slaveName, isSafe\fR)
292 \fBTcl_GetSlave\fR(\fIinterp, slaveName\fR)
295 \fBTcl_GetMaster\fR(\fIinterp\fR)
298 \fBTcl_GetInterpPath\fR(\fIaskingInterp, slaveInterp\fR)
301 \fBTcl_CreateAlias\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd,
305 \fBTcl_CreateAliasObj\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd,
309 \fBTcl_GetAlias\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr,
313 \fBTcl_GetAliasObj\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr,
317 \fBTcl_ExposeCommand\fR(\fIinterp, hiddenCmdName, cmdName\fR)
320 \fBTcl_HideCommand\fR(\fIinterp, cmdName, hiddenCmdName\fR)
322 .AS "const char *const" **targetInterpPtr out
323 .AP Tcl_Interp *interp in
324 Interpreter in which to execute the specified command.
325 .AP "const char" *slaveName in
326 Name of slave interpreter to create or manipulate.
330 slave that is suitable for running untrusted code
331 is created, otherwise a trusted slave is created.
332 .AP Tcl_Interp *slaveInterp in
333 Interpreter to use for creating the source command for an alias (see
335 .AP "const char" *slaveCmd in
336 Name of source command for alias.
337 .AP Tcl_Interp *targetInterp in
338 Interpreter that contains the target command for an alias.
339 .AP "const char" *targetCmd in
340 Name of target command for alias in \fItargetInterp\fR.
342 Count of additional arguments to pass to the alias command.
343 .AP "const char *const" *argv in
344 Vector of strings, the additional arguments to pass to the alias command.
345 This storage is owned by the caller.
347 Count of additional value arguments to pass to the aliased command.
348 .AP Tcl_Obj **objv in
349 Vector of Tcl_Obj structures, the additional value arguments to pass to
351 This storage is owned by the caller.
352 .AP Tcl_Interp **targetInterpPtr in
353 Pointer to location to store the address of the interpreter where a target
354 command is defined for an alias.
355 .AP "const char" **targetCmdPtr out
356 Pointer to location to store the address of the name of the target command
359 Pointer to location to store count of additional arguments to be passed to
360 the alias. The location is in storage owned by the caller.
361 .AP "const char" ***argvPtr out
362 Pointer to location to store a vector of strings, the additional arguments
363 to pass to an alias. The location is in storage owned by the caller, the
364 vector of strings is owned by the called function.
366 Pointer to location to store count of additional value arguments to be
367 passed to the alias. The location is in storage owned by the caller.
368 .AP Tcl_Obj ***objvPtr out
369 Pointer to location to store a vector of Tcl_Obj structures, the additional
370 arguments to pass to an alias command. The location is in storage
371 owned by the caller, the vector of Tcl_Obj structures is owned by the
373 .AP "const char" *cmdName in
374 Name of an exposed command to hide or create.
375 .AP "const char" *hiddenCmdName in
376 Name under which a hidden command is stored and with which it can be
382 These procedures are intended for access to the multiple interpreter
383 facility from inside C programs. They enable managing multiple interpreters
384 in a hierarchical relationship, and the management of aliases, commands
385 that when invoked in one interpreter execute a command in another
386 interpreter. The return value for those procedures that return an \fBint\fR
387 is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
388 then the \fBresult\fR field of the interpreter contains an error message.
390 \fBTcl_CreateSlave\fR creates a new interpreter as a slave of \fIinterp\fR.
391 It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which
392 allows \fIinterp\fR to manipulate the new slave.
393 If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl
394 code has access to all the Tcl commands.
395 If it is \fB1\fR, the command creates a
397 slave in which Tcl code has access only to set of Tcl commands defined as
399 see the manual entry for the Tcl \fBinterp\fR command for details.
400 If the creation of the new slave interpreter failed, \fBNULL\fR is returned.
402 \fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is
404 (was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
407 \fBTcl_MakeSafe\fR marks \fIinterp\fR as
410 calls to \fBTcl_IsSafe\fR will return 1. It also removes all known
411 potentially-unsafe core functionality (both commands and variables)
412 from \fIinterp\fR. However, it cannot know what parts of an extension
413 or application are safe and does not make any attempt to remove those
414 parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR.
415 Callers will want to take care with their use of \fBTcl_MakeSafe\fR
416 to avoid false claims of safety. For many situations, \fBTcl_CreateSlave\fR
417 may be a better choice, since it creates interpreters in a known-safe state.
419 \fBTcl_GetSlave\fR returns a pointer to a slave interpreter of
420 \fIinterp\fR. The slave interpreter is identified by \fIslaveName\fR.
421 If no such slave interpreter exists, \fBNULL\fR is returned.
423 \fBTcl_GetMaster\fR returns a pointer to the master interpreter of
424 \fIinterp\fR. If \fIinterp\fR has no master (it is a
425 top-level interpreter) then \fBNULL\fR is returned.
427 \fBTcl_GetInterpPath\fR sets the \fIresult\fR field in \fIaskingInterp\fR
428 to the relative path between \fIaskingInterp\fR and \fIslaveInterp\fR;
429 \fIslaveInterp\fR must be a slave of \fIaskingInterp\fR. If the computation
430 of the relative path succeeds, \fBTCL_OK\fR is returned, else
431 \fBTCL_ERROR\fR is returned and the \fIresult\fR field in
432 \fIaskingInterp\fR contains the error message.
434 \fBTcl_CreateAlias\fR creates a command named \fIslaveCmd\fR in
435 \fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR
436 to be invoked in \fItargetInterp\fR. The arguments specified by the strings
437 contained in \fIargv\fR are always prepended to any arguments supplied in the
438 invocation of \fIslaveCmd\fR and passed to \fItargetCmd\fR.
439 This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
440 it fails; in that case, an error message is left in the value result
441 of \fIslaveInterp\fR.
442 Note that there are no restrictions on the ancestry relationship (as
443 created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and
444 \fItargetInterp\fR. Any two interpreters can be used, without any
445 restrictions on how they are related.
447 \fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except
448 that it takes a vector of values to pass as additional arguments instead
449 of a vector of strings.
451 \fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
452 in \fIinterp\fR. Any of the result fields can be \fBNULL\fR, in
453 which case the corresponding datum is not returned. If a result field is
454 non\-\fBNULL\fR, the address indicated is set to the corresponding datum.
455 For example, if \fItargetNamePtr\fR is non\-\fBNULL\fR it is set to a
456 pointer to the string containing the name of the target command.
458 \fBTcl_GetAliasObj\fR is similar to \fBTcl_GetAlias\fR except that it
459 returns a pointer to a vector of Tcl_Obj structures instead of a vector of
462 \fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from
463 the set of hidden commands to the set of exposed commands, putting
466 \fIHiddenCmdName\fR must be the name of an existing hidden
467 command, or the operation will return \fBTCL_ERROR\fR and leave an error
468 message in the \fIresult\fR field in \fIinterp\fR.
469 If an exposed command named \fIcmdName\fR already exists,
470 the operation returns \fBTCL_ERROR\fR and leaves an error message in the
471 value result of \fIinterp\fR.
472 If the operation succeeds, it returns \fBTCL_OK\fR.
473 After executing this command, attempts to use \fIcmdName\fR in a call to
474 \fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed.
476 \fBTcl_HideCommand\fR moves the command named \fIcmdName\fR from the set of
477 exposed commands to the set of hidden commands, under the name
479 \fICmdName\fR must be the name of an existing exposed
480 command, or the operation will return \fBTCL_ERROR\fR and leave an error
481 message in the value result of \fIinterp\fR.
482 Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain
483 namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and
484 leave an error message in the value result of \fIinterp\fR.
485 The \fICmdName\fR will be looked up in the global namespace, and not
486 relative to the current namespace, even if the current namespace is not the
488 If a hidden command whose name is \fIhiddenCmdName\fR already
489 exists, the operation also returns \fBTCL_ERROR\fR and the \fIresult\fR
490 field in \fIinterp\fR contains an error message.
491 If the operation succeeds, it returns \fBTCL_OK\fR.
492 After executing this command, attempts to use \fIcmdName\fR in a call to
493 \fBTcl_Eval\fR or with the Tcl \fBeval\fR command will fail.
495 For a description of the Tcl interface to multiple interpreters, see
501 alias, command, exposed commands, hidden commands, interpreter, invoke,