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