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 a1
57 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 a,
94 which is a slave of the invoking interpreter. An empty list
95 specifies the interpreter invoking the command. srcCmd gives
96 the name of a new command, which will be created in the source
97 interpreter. TargetPath and targetCmd specify a target inter‐
98 preter and command, and the arg arguments, if any, specify addi‐
99 tional arguments to targetCmd which are prepended to any argu‐
100 ments specified in the invocation of srcCmd. TargetCmd may be
101 undefined at the time of this call, or it may already exist; it
102 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 error │
119 handler for the interpreter identified by path. If cmdPrefix is │
120 absent, the current background error handler is returned, and if │
121 it is present, it is a list of words (of minimum length one) │
122 that describes what to set the interpreter's background error │
123 to. See the BACKGROUND ERROR HANDLING section for more details.
124 interp create ?-safe? ?--? ?path?
126 Creates a slave interpreter identified by path and a new com‐
127 mand, called a slave command. The name of the slave command is
128 the last component of path. The new slave interpreter and the
129 slave command are created in the interpreter identified by the
130 path obtained by removing the last component from path. For
131 example, if path is a b c then a new slave interpreter and slave
132 command named c are created in the interpreter identified by the
133 path a b. The slave command may be used to manipulate the new
134 interpreter as described below. If path is omitted, Tcl creates
135 a unique name of the form interpx, where x is an integer, and
136 uses it for the interpreter and the slave command. If the -safe
137 switch is specified (or if the master interpreter is a safe
138 interpreter), the new slave interpreter will be created as a
139 safe interpreter with limited functionality; otherwise the slave
140 will include the full set of Tcl built-in commands and vari‐
141 ables. The -- switch can be used to mark the end of switches;
142 it may be needed if path is an unusual value such as -safe. The
143 result of the command is the name of the new interpreter. The
144 name of a slave interpreter must be unique among all the slaves
145 for its master; an error occurs if a slave interpreter by the
146 given name already exists in this master. The initial recursion
147 limit of the slave interpreter is set to the current recursion
148 limit of its parent interpreter.
149 interp debug path ?-frame ?bool??
151 Controls whether frame-level stack information is captured in
152 the slave interpreter identified by path. If no arguments are
153 given, option and current setting are returned. If -frame is
154 given, the debug setting is set to the given boolean if provided
155 and the current setting is returned. This only effects the out‐
156 put of info frame, in that exact frame-level information for
157 command invocation at the bytecode level is only captured with
158 this setting on.
159 For example, with code like
161 proc mycontrol {... script} {
163 ...
164 uplevel 1 $script
165 ...
166 }
167 proc dosomething {...} {
169 ...
170 mycontrol {
171 somecode
172 }
173 }
174 the standard setting will provide a relative line number for the
176 command somecode and the relevant frame will be of type eval.
177 With frame-debug active on the other hand the tracking extends
178 so far that the system will be able to determine the file and
179 absolute line number of this command, and return a frame of type
180 source. This more exact information is paid for with slower exe‐
181 cution of all commands.
182 interp delete ?path ...?
184 Deletes zero or more interpreters given by the optional path
185 arguments, and for each interpreter, it also deletes its slaves.
186 The command also deletes the slave command for each interpreter
187 deleted. For each path argument, if no interpreter by that name
188 exists, the command raises an error.
189 interp eval path arg ?arg ...?
191 This command concatenates all of the arg arguments in the same
192 fashion as the concat command, then evaluates the resulting
193 string as a Tcl script in the slave interpreter identified by
194 path. The result of this evaluation (including all return
195 options, such as -errorinfo and -errorcode information, if an
196 error occurs) is returned to the invoking interpreter. Note
197 that the script will be executed in the current context stack
198 frame of the path interpreter; this is so that the implementa‐
199 tions (in a master interpreter) of aliases in a slave inter‐
200 preter can execute scripts in the slave that find out informa‐
201 tion about the slave's current state and stack frame.
202 interp exists path
204 Returns 1 if a slave interpreter by the specified path exists in
205 this master, 0 otherwise. If path is omitted, the invoking
206 interpreter is used.
207 interp expose path hiddenName ?exposedCmdName?
209 Makes the hidden command hiddenName exposed, eventually bringing
210 it back under a new exposedCmdName name (this name is currently
211 accepted only if it is a valid global name space name without
212 any ::), in the interpreter denoted by path. If an exposed com‐
213 mand with the targeted name already exists, this command fails.
214 Hidden commands are explained in more detail in HIDDEN COMMANDS,
215 below.
216 interp hide path exposedCmdName ?hiddenCmdName?
218 Makes the exposed command exposedCmdName hidden, renaming it to
219 the hidden command hiddenCmdName, or keeping the same name if
220 hiddenCmdName is not given, in the interpreter denoted by path.
221 If a hidden command with the targeted name already exists, this
222 command fails. Currently both exposedCmdName and hiddenCmdName
223 can not contain namespace qualifiers, or an error is raised.
224 Commands to be hidden by interp hide are looked up in the global
225 namespace even if the current namespace is not the global one.
226 This prevents slaves from fooling a master interpreter into hid‐
227 ing the wrong command, by making the current namespace be dif‐
228 ferent from the global one. Hidden commands are explained in
229 more detail in HIDDEN COMMANDS, below.
230 interp hidden path
232 Returns a list of the names of all hidden commands in the inter‐
233 preter identified by path.
234 interp invokehidden path ?-option ...? hiddenCmdName ?arg ...?
236 Invokes the hidden command hiddenCmdName with the arguments sup‐
237 plied in the interpreter denoted by path. No substitutions or
238 evaluation are applied to the arguments. Three -options are sup‐
239 ported, all of which start with -: -namespace (which takes a
240 single argument afterwards, nsName), -global, and --. If the
241 -namespace flag is present, the hidden command is invoked in the
242 namespace called nsName in the target interpreter. If the
243 -global flag is present, the hidden command is invoked at the
244 global level in the target interpreter; otherwise it is invoked
245 at the current call frame and can access local variables in that
246 and outer call frames. The -- flag allows the hiddenCmdName
247 argument to start with a “-” character, and is otherwise unnec‐
248 essary. If both the -namespace and -global flags are present,
249 the -namespace flag is ignored. Note that the hidden command
250 will be executed (by default) in the current context stack frame
251 of the path interpreter. Hidden commands are explained in more
252 detail in HIDDEN COMMANDS, below.
253 interp limit path limitType ?-option? ?value ...?
255 Sets up, manipulates and queries the configuration of the │
256 resource limit limitType for the interpreter denoted by path. │
257 If no -option is specified, return the current configuration of │
258 the limit. If -option is the sole argument, return the value of │
259 that option. Otherwise, a list of -option/value argument pairs │
260 must supplied. See RESOURCE LIMITS below for a more detailed │
261 explanation of what limits and options are supported.
262 interp issafe ?path?
264 Returns 1 if the interpreter identified by the specified path is
265 safe, 0 otherwise.
266 interp marktrusted path
268 Marks the interpreter identified by path as trusted. Does not
269 expose the hidden commands. This command can only be invoked
270 from a trusted interpreter. The command has no effect if the
271 interpreter identified by path is already trusted.
272 interp recursionlimit path ?newlimit?
274 Returns the maximum allowable nesting depth for the interpreter
275 specified by path. If newlimit is specified, the interpreter
276 recursion limit will be set so that nesting of more than
277 newlimit calls to Tcl_Eval() and related procedures in that
278 interpreter will return an error. The newlimit value is also
279 returned. The newlimit value must be a positive integer between
280 1 and the maximum value of a non-long integer on the platform.
281 The command sets the maximum size of the Tcl call stack only. It
283 cannot by itself prevent stack overflows on the C stack being
284 used by the application. If your machine has a limit on the size
285 of the C stack, you may get stack overflows before reaching the
286 limit set by the command. If this happens, see if there is a
287 mechanism in your system for increasing the maximum size of the
288 C stack.
289 interp share srcPath channelId destPath
291 Causes the IO channel identified by channelId to become shared
292 between the interpreter identified by srcPath and the inter‐
293 preter identified by destPath. Both interpreters have the same
294 permissions on the IO channel. Both interpreters must close it
295 to close the underlying IO channel; IO channels accessible in an
296 interpreter are automatically closed when an interpreter is
297 destroyed.
298 interp slaves ?path?
300 Returns a Tcl list of the names of all the slave interpreters
301 associated with the interpreter identified by path. If path is
302 omitted, the invoking interpreter is used.
303 interp target path alias
305 Returns a Tcl list describing the target interpreter for an
306 alias. The alias is specified with an interpreter path and
307 source command name, just as in interp alias above. The name of
308 the target interpreter is returned as an interpreter path, rela‐
309 tive to the invoking interpreter. If the target interpreter for
310 the alias is the invoking interpreter then an empty list is
311 returned. If the target interpreter for the alias is not the
312 invoking interpreter or one of its descendants then an error is
313 generated. The target command does not have to be defined at
314 the time of this invocation.
315 interp transfer srcPath channelId destPath
317 Causes the IO channel identified by channelId to become avail‐
318 able in the interpreter identified by destPath and unavailable
319 in the interpreter identified by srcPath.
320
322 For each slave interpreter created with the interp command, a new Tcl
323 command is created in the master interpreter with the same name as the
324 new interpreter. This command may be used to invoke various operations
325 on the interpreter. It has the following general form:
326 slave command ?arg arg ...?
327 Slave is the name of the interpreter, and command and the args deter‐
328 mine the exact behavior of the command. The valid forms of this com‐
329 mand are:
330 slave aliases
332 Returns a Tcl list whose elements are the tokens of all the
333 aliases in slave. The tokens correspond to the values returned
334 when the aliases were created (which may not be the same as the
335 current names of the commands).
336 slave alias srcToken
338 Returns a Tcl list whose elements are the targetCmd and args
339 associated with the alias represented by srcToken (this is the
340 value returned when the alias was created; it is possible that
341 the actual source command in the slave is different from srcTo‐
342 ken).
343 slave alias srcToken {}
345 Deletes the alias for srcToken in the slave interpreter. srcTo‐
346 ken refers to the value returned when the alias was created; if
347 the source command has been renamed, the renamed command will be
348 deleted.
349 slave alias srcCmd targetCmd ?arg ..?
351 Creates an alias such that whenever srcCmd is invoked in slave,
352 targetCmd is invoked in the master. The arg arguments will be
353 passed to targetCmd as additional arguments, prepended before
354 any arguments passed in the invocation of srcCmd. See ALIAS
355 INVOCATION below for details. The command returns a token that
356 uniquely identifies the command created srcCmd, even if the com‐
357 mand is renamed afterwards. The token may but does not have to
358 be equal to srcCmd.
359 slave bgerror ?cmdPrefix?
361 This command either gets or sets the current background error │
362 handler for the slave interpreter. If cmdPrefix is absent, the │
363 current background error handler is returned, and if it is │
364 present, it is a list of words (of minimum length one) that │
365 describes what to set the interpreter's background error to. See │
366 the BACKGROUND ERROR HANDLING section for more details.
367 slave eval arg ?arg ..?
369 This command concatenates all of the arg arguments in the same
370 fashion as the concat command, then evaluates the resulting
371 string as a Tcl script in slave. The result of this evaluation
372 (including all return options, such as -errorinfo and -errorcode
373 information, if an error occurs) is returned to the invoking
374 interpreter. Note that the script will be executed in the cur‐
375 rent context stack frame of slave; this is so that the implemen‐
376 tations (in a master interpreter) of aliases in a slave inter‐
377 preter can execute scripts in the slave that find out informa‐
378 tion about the slave's current state and stack frame.
379 slave expose hiddenName ?exposedCmdName?
381 This command exposes the hidden command hiddenName, eventually
382 bringing it back under a new exposedCmdName name (this name is
383 currently accepted only if it is a valid global name space name
384 without any ::), in slave. If an exposed command with the tar‐
385 geted name already exists, this command fails. For more details
386 on hidden commands, see HIDDEN COMMANDS, below.
387 slave hide exposedCmdName ?hiddenCmdName?
389 This command hides the exposed command exposedCmdName, renaming
390 it to the hidden command hiddenCmdName, or keeping the same name
391 if the argument is not given, in the slave interpreter. If a
392 hidden command with the targeted name already exists, this com‐
393 mand fails. Currently both exposedCmdName and hiddenCmdName can
394 not contain namespace qualifiers, or an error is raised. Com‐
395 mands to be hidden are looked up in the global namespace even if
396 the current namespace is not the global one. This prevents
397 slaves from fooling a master interpreter into hiding the wrong
398 command, by making the current namespace be different from the
399 global one. For more details on hidden commands, see HIDDEN
400 COMMANDS, below.
401 slave hidden
403 Returns a list of the names of all hidden commands in slave.
404 slave invokehidden ?-option ...? hiddenName ?arg ..?
406 This command invokes the hidden command hiddenName with the sup‐
407 plied arguments, in slave. No substitutions or evaluations are
408 applied to the arguments. Three -options are supported, all of
409 which start with -: -namespace (which takes a single argument
410 afterwards, nsName), -global, and --. If the -namespace flag is
411 given, the hidden command is invoked in the specified namespace
412 in the slave. If the -global flag is given, the command is
413 invoked at the global level in the slave; otherwise it is
414 invoked at the current call frame and can access local variables
415 in that or outer call frames. The -- flag allows the hiddenCmd‐
416 Name argument to start with a “-” character, and is otherwise
417 unnecessary. If both the -namespace and -global flags are
418 given, the -namespace flag is ignored. Note that the hidden
419 command will be executed (by default) in the current context
420 stack frame of slave. For more details on hidden commands, see
421 HIDDEN COMMANDS, below.
422 slave issafe
424 Returns 1 if the slave interpreter is safe, 0 otherwise.
425 slave limit limitType ?-option? ?value ...?
427 Sets up, manipulates and queries the configuration of the │
428 resource limit limitType for the slave interpreter. If no │
429 -option is specified, return the current configuration of the │
430 limit. If -option is the sole argument, return the value of │
431 that option. Otherwise, a list of -option/value argument pairs │
432 must supplied. See RESOURCE LIMITS below for a more detailed │
433 explanation of what limits and options are supported.
434 slave marktrusted
436 Marks the slave interpreter as trusted. Can only be invoked by a
437 trusted interpreter. This command does not expose any hidden
438 commands in the slave interpreter. The command has no effect if
439 the slave is already trusted.
440 slave recursionlimit ?newlimit?
442 Returns the maximum allowable nesting depth for the slave inter‐
443 preter. If newlimit is specified, the recursion limit in slave
444 will be set so that nesting of more than newlimit calls to
445 Tcl_Eval() and related procedures in slave will return an error.
446 The newlimit value is also returned. The newlimit value must be
447 a positive integer between 1 and the maximum value of a non-long
448 integer on the platform.
449 The command sets the maximum size of the Tcl call stack only. It
451 cannot by itself prevent stack overflows on the C stack being
452 used by the application. If your machine has a limit on the size
453 of the C stack, you may get stack overflows before reaching the
454 limit set by the command. If this happens, see if there is a
455 mechanism in your system for increasing the maximum size of the
456 C stack.
457
459 A safe interpreter is one with restricted functionality, so that is
460 safe to execute an arbitrary script from your worst enemy without fear
461 of that script damaging the enclosing application or the rest of your
462 computing environment. In order to make an interpreter safe, certain
463 commands and variables are removed from the interpreter. For example,
464 commands to create files on disk are removed, and the exec command is
465 removed, since it could be used to cause damage through subprocesses.
466 Limited access to these facilities can be provided, by creating aliases
467 to the master interpreter which check their arguments carefully and
468 provide restricted access to a safe subset of facilities. For example,
469 file creation might be allowed in a particular subdirectory and subpro‐
470 cess invocation might be allowed for a carefully selected and fixed set
471 of programs.
472 A safe interpreter is created by specifying the -safe switch to the
474 interp create command. Furthermore, any slave created by a safe inter‐
475 preter will also be safe.
476 A safe interpreter is created with exactly the following set of built-
478 in commands: after append apply array
479 binary break catch chan clock close con‐
480 cat continue dict eof error eval
481 expr fblocked fcopy fileevent
482 flush for foreach format
483 gets global if incr
484 info interp join lappend lassign lin‐
485 dex linsert list llength lrange lrepeat lreplace
486 lsearch lset lsort namespace pack‐
487 age pid proc puts read regexp reg‐
488 sub rename return scan seek set
489 split string subst switch
490 tell time trace unset
491 update uplevel upvar variable vwait while The fol‐
492 lowing commands are hidden by interp create when it creates a safe
493 interpreter: cd encoding exec exit fconfig‐
494 ure file glob load
495 open pwd socket source unload These commands can be
496 recreated later as Tcl procedures or aliases, or re-exposed by interp
497 expose.
498 The following commands from Tcl's library of support procedures are not
500 present in a safe interpreter:
501 auto_exec_ok auto_import auto_load auto_load_index auto_qual‐
502 ify unknown Note in particular that safe interpreters have no
503 default unknown command, so Tcl's default autoloading facilities are
504 not available. Autoload access to Tcl's commands that are normally
505 autoloaded: auto_mkindex auto_mkindex_old
506 auto_reset history parray pkg_mkIndex
507 ::pkg::create ::safe::interpAddToAccessPath ::safe::interpCre‐
508 ate ::safe::interpConfigure ::safe::interpDelete ::safe::interpFindI‐
509 nAccessPath ::safe::interpInit ::safe::setLogCmd tcl_endOf‐
510 Word tcl_findLibrary tcl_startOfNextWord tcl_startOfPrevious‐
511 Word tcl_wordBreakAfter tcl_wordBreakBefore can only be provided by
512 explicit definition of an unknown command in the safe interpreter.
513 This will involve exposing the source command. This is most easily
514 accomplished by creating the safe interpreter with Tcl's Safe-Tcl mech‐
515 anism. Safe-Tcl provides safe versions of source, load, and other Tcl
516 commands needed to support autoloading of commands and the loading of
517 packages.
518 In addition, the env variable is not present in a safe interpreter, so
520 it cannot share environment variables with other interpreters. The env
521 variable poses a security risk, because users can store sensitive
522 information in an environment variable. For example, the PGP manual
523 recommends storing the PGP private key protection password in the envi‐
524 ronment variable PGPPASS. Making this variable available to untrusted
525 code executing in a safe interpreter would incur a security risk.
526 If extensions are loaded into a safe interpreter, they may also
528 restrict their own functionality to eliminate unsafe commands. For a
529 discussion of management of extensions for safety see the manual
530 entries for Safe-Tcl and the load Tcl command.
531 A safe interpreter may not alter the recursion limit of any inter‐
533 preter, including itself.
534
536 The alias mechanism has been carefully designed so that it can be used
537 safely when an untrusted script is executing in a safe slave and the
538 target of the alias is a trusted master. The most important thing in
539 guaranteeing safety is to ensure that information passed from the slave
540 to the master is never evaluated or substituted in the master; if this
541 were to occur, it would enable an evil script in the slave to invoke
542 arbitrary functions in the master, which would compromise security.
543 When the source for an alias is invoked in the slave interpreter, the
545 usual Tcl substitutions are performed when parsing that command. These
546 substitutions are carried out in the source interpreter just as they
547 would be for any other command invoked in that interpreter. The com‐
548 mand procedure for the source command takes its arguments and merges
549 them with the targetCmd and args for the alias to create a new array of
550 arguments. If the words of srcCmd were “srcCmd arg1 arg2 ... argN”,
551 the new set of words will be “targetCmd arg arg ... arg arg1 arg2 ...
552 argN”, where targetCmd and args are the values supplied when the alias
553 was created. TargetCmd is then used to locate a command procedure in
554 the target interpreter, and that command procedure is invoked with the
555 new set of arguments. An error occurs if there is no command named
556 targetCmd in the target interpreter. No additional substitutions are
557 performed on the words: the target command procedure is invoked
558 directly, without going through the normal Tcl evaluation mechanism.
559 Substitutions are thus performed on each word exactly once: targetCmd
560 and args were substituted when parsing the command that created the
561 alias, and arg1 - argN are substituted when the alias's source command
562 is parsed in the source interpreter.
563 When writing the targetCmds for aliases in safe interpreters, it is
565 very important that the arguments to that command never be evaluated or
566 substituted, since this would provide an escape mechanism whereby the
567 slave interpreter could execute arbitrary code in the master. This in
568 turn would compromise the security of the system.
569
571 Safe interpreters greatly restrict the functionality available to Tcl
572 programs executing within them. Allowing the untrusted Tcl program to
573 have direct access to this functionality is unsafe, because it can be
574 used for a variety of attacks on the environment. However, there are
575 times when there is a legitimate need to use the dangerous functional‐
576 ity in the context of the safe interpreter. For example, sometimes a
577 program must be sourced into the interpreter. Another example is Tk,
578 where windows are bound to the hierarchy of windows for a specific
579 interpreter; some potentially dangerous functions, e.g. window manage‐
580 ment, must be performed on these windows within the interpreter con‐
581 text.
582 The interp command provides a solution to this problem in the form of
584 hidden commands. Instead of removing the dangerous commands entirely
585 from a safe interpreter, these commands are hidden so they become
586 unavailable to Tcl scripts executing in the interpreter. However, such
587 hidden commands can be invoked by any trusted ancestor of the safe
588 interpreter, in the context of the safe interpreter, using interp
589 invoke. Hidden commands and exposed commands reside in separate name
590 spaces. It is possible to define a hidden command and an exposed com‐
591 mand by the same name within one interpreter.
592 Hidden commands in a slave interpreter can be invoked in the body of
594 procedures called in the master during alias invocation. For example,
595 an alias for source could be created in a slave interpreter. When it is
596 invoked in the slave interpreter, a procedure is called in the master
597 interpreter to check that the operation is allowable (e.g. it asks to
598 source a file that the slave interpreter is allowed to access). The
599 procedure then it invokes the hidden source command in the slave inter‐
600 preter to actually source in the contents of the file. Note that two
601 commands named source exist in the slave interpreter: the alias, and
602 the hidden command.
603 Because a master interpreter may invoke a hidden command as part of
605 handling an alias invocation, great care must be taken to avoid evalu‐
606 ating any arguments passed in through the alias invocation. Otherwise,
607 malicious slave interpreters could cause a trusted master interpreter
608 to execute dangerous commands on their behalf. See the section on ALIAS
609 INVOCATION for a more complete discussion of this topic. To help avoid
610 this problem, no substitutions or evaluations are applied to arguments
611 of interp invokehidden.
612 Safe interpreters are not allowed to invoke hidden commands in them‐
614 selves or in their descendants. This prevents safe slaves from gaining
615 access to hidden functionality in themselves or their descendants.
616 The set of hidden commands in an interpreter can be manipulated by a
618 trusted interpreter using interp expose and interp hide. The interp
619 expose command moves a hidden command to the set of exposed commands in
620 the interpreter identified by path, potentially renaming the command in
621 the process. If an exposed command by the targeted name already exists,
622 the operation fails. Similarly, interp hide moves an exposed command to
623 the set of hidden commands in that interpreter. Safe interpreters are
624 not allowed to move commands between the set of hidden and exposed com‐
625 mands, in either themselves or their descendants.
626 Currently, the names of hidden commands cannot contain namespace quali‐
628 fiers, and you must first rename a command in a namespace to the global
629 namespace before you can hide it. Commands to be hidden by interp hide
630 are looked up in the global namespace even if the current namespace is
631 not the global one. This prevents slaves from fooling a master inter‐
632 preter into hiding the wrong command, by making the current namespace
633 be different from the global one.
634
636 Every interpreter has two kinds of resource limits that may be imposed │
637 by any master interpreter upon its slaves. Command limits (of type com‐ │
638 mand) restrict the total number of Tcl commands that may be executed by │
639 an interpreter (as can be inspected via the info cmdcount command), and │
640 time limits (of type time) place a limit by which execution within the │
641 interpreter must complete. Note that time limits are expressed as abso‐ │
642 lute times (as in clock seconds) and not relative times (as in after) │
643 because they may be modified after creation. │
644 When a limit is exceeded for an interpreter, first any handler call‐ │
646 backs defined by master interpreters are called. If those callbacks │
647 increase or remove the limit, execution within the (previously) limited │
648 interpreter continues. If the limit is still in force, an error is gen‐ │
649 erated at that point and normal processing of errors within the inter‐ │
650 preter (by the catch command) is disabled, so the error propagates out‐ │
651 wards (building a stack-trace as it goes) to the point where the lim‐ │
652 ited interpreter was invoked (e.g. by interp eval) where it becomes the │
653 responsibility of the calling code to catch and handle. │
654 LIMIT OPTIONS │
656 Every limit has a number of options associated with it, some of which │
657 are common across all kinds of limits, and others of which are particu‐ │
658 lar to the kind of limit.
659 -command
661 This option (common for all limit types) specifies (if non- │
662 empty) a Tcl script to be executed in the global namespace of │
663 the interpreter reading and writing the option when the particu‐ │
664 lar limit in the limited interpreter is exceeded. The callback │
665 may modify the limit on the interpreter if it wishes the limited │
666 interpreter to continue executing. If the callback generates an │
667 error, it is reported through the background error mechanism │
668 (see BACKGROUND ERROR HANDLING). Note that the callbacks defined │
669 by one interpreter are completely isolated from the callbacks │
670 defined by another, and that the order in which those callbacks │
671 are called is undefined.
672 -granularity
674 This option (common for all limit types) specifies how fre‐ │
675 quently (out of the points when the Tcl interpreter is in a con‐ │
676 sistent state where limit checking is possible) that the limit │
677 is actually checked. This allows the tuning of how frequently a │
678 limit is checked, and hence how often the limit-checking over‐ │
679 head (which may be substantial in the case of time limits) is │
680 incurred.
681 -milliseconds
683 This option specifies the number of milliseconds after the │
684 moment defined in the -seconds option that the time limit will │
685 fire. It should only ever be specified in conjunction with the │
686 -seconds option (whether it was set previously or is being set │
687 this invocation.)
688 -seconds
690 This option specifies the number of seconds after the epoch (see │
691 clock seconds) that the time limit for the interpreter will be │
692 triggered. The limit will be triggered at the start of the sec‐ │
693 ond unless specified at a sub-second level using the -millisec‐ │
694 onds option. This option may be the empty string, which indi‐ │
695 cates that a time limit is not set for the interpreter.
696 -value This option specifies the number of commands that the inter‐ │
698 preter may execute before triggering the command limit. This │
699 option may be the empty string, which indicates that a command │
700 limit is not set for the interpreter. │
701 Where an interpreter with a resource limit set on it creates a slave │
703 interpreter, that slave interpreter will have resource limits imposed │
704 on it that are at least as restrictive as the limits on the creating │
705 master interpreter. If the master interpreter of the limited master │
706 wishes to relax these conditions, it should hide the interp command in │
707 the child and then use aliases and the interp invokehidden subcommand │
708 to provide such access as it chooses to the interp command to the lim‐ │
709 ited master as necessary. │
710
712 When an error happens in a situation where it cannot be reported │
713 directly up the stack (e.g. when processing events in an update or │
714 vwait call) the error is instead reported through the background error │
715 handling mechanism. Every interpreter has a background error handler │
716 registered; the default error handler arranges for the bgerror command │
717 in the interpreter's global namespace to be called, but other error │
718 handlers may be installed and process background errors in substan‐ │
719 tially different ways. │
720 A background error handler consists of a non-empty list of words to │
722 which will be appended two further words at invocation time. The first │
723 word will be the error message string, and the second will a dictionary │
724 of return options (this is also the sort of information that can be │
725 obtained by trapping a normal error using catch of course.) The result‐ │
726 ing list will then be executed in the interpreter's global namespace │
727 without further substitutions being performed.
728
730 The safe interpreter mechanism is based on the Safe-Tcl prototype
731 implemented by Nathaniel Borenstein and Marshall Rose.
732
734 Creating and using an alias for a command in the current interpreter:
735 interp alias {} getIndex {} lsearch {alpha beta gamma delta}
736 set idx [getIndex delta]
737 Executing an arbitrary command in a safe interpreter where every invo‐
739 cation of lappend is logged:
740 set i [interp create -safe]
741 interp hide $i lappend
742 interp alias $i lappend {} loggedLappend $i
743 proc loggedLappend {i args} {
744 puts "logged invocation of lappend $args"
745 interp invokehidden $i lappend {*}$args
746 }
747 interp eval $i $someUntrustedScript
748 Setting a resource limit on an interpreter so that an infinite loop │
750 terminates. │
751 set i [interp create] │
752 interp limit $i command -value 1000 │
753 interp eval $i { │
754 set x 0 │
755 while {1} { │
756 puts "Counting up... [incr x]" │
757 } │
758 } │
759
761 bgerror(n), load(n), safe(n), Tcl_CreateSlave(3)
762
764 alias, master interpreter, safe interpreter, slave interpreter
765Tcl 7.6 interp(n)