1interp(n) Tcl Built-In Commands interp(n)
2______________________________________________________________________________
6
8 interp - Create and manipulate Tcl interpreters
9
11 interp subcommand ?arg arg ...?
12______________________________________________________________________________
13
15 This command makes it possible to create one or more new Tcl inter‐
16 preters that co-exist with the creating interpreter in the same appli‐
17 cation. The creating interpreter is called the master and the new
18 interpreter is called a slave. A master can create any number of
19 slaves, and each slave can itself create additional slaves for which it
20 is master, resulting in a hierarchy of interpreters.
21 Each interpreter is independent from the others: it has its own name
23 space for commands, procedures, and global variables. A master inter‐
24 preter may create connections between its slaves and itself using a
25 mechanism called an alias. An alias is a command in a slave inter‐
26 preter which, when invoked, causes a command to be invoked in its mas‐
27 ter interpreter or in another slave interpreter. The only other con‐
28 nections between interpreters are through environment variables (the
29 env variable), which are normally shared among all interpreters in the
30 application, and by resource limit exceeded callbacks. Note that the
31 name space for files (such as the names returned by the open command)
32 is no longer shared between interpreters. Explicit commands are pro‐
33 vided to share files and to transfer references to open files from one
34 interpreter to another.
35 The interp command also provides support for safe interpreters. A safe
37 interpreter is a slave whose functions have been greatly restricted, so
38 that it is safe to execute untrusted scripts without fear of them dam‐
39 aging other interpreters or the application's environment. For example,
40 all IO channel creation commands and subprocess creation commands are
41 made inaccessible to safe interpreters. See SAFE INTERPRETERS below
42 for more information on what features are present in a safe inter‐
43 preter. The dangerous functionality is not removed from the safe
44 interpreter; instead, it is hidden, so that only trusted interpreters
45 can obtain access to it. For a detailed explanation of hidden commands,
46 see HIDDEN COMMANDS, below. The alias mechanism can be used for pro‐
47 tected communication (analogous to a kernel call) between a slave
48 interpreter and its master. See ALIAS INVOCATION, below, for more
49 details on how the alias mechanism works.
50 A qualified interpreter name is a proper Tcl lists containing a subset
52 of its ancestors in the interpreter hierarchy, terminated by the string
53 naming the interpreter in its immediate master. Interpreter names are
54 relative to the interpreter in which they are used. For example, if “a”
55 is a slave of the current interpreter and it has a slave “a1”, which in
56 turn has a slave “a11”, the qualified name of “a11” in “a” is the list
57 “a1 a11”.
58 The interp command, described below, accepts qualified interpreter
60 names as arguments; the interpreter in which the command is being eval‐
61 uated can always be referred to as {} (the empty list or string). Note
62 that it is impossible to refer to a master (ancestor) interpreter by
63 name in a slave interpreter except through aliases. Also, there is no
64 global name by which one can refer to the first interpreter created in
65 an application. Both restrictions are motivated by safety concerns.
66
68 The interp command is used to create, delete, and manipulate slave
69 interpreters, and to share or transfer channels between interpreters.
70 It can have any of several forms, depending on the subcommand argument:
71 interp alias srcPath srcToken
73 Returns a Tcl list whose elements are the targetCmd and args
74 associated with the alias represented by srcToken (this is the
75 value returned when the alias was created; it is possible that
76 the name of the source command in the slave is different from
77 srcToken).
78 interp alias srcPath srcToken {}
80 Deletes the alias for srcToken in the slave interpreter identi‐
81 fied by srcPath. srcToken refers to the value returned when the
82 alias was created; if the source command has been renamed, the
83 renamed command will be deleted.
84 interp alias srcPath srcCmd targetPath targetCmd ?arg arg ...?
86 This command creates an alias between one slave and another (see
87 the alias slave command below for creating aliases between a
88 slave and its master). In this command, either of the slave
89 interpreters may be anywhere in the hierarchy of interpreters
90 under the interpreter invoking the command. SrcPath and srcCmd
91 identify the source of the alias. SrcPath is a Tcl list whose
92 elements select a particular interpreter. For example, “a b”
93 identifies an interpreter “b”, which is a slave of interpreter
94 “a”, which is a slave of the invoking interpreter. An empty
95 list specifies the interpreter invoking the command. srcCmd
96 gives the name of a new command, which will be created in the
97 source interpreter. TargetPath and targetCmd specify a target
98 interpreter and command, and the arg arguments, if any, specify
99 additional arguments to targetCmd which are prepended to any
100 arguments specified in the invocation of srcCmd. TargetCmd may
101 be undefined at the time of this call, or it may already exist;
102 it is not created by this command. The alias arranges for the
103 given target command to be invoked in the target interpreter
104 whenever the given source command is invoked in the source
105 interpreter. See ALIAS INVOCATION below for more details. The
106 command returns a token that uniquely identifies the command
107 created srcCmd, even if the command is renamed afterwards. The
108 token may but does not have to be equal to srcCmd.
109 interp aliases ?path?
111 This command returns a Tcl list of the tokens of all the source
112 commands for aliases defined in the interpreter identified by
113 path. The tokens correspond to the values returned when the
114 aliases were created (which may not be the same as the current
115 names of the commands).
116 interp bgerror path ?cmdPrefix?
118 This command either gets or sets the current background excep‐
119 tion handler for the interpreter identified by path. If cmdPre‐
120 fix is absent, the current background exception handler is
121 returned, and if it is present, it is a list of words (of mini‐
122 mum length one) that describes what to set the interpreter's
123 background exception handler to. See the BACKGROUND EXCEPTION
124 HANDLING section for more details.
125 interp cancel ?-unwind? ?--? ?path? ?result?
127 Cancels the script being evaluated in the interpreter identified │
128 by path. Without the -unwind switch the evaluation stack for the │
129 interpreter is unwound until an enclosing catch command is found │
130 or there are no further invocations of the interpreter left on │
131 the call stack. With the -unwind switch the evaluation stack for │
132 the interpreter is unwound without regard to any intervening │
133 catch command until there are no further invocations of the │
134 interpreter left on the call stack. The -- switch can be used to │
135 mark the end of switches; it may be needed if path is an unusual │
136 value such as -safe. If result is present, it will be used as │
137 the error message string; otherwise, a default error message │
138 string will be used.
139 interp create ?-safe? ?--? ?path?
141 Creates a slave interpreter identified by path and a new com‐
142 mand, called a slave command. The name of the slave command is
143 the last component of path. The new slave interpreter and the
144 slave command are created in the interpreter identified by the
145 path obtained by removing the last component from path. For
146 example, if path is a b c then a new slave interpreter and slave
147 command named c are created in the interpreter identified by the
148 path a b. The slave command may be used to manipulate the new
149 interpreter as described below. If path is omitted, Tcl creates
150 a unique name of the form interpx, where x is an integer, and
151 uses it for the interpreter and the slave command. If the -safe
152 switch is specified (or if the master interpreter is a safe
153 interpreter), the new slave interpreter will be created as a
154 safe interpreter with limited functionality; otherwise the slave
155 will include the full set of Tcl built-in commands and vari‐
156 ables. The -- switch can be used to mark the end of switches;
157 it may be needed if path is an unusual value such as -safe. The
158 result of the command is the name of the new interpreter. The
159 name of a slave interpreter must be unique among all the slaves
160 for its master; an error occurs if a slave interpreter by the
161 given name already exists in this master. The initial recursion
162 limit of the slave interpreter is set to the current recursion
163 limit of its parent interpreter.
164 interp debug path ?-frame ?bool??
166 Controls whether frame-level stack information is captured in
167 the slave interpreter identified by path. If no arguments are
168 given, option and current setting are returned. If -frame is
169 given, the debug setting is set to the given boolean if provided
170 and the current setting is returned. This only affects the out‐
171 put of info frame, in that exact frame-level information for
172 command invocation at the bytecode level is only captured with
173 this setting on.
174 For example, with code like
176 proc mycontrol {... script} {
178 ...
179 uplevel 1 $script
180 ...
181 }
182 proc dosomething {...} {
184 ...
185 mycontrol {
186 somecode
187 }
188 }
189 the standard setting will provide a relative line number for the
191 command somecode and the relevant frame will be of type eval.
192 With frame-debug active on the other hand the tracking extends
193 so far that the system will be able to determine the file and
194 absolute line number of this command, and return a frame of type
195 source. This more exact information is paid for with slower exe‐
196 cution of all commands.
197 Note that once it is on, this flag cannot be switched back off:
199 such attempts are silently ignored. This is needed to maintain
200 the consistency of the underlying interpreter's state.
201 interp delete ?path ...?
203 Deletes zero or more interpreters given by the optional path
204 arguments, and for each interpreter, it also deletes its slaves.
205 The command also deletes the slave command for each interpreter
206 deleted. For each path argument, if no interpreter by that name
207 exists, the command raises an error.
208 interp eval path arg ?arg ...?
210 This command concatenates all of the arg arguments in the same
211 fashion as the concat command, then evaluates the resulting
212 string as a Tcl script in the slave interpreter identified by
213 path. The result of this evaluation (including all return
214 options, such as -errorinfo and -errorcode information, if an
215 error occurs) is returned to the invoking interpreter. Note
216 that the script will be executed in the current context stack
217 frame of the path interpreter; this is so that the implementa‐
218 tions (in a master interpreter) of aliases in a slave inter‐
219 preter can execute scripts in the slave that find out informa‐
220 tion about the slave's current state and stack frame.
221 interp exists path
223 Returns 1 if a slave interpreter by the specified path exists in
224 this master, 0 otherwise. If path is omitted, the invoking
225 interpreter is used.
226 interp expose path hiddenName ?exposedCmdName?
228 Makes the hidden command hiddenName exposed, eventually bringing
229 it back under a new exposedCmdName name (this name is currently
230 accepted only if it is a valid global name space name without
231 any ::), in the interpreter denoted by path. If an exposed com‐
232 mand with the targeted name already exists, this command fails.
233 Hidden commands are explained in more detail in HIDDEN COMMANDS,
234 below.
235 interp hide path exposedCmdName ?hiddenCmdName?
237 Makes the exposed command exposedCmdName hidden, renaming it to
238 the hidden command hiddenCmdName, or keeping the same name if
239 hiddenCmdName is not given, in the interpreter denoted by path.
240 If a hidden command with the targeted name already exists, this
241 command fails. Currently both exposedCmdName and hiddenCmdName
242 can not contain namespace qualifiers, or an error is raised.
243 Commands to be hidden by interp hide are looked up in the global
244 namespace even if the current namespace is not the global one.
245 This prevents slaves from fooling a master interpreter into hid‐
246 ing the wrong command, by making the current namespace be dif‐
247 ferent from the global one. Hidden commands are explained in
248 more detail in HIDDEN COMMANDS, below.
249 interp hidden path
251 Returns a list of the names of all hidden commands in the inter‐
252 preter identified by path.
253 interp invokehidden path ?-option ...? hiddenCmdName ?arg ...?
255 Invokes the hidden command hiddenCmdName with the arguments sup‐
256 plied in the interpreter denoted by path. No substitutions or
257 evaluation are applied to the arguments. Three -options are sup‐
258 ported, all of which start with -: -namespace (which takes a
259 single argument afterwards, nsName), -global, and --. If the
260 -namespace flag is present, the hidden command is invoked in the
261 namespace called nsName in the target interpreter. If the
262 -global flag is present, the hidden command is invoked at the
263 global level in the target interpreter; otherwise it is invoked
264 at the current call frame and can access local variables in that
265 and outer call frames. The -- flag allows the hiddenCmdName
266 argument to start with a “-” character, and is otherwise unnec‐
267 essary. If both the -namespace and -global flags are present,
268 the -namespace flag is ignored. Note that the hidden command
269 will be executed (by default) in the current context stack frame
270 of the path interpreter. Hidden commands are explained in more
271 detail in HIDDEN COMMANDS, below.
272 interp issafe ?path?
274 Returns 1 if the interpreter identified by the specified path is
275 safe, 0 otherwise.
276 interp limit path limitType ?-option? ?value ...?
278 Sets up, manipulates and queries the configuration of the
279 resource limit limitType for the interpreter denoted by path.
280 If no -option is specified, return the current configuration of
281 the limit. If -option is the sole argument, return the value of
282 that option. Otherwise, a list of -option/value argument pairs
283 must supplied. See RESOURCE LIMITS below for a more detailed
284 explanation of what limits and options are supported.
285 interp marktrusted path
287 Marks the interpreter identified by path as trusted. Does not
288 expose the hidden commands. This command can only be invoked
289 from a trusted interpreter. The command has no effect if the
290 interpreter identified by path is already trusted.
291 interp recursionlimit path ?newlimit?
293 Returns the maximum allowable nesting depth for the interpreter
294 specified by path. If newlimit is specified, the interpreter
295 recursion limit will be set so that nesting of more than
296 newlimit calls to Tcl_Eval and related procedures in that inter‐
297 preter will return an error. The newlimit value is also
298 returned. The newlimit value must be a positive integer between
299 1 and the maximum value of a non-long integer on the platform.
300 The command sets the maximum size of the Tcl call stack only. It
302 cannot by itself prevent stack overflows on the C stack being
303 used by the application. If your machine has a limit on the size
304 of the C stack, you may get stack overflows before reaching the
305 limit set by the command. If this happens, see if there is a
306 mechanism in your system for increasing the maximum size of the
307 C stack.
308 interp share srcPath channelId destPath
310 Causes the IO channel identified by channelId to become shared
311 between the interpreter identified by srcPath and the inter‐
312 preter identified by destPath. Both interpreters have the same
313 permissions on the IO channel. Both interpreters must close it
314 to close the underlying IO channel; IO channels accessible in an
315 interpreter are automatically closed when an interpreter is
316 destroyed.
317 interp slaves ?path?
319 Returns a Tcl list of the names of all the slave interpreters
320 associated with the interpreter identified by path. If path is
321 omitted, the invoking interpreter is used.
322 interp target path alias
324 Returns a Tcl list describing the target interpreter for an
325 alias. The alias is specified with an interpreter path and
326 source command name, just as in interp alias above. The name of
327 the target interpreter is returned as an interpreter path, rela‐
328 tive to the invoking interpreter. If the target interpreter for
329 the alias is the invoking interpreter then an empty list is
330 returned. If the target interpreter for the alias is not the
331 invoking interpreter or one of its descendants then an error is
332 generated. The target command does not have to be defined at
333 the time of this invocation.
334 interp transfer srcPath channelId destPath
336 Causes the IO channel identified by channelId to become avail‐
337 able in the interpreter identified by destPath and unavailable
338 in the interpreter identified by srcPath.
339
341 For each slave interpreter created with the interp command, a new Tcl
342 command is created in the master interpreter with the same name as the
343 new interpreter. This command may be used to invoke various operations
344 on the interpreter. It has the following general form:
345 slave command ?arg arg ...?
347 Slave is the name of the interpreter, and command and the args deter‐
349 mine the exact behavior of the command. The valid forms of this com‐
350 mand are:
351 slave aliases
353 Returns a Tcl list whose elements are the tokens of all the
354 aliases in slave. The tokens correspond to the values returned
355 when the aliases were created (which may not be the same as the
356 current names of the commands).
357 slave alias srcToken
359 Returns a Tcl list whose elements are the targetCmd and args
360 associated with the alias represented by srcToken (this is the
361 value returned when the alias was created; it is possible that
362 the actual source command in the slave is different from srcTo‐
363 ken).
364 slave alias srcToken {}
366 Deletes the alias for srcToken in the slave interpreter. srcTo‐
367 ken refers to the value returned when the alias was created; if
368 the source command has been renamed, the renamed command will be
369 deleted.
370 slave alias srcCmd targetCmd ?arg ..?
372 Creates an alias such that whenever srcCmd is invoked in slave,
373 targetCmd is invoked in the master. The arg arguments will be
374 passed to targetCmd as additional arguments, prepended before
375 any arguments passed in the invocation of srcCmd. See ALIAS
376 INVOCATION below for details. The command returns a token that
377 uniquely identifies the command created srcCmd, even if the com‐
378 mand is renamed afterwards. The token may but does not have to
379 be equal to srcCmd.
380 slave bgerror ?cmdPrefix?
382 This command either gets or sets the current background excep‐
383 tion handler for the slave interpreter. If cmdPrefix is absent,
384 the current background exception handler is returned, and if it
385 is present, it is a list of words (of minimum length one) that
386 describes what to set the interpreter's background exception
387 handler to. See the BACKGROUND EXCEPTION HANDLING section for
388 more details.
389 slave eval arg ?arg ..?
391 This command concatenates all of the arg arguments in the same
392 fashion as the concat command, then evaluates the resulting
393 string as a Tcl script in slave. The result of this evaluation
394 (including all return options, such as -errorinfo and -errorcode
395 information, if an error occurs) is returned to the invoking
396 interpreter. Note that the script will be executed in the cur‐
397 rent context stack frame of slave; this is so that the implemen‐
398 tations (in a master interpreter) of aliases in a slave inter‐
399 preter can execute scripts in the slave that find out informa‐
400 tion about the slave's current state and stack frame.
401 slave expose hiddenName ?exposedCmdName?
403 This command exposes the hidden command hiddenName, eventually
404 bringing it back under a new exposedCmdName name (this name is
405 currently accepted only if it is a valid global name space name
406 without any ::), in slave. If an exposed command with the tar‐
407 geted name already exists, this command fails. For more details
408 on hidden commands, see HIDDEN COMMANDS, below.
409 slave hide exposedCmdName ?hiddenCmdName?
411 This command hides the exposed command exposedCmdName, renaming
412 it to the hidden command hiddenCmdName, or keeping the same name
413 if the argument is not given, in the slave interpreter. If a
414 hidden command with the targeted name already exists, this com‐
415 mand fails. Currently both exposedCmdName and hiddenCmdName can
416 not contain namespace qualifiers, or an error is raised. Com‐
417 mands to be hidden are looked up in the global namespace even if
418 the current namespace is not the global one. This prevents
419 slaves from fooling a master interpreter into hiding the wrong
420 command, by making the current namespace be different from the
421 global one. For more details on hidden commands, see HIDDEN
422 COMMANDS, below.
423 slave hidden
425 Returns a list of the names of all hidden commands in slave.
426 slave invokehidden ?-option ...? hiddenName ?arg ..?
428 This command invokes the hidden command hiddenName with the sup‐
429 plied arguments, in slave. No substitutions or evaluations are
430 applied to the arguments. Three -options are supported, all of
431 which start with -: -namespace (which takes a single argument
432 afterwards, nsName), -global, and --. If the -namespace flag is
433 given, the hidden command is invoked in the specified namespace
434 in the slave. If the -global flag is given, the command is
435 invoked at the global level in the slave; otherwise it is
436 invoked at the current call frame and can access local variables
437 in that or outer call frames. The -- flag allows the hiddenCmd‐
438 Name argument to start with a “-” character, and is otherwise
439 unnecessary. If both the -namespace and -global flags are
440 given, the -namespace flag is ignored. Note that the hidden
441 command will be executed (by default) in the current context
442 stack frame of slave. For more details on hidden commands, see
443 HIDDEN COMMANDS, below.
444 slave issafe
446 Returns 1 if the slave interpreter is safe, 0 otherwise.
447 slave limit limitType ?-option? ?value ...?
449 Sets up, manipulates and queries the configuration of the
450 resource limit limitType for the slave interpreter. If no
451 -option is specified, return the current configuration of the
452 limit. If -option is the sole argument, return the value of
453 that option. Otherwise, a list of -option/value argument pairs
454 must supplied. See RESOURCE LIMITS below for a more detailed
455 explanation of what limits and options are supported.
456 slave marktrusted
458 Marks the slave interpreter as trusted. Can only be invoked by a
459 trusted interpreter. This command does not expose any hidden
460 commands in the slave interpreter. The command has no effect if
461 the slave is already trusted.
462 slave recursionlimit ?newlimit?
464 Returns the maximum allowable nesting depth for the slave inter‐
465 preter. If newlimit is specified, the recursion limit in slave
466 will be set so that nesting of more than newlimit calls to
467 Tcl_Eval() and related procedures in slave will return an error.
468 The newlimit value is also returned. The newlimit value must be
469 a positive integer between 1 and the maximum value of a non-long
470 integer on the platform.
471 The command sets the maximum size of the Tcl call stack only. It
473 cannot by itself prevent stack overflows on the C stack being
474 used by the application. If your machine has a limit on the size
475 of the C stack, you may get stack overflows before reaching the
476 limit set by the command. If this happens, see if there is a
477 mechanism in your system for increasing the maximum size of the
478 C stack.
479
481 A safe interpreter is one with restricted functionality, so that is
482 safe to execute an arbitrary script from your worst enemy without fear
483 of that script damaging the enclosing application or the rest of your
484 computing environment. In order to make an interpreter safe, certain
485 commands and variables are removed from the interpreter. For example,
486 commands to create files on disk are removed, and the exec command is
487 removed, since it could be used to cause damage through subprocesses.
488 Limited access to these facilities can be provided, by creating aliases
489 to the master interpreter which check their arguments carefully and
490 provide restricted access to a safe subset of facilities. For example,
491 file creation might be allowed in a particular subdirectory and subpro‐
492 cess invocation might be allowed for a carefully selected and fixed set
493 of programs.
494 A safe interpreter is created by specifying the -safe switch to the
496 interp create command. Furthermore, any slave created by a safe inter‐
497 preter will also be safe.
498 A safe interpreter is created with exactly the following set of built-
500 in commands:
501 after append apply array
503 binary break catch chan
504 clock close concat continue
505 dict eof error eval
506 expr fblocked fcopy fileevent
507 flush for foreach format
508 gets global if incr
509 info interp join lappend
510 lassign lindex linsert list
511 llength lrange lrepeat lreplace
512 lsearch lset lsort namespace
513 package pid proc puts
514 read regexp regsub rename
515 return scan seek set
516 split string subst switch
517 tell time trace unset
518 update uplevel upvar variable
519 vwait while
520 The following commands are hidden by interp create when it creates a
522 safe interpreter:
523 cd encoding exec exit
525 fconfigure file glob load
526 open pwd socket source
527 unload
528 These commands can be recreated later as Tcl procedures or aliases, or
530 re-exposed by interp expose.
531 The following commands from Tcl's library of support procedures are not
533 present in a safe interpreter:
534 auto_exec_ok auto_import auto_load
536 auto_load_index auto_qualify unknown
537 Note in particular that safe interpreters have no default unknown com‐
539 mand, so Tcl's default autoloading facilities are not available.
540 Autoload access to Tcl's commands that are normally autoloaded:
541 auto_mkindex auto_mkindex_old
543 auto_reset history
544 parray pkg_mkIndex
545 ::pkg::create ::safe::interpAddToAccessPath
546 ::safe::interpCreate ::safe::interpConfigure
547 ::safe::interpDelete ::safe::interpFindInAccessPath
548 ::safe::interpInit ::safe::setLogCmd
549 tcl_endOfWord tcl_findLibrary
550 tcl_startOfNextWord tcl_startOfPreviousWord
551 tcl_wordBreakAfter tcl_wordBreakBefore
552 can only be provided by explicit definition of an unknown command in
554 the safe interpreter. This will involve exposing the source command.
555 This is most easily accomplished by creating the safe interpreter with
556 Tcl's Safe-Tcl mechanism. Safe-Tcl provides safe versions of source,
557 load, and other Tcl commands needed to support autoloading of commands
558 and the loading of packages.
559 In addition, the env variable is not present in a safe interpreter, so
561 it cannot share environment variables with other interpreters. The env
562 variable poses a security risk, because users can store sensitive
563 information in an environment variable. For example, the PGP manual
564 recommends storing the PGP private key protection password in the envi‐
565 ronment variable PGPPASS. Making this variable available to untrusted
566 code executing in a safe interpreter would incur a security risk.
567 If extensions are loaded into a safe interpreter, they may also
569 restrict their own functionality to eliminate unsafe commands. For a
570 discussion of management of extensions for safety see the manual
571 entries for Safe-Tcl and the load Tcl command.
572 A safe interpreter may not alter the recursion limit of any inter‐
574 preter, including itself.
575
577 The alias mechanism has been carefully designed so that it can be used
578 safely when an untrusted script is executing in a safe slave and the
579 target of the alias is a trusted master. The most important thing in
580 guaranteeing safety is to ensure that information passed from the slave
581 to the master is never evaluated or substituted in the master; if this
582 were to occur, it would enable an evil script in the slave to invoke
583 arbitrary functions in the master, which would compromise security.
584 When the source for an alias is invoked in the slave interpreter, the
586 usual Tcl substitutions are performed when parsing that command. These
587 substitutions are carried out in the source interpreter just as they
588 would be for any other command invoked in that interpreter. The com‐
589 mand procedure for the source command takes its arguments and merges
590 them with the targetCmd and args for the alias to create a new array of
591 arguments. If the words of srcCmd were “srcCmd arg1 arg2 ... argN”,
592 the new set of words will be “targetCmd arg arg ... arg arg1 arg2 ...
593 argN”, where targetCmd and args are the values supplied when the alias
594 was created. TargetCmd is then used to locate a command procedure in
595 the target interpreter, and that command procedure is invoked with the
596 new set of arguments. An error occurs if there is no command named
597 targetCmd in the target interpreter. No additional substitutions are
598 performed on the words: the target command procedure is invoked
599 directly, without going through the normal Tcl evaluation mechanism.
600 Substitutions are thus performed on each word exactly once: targetCmd
601 and args were substituted when parsing the command that created the
602 alias, and arg1 - argN are substituted when the alias's source command
603 is parsed in the source interpreter.
604 When writing the targetCmds for aliases in safe interpreters, it is
606 very important that the arguments to that command never be evaluated or
607 substituted, since this would provide an escape mechanism whereby the
608 slave interpreter could execute arbitrary code in the master. This in
609 turn would compromise the security of the system.
610
612 Safe interpreters greatly restrict the functionality available to Tcl
613 programs executing within them. Allowing the untrusted Tcl program to
614 have direct access to this functionality is unsafe, because it can be
615 used for a variety of attacks on the environment. However, there are
616 times when there is a legitimate need to use the dangerous functional‐
617 ity in the context of the safe interpreter. For example, sometimes a
618 program must be sourced into the interpreter. Another example is Tk,
619 where windows are bound to the hierarchy of windows for a specific
620 interpreter; some potentially dangerous functions, e.g. window manage‐
621 ment, must be performed on these windows within the interpreter con‐
622 text.
623 The interp command provides a solution to this problem in the form of
625 hidden commands. Instead of removing the dangerous commands entirely
626 from a safe interpreter, these commands are hidden so they become
627 unavailable to Tcl scripts executing in the interpreter. However, such
628 hidden commands can be invoked by any trusted ancestor of the safe
629 interpreter, in the context of the safe interpreter, using interp
630 invoke. Hidden commands and exposed commands reside in separate name
631 spaces. It is possible to define a hidden command and an exposed com‐
632 mand by the same name within one interpreter.
633 Hidden commands in a slave interpreter can be invoked in the body of
635 procedures called in the master during alias invocation. For example,
636 an alias for source could be created in a slave interpreter. When it is
637 invoked in the slave interpreter, a procedure is called in the master
638 interpreter to check that the operation is allowable (e.g. it asks to
639 source a file that the slave interpreter is allowed to access). The
640 procedure then it invokes the hidden source command in the slave inter‐
641 preter to actually source in the contents of the file. Note that two
642 commands named source exist in the slave interpreter: the alias, and
643 the hidden command.
644 Because a master interpreter may invoke a hidden command as part of
646 handling an alias invocation, great care must be taken to avoid evalu‐
647 ating any arguments passed in through the alias invocation. Otherwise,
648 malicious slave interpreters could cause a trusted master interpreter
649 to execute dangerous commands on their behalf. See the section on ALIAS
650 INVOCATION for a more complete discussion of this topic. To help avoid
651 this problem, no substitutions or evaluations are applied to arguments
652 of interp invokehidden.
653 Safe interpreters are not allowed to invoke hidden commands in them‐
655 selves or in their descendants. This prevents safe slaves from gaining
656 access to hidden functionality in themselves or their descendants.
657 The set of hidden commands in an interpreter can be manipulated by a
659 trusted interpreter using interp expose and interp hide. The interp
660 expose command moves a hidden command to the set of exposed commands in
661 the interpreter identified by path, potentially renaming the command in
662 the process. If an exposed command by the targeted name already exists,
663 the operation fails. Similarly, interp hide moves an exposed command to
664 the set of hidden commands in that interpreter. Safe interpreters are
665 not allowed to move commands between the set of hidden and exposed com‐
666 mands, in either themselves or their descendants.
667 Currently, the names of hidden commands cannot contain namespace quali‐
669 fiers, and you must first rename a command in a namespace to the global
670 namespace before you can hide it. Commands to be hidden by interp hide
671 are looked up in the global namespace even if the current namespace is
672 not the global one. This prevents slaves from fooling a master inter‐
673 preter into hiding the wrong command, by making the current namespace
674 be different from the global one.
675
677 Every interpreter has two kinds of resource limits that may be imposed
678 by any master interpreter upon its slaves. Command limits (of type com‐
679 mand) restrict the total number of Tcl commands that may be executed by
680 an interpreter (as can be inspected via the info cmdcount command), and
681 time limits (of type time) place a limit by which execution within the
682 interpreter must complete. Note that time limits are expressed as abso‐
683 lute times (as in clock seconds) and not relative times (as in after)
684 because they may be modified after creation.
685 When a limit is exceeded for an interpreter, first any handler call‐
687 backs defined by master interpreters are called. If those callbacks
688 increase or remove the limit, execution within the (previously) limited
689 interpreter continues. If the limit is still in force, an error is gen‐
690 erated at that point and normal processing of errors within the inter‐
691 preter (by the catch command) is disabled, so the error propagates out‐
692 wards (building a stack-trace as it goes) to the point where the lim‐
693 ited interpreter was invoked (e.g. by interp eval) where it becomes the
694 responsibility of the calling code to catch and handle.
695 LIMIT OPTIONS
697 Every limit has a number of options associated with it, some of which
698 are common across all kinds of limits, and others of which are particu‐
699 lar to the kind of limit.
700 -command
702 This option (common for all limit types) specifies (if non-
703 empty) a Tcl script to be executed in the global namespace of
704 the interpreter reading and writing the option when the particu‐
705 lar limit in the limited interpreter is exceeded. The callback
706 may modify the limit on the interpreter if it wishes the limited
707 interpreter to continue executing. If the callback generates an
708 exception, it is reported through the background exception mech‐
709 anism (see BACKGROUND EXCEPTION HANDLING). Note that the call‐
710 backs defined by one interpreter are completely isolated from
711 the callbacks defined by another, and that the order in which
712 those callbacks are called is undefined.
713 -granularity
715 This option (common for all limit types) specifies how fre‐
716 quently (out of the points when the Tcl interpreter is in a con‐
717 sistent state where limit checking is possible) that the limit
718 is actually checked. This allows the tuning of how frequently a
719 limit is checked, and hence how often the limit-checking over‐
720 head (which may be substantial in the case of time limits) is
721 incurred.
722 -milliseconds
724 This option specifies the number of milliseconds after the
725 moment defined in the -seconds option that the time limit will
726 fire. It should only ever be specified in conjunction with the
727 -seconds option (whether it was set previously or is being set
728 this invocation.)
729 -seconds
731 This option specifies the number of seconds after the epoch (see
732 clock seconds) that the time limit for the interpreter will be
733 triggered. The limit will be triggered at the start of the sec‐
734 ond unless specified at a sub-second level using the -millisec‐
735 onds option. This option may be the empty string, which indi‐
736 cates that a time limit is not set for the interpreter.
737 -value This option specifies the number of commands that the inter‐
739 preter may execute before triggering the command limit. This
740 option may be the empty string, which indicates that a command
741 limit is not set for the interpreter.
742 Where an interpreter with a resource limit set on it creates a slave
744 interpreter, that slave interpreter will have resource limits imposed
745 on it that are at least as restrictive as the limits on the creating
746 master interpreter. If the master interpreter of the limited master
747 wishes to relax these conditions, it should hide the interp command in
748 the child and then use aliases and the interp invokehidden subcommand
749 to provide such access as it chooses to the interp command to the lim‐
750 ited master as necessary.
751
753 When an exception happens in a situation where it cannot be reported
754 directly up the stack (e.g. when processing events in an update or
755 vwait call) the exception is instead reported through the background
756 exception handling mechanism. Every interpreter has a background
757 exception handler registered; the default exception handler arranges
758 for the bgerror command in the interpreter's global namespace to be
759 called, but other exception handlers may be installed and process back‐
760 ground exceptions in substantially different ways.
761 A background exception handler consists of a non-empty list of words to
763 which will be appended two further words at invocation time. The first
764 word will be the interpreter result at time of the exception, typically
765 an error message, and the second will be the dictionary of return
766 options at the time of the exception. These are the same values that
767 catch can capture when it controls script evaluation in a non-back‐
768 ground situation. The resulting list will then be executed in the
769 interpreter's global namespace without further substitutions being per‐
770 formed.
771
773 The safe interpreter mechanism is based on the Safe-Tcl prototype
774 implemented by Nathaniel Borenstein and Marshall Rose.
775
777 Creating and using an alias for a command in the current interpreter:
778 interp alias {} getIndex {} lsearch {alpha beta gamma delta}
780 set idx [getIndex delta]
781 Executing an arbitrary command in a safe interpreter where every invo‐
783 cation of lappend is logged:
784 set i [interp create -safe]
786 interp hide $i lappend
787 interp alias $i lappend {} loggedLappend $i
788 proc loggedLappend {i args} {
789 puts "logged invocation of lappend $args"
790 interp invokehidden $i lappend {*}$args
791 }
792 interp eval $i $someUntrustedScript
793 Setting a resource limit on an interpreter so that an infinite loop
795 terminates.
796 set i [interp create]
798 interp limit $i command -value 1000
799 interp eval $i {
800 set x 0
801 while {1} {
802 puts "Counting up... [incr x]"
803 }
804 }
805
807 bgerror(n), load(n), safe(n), Tcl_CreateSlave(3), Tcl_Eval(3),
808 Tcl_BackgroundException(3)
809
811 alias, master interpreter, safe interpreter, slave interpreter
812Tcl 8.6 interp(n)