2 interp - Create and manipulate Tcl interpreters
5 interp option ?arg arg ...?
9 This command makes it possible to create one or more new Tcl inter-
10 preters that co-exist with the creating interpreter in the same appli-
11 cation. The creating interpreter is called the master and the new
12 interpreter is called a slave. A master can create any number of
13 slaves, and each slave can itself create additional slaves for which it
14 is master, resulting in a hierarchy of interpreters.
16 Each interpreter is independent from the others: it has its own name
17 space for commands, procedures, and global variables. A master inter-
18 preter may create connections between its slaves and itself using a
19 mechanism called an alias. An alias is a command in a slave inter-
20 preter which, when invoked, causes a command to be invoked in its mas-
21 ter interpreter or in another slave interpreter. The only other con-
22 nections between interpreters are through environment variables (the
23 env variable), which are normally shared among all interpreters in the
24 application. Note that the name space for files (such as the names
25 returned by the open command) is no longer shared between interpreters.
26 Explicit commands are provided to share files and to transfer refer-
27 ences to open files from one interpreter to another.
29 The interp command also provides support for safe interpreters. A safe
30 interpreter is a slave whose functions have been greatly restricted, so
31 that it is safe to execute untrusted scripts without fear of them dam-
32 aging other interpreters or the application's environment. For example,
33 all IO channel creation commands and subprocess creation commands are
34 made inaccessible to safe interpreters. See SAFE INTERPRETERS below
35 for more information on what features are present in a safe inter-
36 preter. The dangerous functionality is not removed from the safe
37 interpreter; instead, it is hidden, so that only trusted interpreters
38 can obtain access to it. For a detailed explanation of hidden commands,
39 see HIDDEN COMMANDS, below. The alias mechanism can be used for pro-
40 tected communication (analogous to a kernel call) between a slave
41 interpreter and its master. See ALIAS INVOCATION, below, for more
42 details on how the alias mechanism works.
44 A qualified interpreter name is a proper Tcl lists containing a subset
45 of its ancestors in the interpreter hierarchy, terminated by the string
46 naming the interpreter in its immediate master. Interpreter names are
47 relative to the interpreter in which they are used. For example, if a
48 is a slave of the current interpreter and it has a slave a1, which in
49 turn has a slave a11, the qualified name of a11 in a is the list a1
52 The interp command, described below, accepts qualified interpreter
53 names as arguments; the interpreter in which the command is being eval-
54 uated can always be referred to as {} (the empty list or string). Note
55 that it is impossible to refer to a master (ancestor) interpreter by
56 name in a slave interpreter except through aliases. Also, there is no
57 global name by which one can refer to the first interpreter created in
58 an application. Both restrictions are motivated by safety concerns.
61 The interp command is used to create, delete, and manipulate slave
62 interpreters, and to share or transfer channels between interpreters.
63 It can have any of several forms, depending on the option argument:
65 interp alias srcPath srcToken
66 Returns a Tcl list whose elements are the targetCmd and args
67 associated with the alias represented by srcToken (this is the
68 value returned when the alias was created; it is possible that
69 the name of the source command in the slave is different from
72 interp alias srcPath srcToken {}
73 Deletes the alias for srcToken in the slave interpreter identi-
74 fied by srcPath. srcToken refers to the value returned when the
75 alias was created; if the source command has been renamed, the
76 renamed command will be deleted.
78 interp alias srcPath srcCmd targetPath targetCmd ?arg arg ...?
79 This command creates an alias between one slave and another (see
80 the alias slave command below for creating aliases between a
81 slave and its master). In this command, either of the slave
82 interpreters may be anywhere in the hierarchy of interpreters
83 under the interpreter invoking the command. SrcPath and srcCmd
84 identify the source of the alias. SrcPath is a Tcl list whose
85 elements select a particular interpreter. For example, ``a b''
86 identifies an interpreter b, which is a slave of interpreter a,
87 which is a slave of the invoking interpreter. An empty list
88 specifies the interpreter invoking the command. srcCmd gives
89 the name of a new command, which will be created in the source
90 interpreter. TargetPath and targetCmd specify a target inter-
91 preter and command, and the arg arguments, if any, specify addi-
92 tional arguments to targetCmd which are prepended to any argu-
93 ments specified in the invocation of srcCmd. TargetCmd may be
94 undefined at the time of this call, or it may already exist; it
95 is not created by this command. The alias arranges for the
96 given target command to be invoked in the target interpreter
97 whenever the given source command is invoked in the source
98 interpreter. See ALIAS INVOCATION below for more details. The
99 command returns a token that uniquely identifies the command
100 created srcCmd, even if the command is renamed afterwards. The
101 token may but does not have to be equal to srcCmd.
103 interp aliases ?path?
104 This command returns a Tcl list of the tokens of all the source
105 commands for aliases defined in the interpreter identified by
106 path. The tokens correspond to the values returned when the
107 aliases were created (which may not be the same as the current
108 names of the commands).
110 interp create ?-safe? ?--? ?path?
111 Creates a slave interpreter identified by path and a new com-
112 mand, called a slave command. The name of the slave command is
113 the last component of path. The new slave interpreter and the
114 slave command are created in the interpreter identified by the
115 path obtained by removing the last component from path. For
116 example, if path is a b c then a new slave interpreter and slave
117 command named c are created in the interpreter identified by the
118 path a b. The slave command may be used to manipulate the new
119 interpreter as described below. If path is omitted, Tcl creates
120 a unique name of the form interpx, where x is an integer, and
121 uses it for the interpreter and the slave command. If the -safe
122 switch is specified (or if the master interpreter is a safe
123 interpreter), the new slave interpreter will be created as a
124 safe interpreter with limited functionality; otherwise the slave
125 will include the full set of Tcl built-in commands and vari-
126 ables. The -- switch can be used to mark the end of switches;
127 it may be needed if path is an unusual value such as -safe. The
128 result of the command is the name of the new interpreter. The
129 name of a slave interpreter must be unique among all the slaves
130 for its master; an error occurs if a slave interpreter by the
131 given name already exists in this master. The initial recursion
132 limit of the slave interpreter is set to the current recursion
133 limit of its parent interpreter.
135 interp delete ?path ...?
136 Deletes zero or more interpreters given by the optional path
137 arguments, and for each interpreter, it also deletes its slaves.
138 The command also deletes the slave command for each interpreter
139 deleted. For each path argument, if no interpreter by that name
140 exists, the command raises an error.
142 interp eval path arg ?arg ...?
143 This command concatenates all of the arg arguments in the same
144 fashion as the concat command, then evaluates the resulting
145 string as a Tcl script in the slave interpreter identified by
146 path. The result of this evaluation (including error information
147 such as the errorInfo and errorCode variables, if an error
148 occurs) is returned to the invoking interpreter. Note that the
149 script will be executed in the current context stack frame of
150 the path interpreter; this is so that the implementations (in a
151 master interpreter) of aliases in a slave interpreter can exe-
152 cute scripts in the slave that find out information about the
153 slave's current state and stack frame.
156 Returns 1 if a slave interpreter by the specified path exists
157 in this master, 0 otherwise. If path is omitted, the invoking
160 interp expose path hiddenName ?exposedCmdName?
161 Makes the hidden command hiddenName exposed, eventually bringing
162 it back under a new exposedCmdName name (this name is currently
163 accepted only if it is a valid global name space name without
164 any ::), in the interpreter denoted by path. If an exposed com-
165 mand with the targeted name already exists, this command fails.
166 Hidden commands are explained in more detail in HIDDEN COMMANDS,
169 interp hide path exposedCmdName ?hiddenCmdName?
170 Makes the exposed command exposedCmdName hidden, renaming it to
171 the hidden command hiddenCmdName, or keeping the same name if
172 hiddenCmdName is not given, in the interpreter denoted by path.
173 If a hidden command with the targeted name already exists, this
174 command fails. Currently both exposedCmdName and hiddenCmdName
175 can not contain namespace qualifiers, or an error is raised.
176 Commands to be hidden by interp hide are looked up in the global
177 namespace even if the current namespace is not the global one.
178 This prevents slaves from fooling a master interpreter into hid-
179 ing the wrong command, by making the current namespace be dif-
180 ferent from the global one. Hidden commands are explained in
181 more detail in HIDDEN COMMANDS, below.
184 Returns a list of the names of all hidden commands in the inter-
185 preter identified by path.
187 interp invokehidden path ?-global? hiddenCmdName ?arg ...?
188 Invokes the hidden command hiddenCmdName with the arguments sup-
189 plied in the interpreter denoted by path. No substitutions or
190 evaluation are applied to the arguments. If the -global flag is
191 present, the hidden command is invoked at the global level in
192 the target interpreter; otherwise it is invoked at the current
193 call frame and can access local variables in that and outer call
194 frames. Hidden commands are explained in more detail in HIDDEN
198 Returns 1 if the interpreter identified by the specified path is
201 interp marktrusted path
202 Marks the interpreter identified by path as trusted. Does not
203 expose the hidden commands. This command can only be invoked
204 from a trusted interpreter. The command has no effect if the
205 interpreter identified by path is already trusted.
207 interp recursionlimit path ?newlimit?
208 Returns the maximum allowable nesting depth for the interpreter
209 specified by path. If newlimit is specified, the interpreter
210 recursion limit will be set so that nesting of more than
211 newlimit calls to Tcl_Eval() and related procedures in that
212 interpreter will return an error. The newlimit value is also
213 returned. The newlimit value must be a positive integer between
214 1 and the maximum value of a non-long integer on the platform.
216 The command sets the maximum size of the Tcl call stack only. It
217 cannot by itself prevent stack overflows on the C stack being
218 used by the application. If your machine has a limit on the size
219 of the C stack, you may get stack overflows before reaching the
220 limit set by the command. If this happens, see if there is a
221 mechanism in your system for increasing the maximum size of the
224 interp share srcPath channelId destPath
225 Causes the IO channel identified by channelId to become shared
226 between the interpreter identified by srcPath and the inter-
227 preter identified by destPath. Both interpreters have the same
228 permissions on the IO channel. Both interpreters must close it
229 to close the underlying IO channel; IO channels accessible in an
230 interpreter are automatically closed when an interpreter is
234 Returns a Tcl list of the names of all the slave interpreters
235 associated with the interpreter identified by path. If path is
236 omitted, the invoking interpreter is used.
238 interp target path alias
239 Returns a Tcl list describing the target interpreter for an
240 alias. The alias is specified with an interpreter path and
241 source command name, just as in interp alias above. The name of
242 the target interpreter is returned as an interpreter path, rela-
243 tive to the invoking interpreter. If the target interpreter for
244 the alias is the invoking interpreter then an empty list is
245 returned. If the target interpreter for the alias is not the
246 invoking interpreter or one of its descendants then an error is
247 generated. The target command does not have to be defined at
248 the time of this invocation.
250 interp transfer srcPath channelId destPath
251 Causes the IO channel identified by channelId to become avail-
252 able in the interpreter identified by destPath and unavailable
253 in the interpreter identified by srcPath.
256 For each slave interpreter created with the interp command, a new Tcl
257 command is created in the master interpreter with the same name as the
258 new interpreter. This command may be used to invoke various operations
259 on the interpreter. It has the following general form:
260 slave command ?arg arg ...?
261 Slave is the name of the interpreter, and command and the args deter-
262 mine the exact behavior of the command. The valid forms of this com-
266 Returns a Tcl list whose elements are the tokens of all the
267 aliases in slave. The tokens correspond to the values returned
268 when the aliases were created (which may not be the same as the
269 current names of the commands).
272 Returns a Tcl list whose elements are the targetCmd and args
273 associated with the alias represented by srcToken (this is the
274 value returned when the alias was created; it is possible that
275 the actual source command in the slave is different from srcTo-
278 slave alias srcToken {}
279 Deletes the alias for srcToken in the slave interpreter. srcTo-
280 ken refers to the value returned when the alias was created; if
281 the source command has been renamed, the renamed command will be
284 slave alias srcCmd targetCmd ?arg ..?
285 Creates an alias such that whenever srcCmd is invoked in slave,
286 targetCmd is invoked in the master. The arg arguments will be
287 passed to targetCmd as additional arguments, prepended before
288 any arguments passed in the invocation of srcCmd. See ALIAS
289 INVOCATION below for details. The command returns a token that
290 uniquely identifies the command created srcCmd, even if the com-
291 mand is renamed afterwards. The token may but does not have to
294 slave eval arg ?arg ..?
295 This command concatenates all of the arg arguments in the same
296 fashion as the concat command, then evaluates the resulting
297 string as a Tcl script in slave. The result of this evaluation
298 (including error information such as the errorInfo and errorCode
299 variables, if an error occurs) is returned to the invoking
300 interpreter. Note that the script will be executed in the cur-
301 rent context stack frame of slave; this is so that the implemen-
302 tations (in a master interpreter) of aliases in a slave inter-
303 preter can execute scripts in the slave that find out informa-
304 tion about the slave's current state and stack frame.
306 slave expose hiddenName ?exposedCmdName?
307 This command exposes the hidden command hiddenName, eventually
308 bringing it back under a new exposedCmdName name (this name is
309 currently accepted only if it is a valid global name space name
310 without any ::), in slave. If an exposed command with the tar-
311 geted name already exists, this command fails. For more details
312 on hidden commands, see HIDDEN COMMANDS, below.
314 slave hide exposedCmdName ?hiddenCmdName?
315 This command hides the exposed command exposedCmdName, renaming
316 it to the hidden command hiddenCmdName, or keeping the same name
317 if the argument is not given, in the slave interpreter. If a
318 hidden command with the targeted name already exists, this com-
319 mand fails. Currently both exposedCmdName and hiddenCmdName can
320 not contain namespace qualifiers, or an error is raised. Com-
321 mands to be hidden are looked up in the global namespace even if
322 the current namespace is not the global one. This prevents
323 slaves from fooling a master interpreter into hiding the wrong
324 command, by making the current namespace be different from the
325 global one. For more details on hidden commands, see HIDDEN
329 Returns a list of the names of all hidden commands in slave.
331 slave invokehidden ?-global hiddenName ?arg ..?
332 This command invokes the hidden command hiddenName with the sup-
333 plied arguments, in slave. No substitutions or evaluations are
334 applied to the arguments. If the -global flag is given, the
335 command is invoked at the global level in the slave; otherwise
336 it is invoked at the current call frame and can access local
337 variables in that or outer call frames. For more details on
338 hidden commands, see HIDDEN COMMANDS, below.
341 Returns 1 if the slave interpreter is safe, 0 otherwise.
344 Marks the slave interpreter as trusted. Can only be invoked by a
345 trusted interpreter. This command does not expose any hidden
346 commands in the slave interpreter. The command has no effect if
347 the slave is already trusted.
349 slave recursionlimit ?newlimit?
350 Returns the maximum allowable nesting depth for the slave inter-
351 preter. If newlimit is specified, the recursion limit in slave
352 will be set so that nesting of more than newlimit calls to
353 Tcl_Eval() and related procedures in slave will return an error.
354 The newlimit value is also returned. The newlimit value must be
355 a positive integer between 1 and the maximum value of a non-long
356 integer on the platform.
358 The command sets the maximum size of the Tcl call stack only. It
359 cannot by itself prevent stack overflows on the C stack being
360 used by the application. If your machine has a limit on the size
361 of the C stack, you may get stack overflows before reaching the
362 limit set by the command. If this happens, see if there is a
363 mechanism in your system for increasing the maximum size of the
367 A safe interpreter is one with restricted functionality, so that is
368 safe to execute an arbitrary script from your worst enemy without fear
369 of that script damaging the enclosing application or the rest of your
370 computing environment. In order to make an interpreter safe, certain
371 commands and variables are removed from the interpreter. For example,
372 commands to create files on disk are removed, and the exec command is
373 removed, since it could be used to cause damage through subprocesses.
374 Limited access to these facilities can be provided, by creating aliases
375 to the master interpreter which check their arguments carefully and
376 provide restricted access to a safe subset of facilities. For example,
377 file creation might be allowed in a particular subdirectory and subpro-
378 cess invocation might be allowed for a carefully selected and fixed set
381 A safe interpreter is created by specifying the -safe switch to the
382 interp create command. Furthermore, any slave created by a safe inter-
383 preter will also be safe.
385 A safe interpreter is created with exactly the following set of built-
388 after append array binary
389 break case catch clock
390 close concat continue eof
391 error eval expr fblocked
392 fcopy fileevent flush for
393 foreach format gets global
395 join lappend lindex linsert
396 list llength lrange lreplace
397 lsearch lsort namespace package
399 regexp regsub rename return
401 string subst switch tell
402 time trace unset update
403 uplevel upvar variable vwait
406 The following commands are hidden by interp create when it creates a
409 cd encoding exec exit
410 fconfigure file glob load
411 open pwd socket source
413 These commands can be recreated later as Tcl procedures or aliases, or
414 re-exposed by interp expose.
416 The following commands from Tcl's library of support procedures are not
417 present in a safe interpreter:
419 auto_exec_ok auto_import auto_load
420 auto_load_index auto_qualify unknown
422 Note in particular that safe interpreters have no default unknown com-
423 mand, so Tcl's default autoloading facilities are not available.
424 Autoload access to Tcl's commands that are normally autoloaded:
426 auto_mkindex auto_mkindex_old
429 ::pkg::create ::safe::interpAddToAccessPath
430 ::safe::interpCreate ::safe::interpConfigure
431 ::safe::interpDelete ::safe::interpFindInAccessPath
432 ::safe::interpInit ::safe::setLogCmd
433 tcl_endOfWord tcl_findLibrary
434 tcl_startOfNextWord tcl_startOfPreviousWord
435 tcl_wordBreakAfter tcl_wordBreakBefore
437 can only be provided by explicit definition of an unknown command in
438 the safe interpreter. This will involve exposing the source command.
439 This is most easily accomplished by creating the safe interpreter with
440 Tcl's Safe-Tcl mechanism. Safe-Tcl provides safe versions of source,
441 load, and other Tcl commands needed to support autoloading of commands
442 and the loading of packages.
444 In addition, the env variable is not present in a safe interpreter, so
445 it cannot share environment variables with other interpreters. The env
446 variable poses a security risk, because users can store sensitive
447 information in an environment variable. For example, the PGP manual
448 recommends storing the PGP private key protection password in the envi-
449 ronment variable PGPPASS. Making this variable available to untrusted
450 code executing in a safe interpreter would incur a security risk.
452 If extensions are loaded into a safe interpreter, they may also
453 restrict their own functionality to eliminate unsafe commands. For a
454 discussion of management of extensions for safety see the manual
455 entries for Safe-Tcl and the load Tcl command.
457 A safe interpreter may not alter the recursion limit of any inter-
458 preter, including itself.
461 The alias mechanism has been carefully designed so that it can be used
462 safely when an untrusted script is executing in a safe slave and the
463 target of the alias is a trusted master. The most important thing in
464 guaranteeing safety is to ensure that information passed from the slave
465 to the master is never evaluated or substituted in the master; if this
466 were to occur, it would enable an evil script in the slave to invoke
467 arbitrary functions in the master, which would compromise security.
469 When the source for an alias is invoked in the slave interpreter, the
470 usual Tcl substitutions are performed when parsing that command. These
471 substitutions are carried out in the source interpreter just as they
472 would be for any other command invoked in that interpreter. The com-
473 mand procedure for the source command takes its arguments and merges
474 them with the targetCmd and args for the alias to create a new array of
475 arguments. If the words of srcCmd were ``srcCmd arg1 arg2 ... argN'',
476 the new set of words will be ``targetCmd arg arg ... arg arg1 arg2 ...
477 argN'', where targetCmd and args are the values supplied when the alias
478 was created. TargetCmd is then used to locate a command procedure in
479 the target interpreter, and that command procedure is invoked with the
480 new set of arguments. An error occurs if there is no command named
481 targetCmd in the target interpreter. No additional substitutions are
482 performed on the words: the target command procedure is invoked
483 directly, without going through the normal Tcl evaluation mechanism.
484 Substitutions are thus performed on each word exactly once: targetCmd
485 and args were substituted when parsing the command that created the
486 alias, and arg1 - argN are substituted when the alias's source command
487 is parsed in the source interpreter.
489 When writing the targetCmds for aliases in safe interpreters, it is
490 very important that the arguments to that command never be evaluated or
491 substituted, since this would provide an escape mechanism whereby the
492 slave interpreter could execute arbitrary code in the master. This in
493 turn would compromise the security of the system.
496 Safe interpreters greatly restrict the functionality available to Tcl
497 programs executing within them. Allowing the untrusted Tcl program to
498 have direct access to this functionality is unsafe, because it can be
499 used for a variety of attacks on the environment. However, there are
500 times when there is a legitimate need to use the dangerous functional-
501 ity in the context of the safe interpreter. For example, sometimes a
502 program must be sourced into the interpreter. Another example is Tk,
503 where windows are bound to the hierarchy of windows for a specific
504 interpreter; some potentially dangerous functions, e.g. window manage-
505 ment, must be performed on these windows within the interpreter con-
508 The interp command provides a solution to this problem in the form of
509 hidden commands. Instead of removing the dangerous commands entirely
510 from a safe interpreter, these commands are hidden so they become
511 unavailable to Tcl scripts executing in the interpreter. However, such
512 hidden commands can be invoked by any trusted ancestor of the safe
513 interpreter, in the context of the safe interpreter, using interp
514 invoke. Hidden commands and exposed commands reside in separate name
515 spaces. It is possible to define a hidden command and an exposed com-
516 mand by the same name within one interpreter.
518 Hidden commands in a slave interpreter can be invoked in the body of
519 procedures called in the master during alias invocation. For example,
520 an alias for source could be created in a slave interpreter. When it is
521 invoked in the slave interpreter, a procedure is called in the master
522 interpreter to check that the operation is allowable (e.g. it asks to
523 source a file that the slave interpreter is allowed to access). The
524 procedure then it invokes the hidden source command in the slave inter-
525 preter to actually source in the contents of the file. Note that two
526 commands named source exist in the slave interpreter: the alias, and
529 Because a master interpreter may invoke a hidden command as part of
530 handling an alias invocation, great care must be taken to avoid evalu-
531 ating any arguments passed in through the alias invocation. Otherwise,
532 malicious slave interpreters could cause a trusted master interpreter
533 to execute dangerous commands on their behalf. See the section on ALIAS
534 INVOCATION for a more complete discussion of this topic. To help avoid
535 this problem, no substitutions or evaluations are applied to arguments
536 of interp invokehidden.
538 Safe interpreters are not allowed to invoke hidden commands in them-
539 selves or in their descendants. This prevents safe slaves from gaining
540 access to hidden functionality in themselves or their descendants.
542 The set of hidden commands in an interpreter can be manipulated by a
543 trusted interpreter using interp expose and interp hide. The interp
544 expose command moves a hidden command to the set of exposed commands in
545 the interpreter identified by path, potentially renaming the command in
546 the process. If an exposed command by the targeted name already exists,
547 the operation fails. Similarly, interp hide moves an exposed command to
548 the set of hidden commands in that interpreter. Safe interpreters are
549 not allowed to move commands between the set of hidden and exposed com-
550 mands, in either themselves or their descendants.
552 Currently, the names of hidden commands cannot contain namespace quali-
553 fiers, and you must first rename a command in a namespace to the global
554 namespace before you can hide it. Commands to be hidden by interp hide
555 are looked up in the global namespace even if the current namespace is
556 not the global one. This prevents slaves from fooling a master inter-
557 preter into hiding the wrong command, by making the current namespace
558 be different from the global one.
561 This mechanism is based on the Safe-Tcl prototype implemented by
562 Nathaniel Borenstein and Marshall Rose.
565 Creating and using an alias for a command in the current interpreter:
566 interp alias {} getIndex {} lsearch {alpha beta gamma delta}
567 set idx [getIndex delta]
569 Executing an arbitrary command in a safe interpreter where every
570 invokation of lappend is logged:
571 set i [interp create -safe]
572 interp hide $i lappend
573 interp alias $i lappend {} loggedLappend $i
574 proc loggedLappend {i args} {
575 puts "logged invokation of lappend $args"
576 # Be extremely careful about command construction
577 eval [linsert $args 0 \
578 interp invokehidden $i lappend]
580 interp eval $i $someUntrustedScript
584 load(n), safe(n), Tcl_CreateSlave(3)
projects / tas-yagle.git / blob