Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | '\" |
2 | '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. | |
3 | '\" | |
4 | '\" See the file "license.terms" for information on usage and redistribution | |
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
6 | '\" | |
7 | '\" RCS: @(#) $Id: interp.n,v 1.9.2.2 2004/10/27 14:23:56 dkf Exp $ | |
8 | '\" | |
9 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
10 | '\" manual entries. | |
11 | '\" | |
12 | '\" .AP type name in/out ?indent? | |
13 | '\" Start paragraph describing an argument to a library procedure. | |
14 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
15 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
16 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
17 | '\" needed; use .AS below instead) | |
18 | '\" | |
19 | '\" .AS ?type? ?name? | |
20 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
21 | '\" name are examples of largest possible arguments that will be passed | |
22 | '\" to .AP later. If args are omitted, default tab stops are used. | |
23 | '\" | |
24 | '\" .BS | |
25 | '\" Start box enclosure. From here until next .BE, everything will be | |
26 | '\" enclosed in one large box. | |
27 | '\" | |
28 | '\" .BE | |
29 | '\" End of box enclosure. | |
30 | '\" | |
31 | '\" .CS | |
32 | '\" Begin code excerpt. | |
33 | '\" | |
34 | '\" .CE | |
35 | '\" End code excerpt. | |
36 | '\" | |
37 | '\" .VS ?version? ?br? | |
38 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
39 | '\" of man pages. The first argument is ignored and used for recording | |
40 | '\" the version when the .VS was added, so that the sidebars can be | |
41 | '\" found and removed when they reach a certain age. If another argument | |
42 | '\" is present, then a line break is forced before starting the sidebar. | |
43 | '\" | |
44 | '\" .VE | |
45 | '\" End of vertical sidebar. | |
46 | '\" | |
47 | '\" .DS | |
48 | '\" Begin an indented unfilled display. | |
49 | '\" | |
50 | '\" .DE | |
51 | '\" End of indented unfilled display. | |
52 | '\" | |
53 | '\" .SO | |
54 | '\" Start of list of standard options for a Tk widget. The | |
55 | '\" options follow on successive lines, in four columns separated | |
56 | '\" by tabs. | |
57 | '\" | |
58 | '\" .SE | |
59 | '\" End of list of standard options for a Tk widget. | |
60 | '\" | |
61 | '\" .OP cmdName dbName dbClass | |
62 | '\" Start of description of a specific option. cmdName gives the | |
63 | '\" option's name as specified in the class command, dbName gives | |
64 | '\" the option's name in the option database, and dbClass gives | |
65 | '\" the option's class in the option database. | |
66 | '\" | |
67 | '\" .UL arg1 arg2 | |
68 | '\" Print arg1 underlined, then print arg2 normally. | |
69 | '\" | |
70 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
71 | '\" | |
72 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
73 | .if t .wh -1.3i ^B | |
74 | .nr ^l \n(.l | |
75 | .ad b | |
76 | '\" # Start an argument description | |
77 | .de AP | |
78 | .ie !"\\$4"" .TP \\$4 | |
79 | .el \{\ | |
80 | . ie !"\\$2"" .TP \\n()Cu | |
81 | . el .TP 15 | |
82 | .\} | |
83 | .ta \\n()Au \\n()Bu | |
84 | .ie !"\\$3"" \{\ | |
85 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
86 | .\".b | |
87 | .\} | |
88 | .el \{\ | |
89 | .br | |
90 | .ie !"\\$2"" \{\ | |
91 | \&\\$1 \\fI\\$2\\fP | |
92 | .\} | |
93 | .el \{\ | |
94 | \&\\fI\\$1\\fP | |
95 | .\} | |
96 | .\} | |
97 | .. | |
98 | '\" # define tabbing values for .AP | |
99 | .de AS | |
100 | .nr )A 10n | |
101 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
102 | .nr )B \\n()Au+15n | |
103 | .\" | |
104 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
105 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
106 | .. | |
107 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
108 | '\" # BS - start boxed text | |
109 | '\" # ^y = starting y location | |
110 | '\" # ^b = 1 | |
111 | .de BS | |
112 | .br | |
113 | .mk ^y | |
114 | .nr ^b 1u | |
115 | .if n .nf | |
116 | .if n .ti 0 | |
117 | .if n \l'\\n(.lu\(ul' | |
118 | .if n .fi | |
119 | .. | |
120 | '\" # BE - end boxed text (draw box now) | |
121 | .de BE | |
122 | .nf | |
123 | .ti 0 | |
124 | .mk ^t | |
125 | .ie n \l'\\n(^lu\(ul' | |
126 | .el \{\ | |
127 | .\" Draw four-sided box normally, but don't draw top of | |
128 | .\" box if the box started on an earlier page. | |
129 | .ie !\\n(^b-1 \{\ | |
130 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
131 | .\} | |
132 | .el \}\ | |
133 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
134 | .\} | |
135 | .\} | |
136 | .fi | |
137 | .br | |
138 | .nr ^b 0 | |
139 | .. | |
140 | '\" # VS - start vertical sidebar | |
141 | '\" # ^Y = starting y location | |
142 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
143 | .de VS | |
144 | .if !"\\$2"" .br | |
145 | .mk ^Y | |
146 | .ie n 'mc \s12\(br\s0 | |
147 | .el .nr ^v 1u | |
148 | .. | |
149 | '\" # VE - end of vertical sidebar | |
150 | .de VE | |
151 | .ie n 'mc | |
152 | .el \{\ | |
153 | .ev 2 | |
154 | .nf | |
155 | .ti 0 | |
156 | .mk ^t | |
157 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
158 | .sp -1 | |
159 | .fi | |
160 | .ev | |
161 | .\} | |
162 | .nr ^v 0 | |
163 | .. | |
164 | '\" # Special macro to handle page bottom: finish off current | |
165 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
166 | '\" # page bottom macro. | |
167 | .de ^B | |
168 | .ev 2 | |
169 | 'ti 0 | |
170 | 'nf | |
171 | .mk ^t | |
172 | .if \\n(^b \{\ | |
173 | .\" Draw three-sided box if this is the box's first page, | |
174 | .\" draw two sides but no top otherwise. | |
175 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
176 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
177 | .\} | |
178 | .if \\n(^v \{\ | |
179 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
180 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
181 | .\} | |
182 | .bp | |
183 | 'fi | |
184 | .ev | |
185 | .if \\n(^b \{\ | |
186 | .mk ^y | |
187 | .nr ^b 2 | |
188 | .\} | |
189 | .if \\n(^v \{\ | |
190 | .mk ^Y | |
191 | .\} | |
192 | .. | |
193 | '\" # DS - begin display | |
194 | .de DS | |
195 | .RS | |
196 | .nf | |
197 | .sp | |
198 | .. | |
199 | '\" # DE - end display | |
200 | .de DE | |
201 | .fi | |
202 | .RE | |
203 | .sp | |
204 | .. | |
205 | '\" # SO - start of list of standard options | |
206 | .de SO | |
207 | .SH "STANDARD OPTIONS" | |
208 | .LP | |
209 | .nf | |
210 | .ta 5.5c 11c | |
211 | .ft B | |
212 | .. | |
213 | '\" # SE - end of list of standard options | |
214 | .de SE | |
215 | .fi | |
216 | .ft R | |
217 | .LP | |
218 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
219 | .. | |
220 | '\" # OP - start of full description for a single option | |
221 | .de OP | |
222 | .LP | |
223 | .nf | |
224 | .ta 4c | |
225 | Command-Line Name: \\fB\\$1\\fR | |
226 | Database Name: \\fB\\$2\\fR | |
227 | Database Class: \\fB\\$3\\fR | |
228 | .fi | |
229 | .IP | |
230 | .. | |
231 | '\" # CS - begin code excerpt | |
232 | .de CS | |
233 | .RS | |
234 | .nf | |
235 | .ta .25i .5i .75i 1i | |
236 | .. | |
237 | '\" # CE - end code excerpt | |
238 | .de CE | |
239 | .fi | |
240 | .RE | |
241 | .. | |
242 | .de UL | |
243 | \\$1\l'|0\(ul'\\$2 | |
244 | .. | |
245 | .TH interp n 7.6 Tcl "Tcl Built-In Commands" | |
246 | .BS | |
247 | '\" Note: do not modify the .SH NAME line immediately below! | |
248 | .SH NAME | |
249 | interp \- Create and manipulate Tcl interpreters | |
250 | .SH SYNOPSIS | |
251 | \fBinterp \fIoption \fR?\fIarg arg ...\fR? | |
252 | .BE | |
253 | ||
254 | .SH DESCRIPTION | |
255 | .PP | |
256 | This command makes it possible to create one or more new Tcl | |
257 | interpreters that co-exist with the creating interpreter in the | |
258 | same application. The creating interpreter is called the \fImaster\fR | |
259 | and the new interpreter is called a \fIslave\fR. | |
260 | A master can create any number of slaves, and each slave can | |
261 | itself create additional slaves for which it is master, resulting | |
262 | in a hierarchy of interpreters. | |
263 | .PP | |
264 | Each interpreter is independent from the others: it has its own name | |
265 | space for commands, procedures, and global variables. | |
266 | A master interpreter may create connections between its slaves and | |
267 | itself using a mechanism called an \fIalias\fR. An \fIalias\fR is | |
268 | a command in a slave interpreter which, when invoked, causes a | |
269 | command to be invoked in its master interpreter or in another slave | |
270 | interpreter. The only other connections between interpreters are | |
271 | through environment variables (the \fBenv\fR variable), which are | |
272 | normally shared among all interpreters in the application. Note that the | |
273 | name space for files (such as the names returned by the \fBopen\fR command) | |
274 | is no longer shared between interpreters. Explicit commands are provided to | |
275 | share files and to transfer references to open files from one interpreter | |
276 | to another. | |
277 | .PP | |
278 | The \fBinterp\fR command also provides support for \fIsafe\fR | |
279 | interpreters. A safe interpreter is a slave whose functions have | |
280 | been greatly restricted, so that it is safe to execute untrusted | |
281 | scripts without fear of them damaging other interpreters or the | |
282 | application's environment. For example, all IO channel creation | |
283 | commands and subprocess creation commands are made inaccessible to safe | |
284 | interpreters. | |
285 | .VS | |
286 | See \fBSAFE INTERPRETERS\fR below for more information on | |
287 | what features are present in a safe interpreter. | |
288 | The dangerous functionality is not removed from the safe interpreter; | |
289 | instead, it is \fIhidden\fR, so that only trusted interpreters can obtain | |
290 | access to it. For a detailed explanation of hidden commands, see | |
291 | \fBHIDDEN COMMANDS\fR, below. | |
292 | The alias mechanism can be used for protected communication (analogous to a | |
293 | kernel call) between a slave interpreter and its master. | |
294 | See \fBALIAS INVOCATION\fR, below, for more details | |
295 | on how the alias mechanism works. | |
296 | .VE | |
297 | .PP | |
298 | A qualified interpreter name is a proper Tcl lists containing a subset of its | |
299 | ancestors in the interpreter hierarchy, terminated by the string naming the | |
300 | interpreter in its immediate master. Interpreter names are relative to the | |
301 | interpreter in which they are used. For example, if \fBa\fR is a slave of | |
302 | the current interpreter and it has a slave \fBa1\fR, which in turn has a | |
303 | slave \fBa11\fR, the qualified name of \fBa11\fR in \fBa\fR is the list | |
304 | \fBa1 a11\fR. | |
305 | .PP | |
306 | The \fBinterp\fR command, described below, accepts qualified interpreter | |
307 | names as arguments; the interpreter in which the command is being evaluated | |
308 | can always be referred to as \fB{}\fR (the empty list or string). Note that | |
309 | it is impossible to refer to a master (ancestor) interpreter by name in a | |
310 | slave interpreter except through aliases. Also, there is no global name by | |
311 | which one can refer to the first interpreter created in an application. | |
312 | Both restrictions are motivated by safety concerns. | |
313 | .SH "THE INTERP COMMAND" | |
314 | .PP | |
315 | The \fBinterp\fR command is used to create, delete, and manipulate | |
316 | slave interpreters, and to share or transfer | |
317 | channels between interpreters. It can have any of several forms, depending | |
318 | on the \fIoption\fR argument: | |
319 | .TP | |
320 | \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR | |
321 | Returns a Tcl list whose elements are the \fItargetCmd\fR and | |
322 | \fIarg\fRs associated with the alias represented by \fIsrcToken\fR | |
323 | (this is the value returned when the alias was | |
324 | created; it is possible that the name of the source command in the | |
325 | slave is different from \fIsrcToken\fR). | |
326 | .TP | |
327 | \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR \fB{}\fR | |
328 | Deletes the alias for \fIsrcToken\fR in the slave interpreter identified by | |
329 | \fIsrcPath\fR. | |
330 | \fIsrcToken\fR refers to the value returned when the alias | |
331 | was created; if the source command has been renamed, the renamed | |
332 | command will be deleted. | |
333 | .TP | |
334 | \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR \fItargetPath\fR \fItargetCmd \fR?\fIarg arg ...\fR? | |
335 | This command creates an alias between one slave and another (see the | |
336 | \fBalias\fR slave command below for creating aliases between a slave | |
337 | and its master). In this command, either of the slave interpreters | |
338 | may be anywhere in the hierarchy of interpreters under the interpreter | |
339 | invoking the command. | |
340 | \fISrcPath\fR and \fIsrcCmd\fR identify the source of the alias. | |
341 | \fISrcPath\fR is a Tcl list whose elements select a particular | |
342 | interpreter. For example, ``\fBa b\fR'' identifies an interpreter | |
343 | \fBb\fR, which is a slave of interpreter \fBa\fR, which is a slave | |
344 | of the invoking interpreter. An empty list specifies the interpreter | |
345 | invoking the command. \fIsrcCmd\fR gives the name of a new | |
346 | command, which will be created in the source interpreter. | |
347 | \fITargetPath\fR and \fItargetCmd\fR specify a target interpreter | |
348 | and command, and the \fIarg\fR arguments, if any, specify additional | |
349 | arguments to \fItargetCmd\fR which are prepended to any arguments specified | |
350 | in the invocation of \fIsrcCmd\fR. | |
351 | \fITargetCmd\fR may be undefined at the time of this call, or it may | |
352 | already exist; it is not created by this command. | |
353 | The alias arranges for the given target command to be invoked | |
354 | in the target interpreter whenever the given source command is | |
355 | invoked in the source interpreter. See \fBALIAS INVOCATION\fR below for | |
356 | more details. | |
357 | The command returns a token that uniquely identifies the command created | |
358 | \fIsrcCmd\fR, even if the command is renamed afterwards. The token may but | |
359 | does not have to be equal to \fIsrcCmd\fR. | |
360 | .TP | |
361 | \fBinterp\fR \fBaliases \fR?\fIpath\fR? | |
362 | This command returns a Tcl list of the tokens of all the source commands for | |
363 | aliases defined in the interpreter identified by \fIpath\fR. The tokens | |
364 | correspond to the values returned when | |
365 | the aliases were created (which may not be the same | |
366 | as the current names of the commands). | |
367 | .TP | |
368 | \fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? | |
369 | Creates a slave interpreter identified by \fIpath\fR and a new command, | |
370 | called a \fIslave command\fR. The name of the slave command is the last | |
371 | component of \fIpath\fR. The new slave interpreter and the slave command | |
372 | are created in the interpreter identified by the path obtained by removing | |
373 | the last component from \fIpath\fR. For example, if \fIpath is \fBa b | |
374 | c\fR then a new slave interpreter and slave command named \fBc\fR are | |
375 | created in the interpreter identified by the path \fBa b\fR. | |
376 | The slave command may be used to manipulate the new interpreter as | |
377 | described below. If \fIpath\fR is omitted, Tcl creates a unique name of the | |
378 | form \fBinterp\fIx\fR, where \fIx\fR is an integer, and uses it for the | |
379 | interpreter and the slave command. If the \fB\-safe\fR switch is specified | |
380 | (or if the master interpreter is a safe interpreter), the new slave | |
381 | interpreter will be created as a safe interpreter with limited | |
382 | functionality; otherwise the slave will include the full set of Tcl | |
383 | built-in commands and variables. The \fB\-\|\-\fR switch can be used to | |
384 | mark the end of switches; it may be needed if \fIpath\fR is an unusual | |
385 | value such as \fB\-safe\fR. The result of the command is the name of the | |
386 | new interpreter. The name of a slave interpreter must be unique among all | |
387 | the slaves for its master; an error occurs if a slave interpreter by the | |
388 | given name already exists in this master. | |
389 | The initial recursion limit of the slave interpreter is set to the | |
390 | current recursion limit of its parent interpreter. | |
391 | .TP | |
392 | \fBinterp\fR \fBdelete \fR?\fIpath ...?\fR | |
393 | Deletes zero or more interpreters given by the optional \fIpath\fR | |
394 | arguments, and for each interpreter, it also deletes its slaves. The | |
395 | command also deletes the slave command for each interpreter deleted. | |
396 | For each \fIpath\fR argument, if no interpreter by that name | |
397 | exists, the command raises an error. | |
398 | .TP | |
399 | \fBinterp\fR \fBeval\fR \fIpath arg \fR?\fIarg ...\fR? | |
400 | This command concatenates all of the \fIarg\fR arguments in the same | |
401 | fashion as the \fBconcat\fR command, then evaluates the resulting string as | |
402 | a Tcl script in the slave interpreter identified by \fIpath\fR. The result | |
403 | of this evaluation (including error information such as the \fBerrorInfo\fR | |
404 | and \fBerrorCode\fR variables, if an error occurs) is returned to the | |
405 | invoking interpreter. | |
406 | Note that the script will be executed in the current context stack frame of the | |
407 | \fIpath\fR interpreter; this is so that the implementations (in a master | |
408 | interpreter) of aliases in a slave interpreter can execute scripts in | |
409 | the slave that find out information about the slave's current state | |
410 | and stack frame. | |
411 | .TP | |
412 | \fBinterp exists \fIpath\fR | |
413 | Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR | |
414 | exists in this master, \fB0\fR otherwise. If \fIpath\fR is omitted, the | |
415 | invoking interpreter is used. | |
416 | .VS "" BR | |
417 | .TP | |
418 | \fBinterp expose \fIpath\fR \fIhiddenName\fR ?\fIexposedCmdName\fR? | |
419 | Makes the hidden command \fIhiddenName\fR exposed, eventually bringing | |
420 | it back under a new \fIexposedCmdName\fR name (this name is currently | |
421 | accepted only if it is a valid global name space name without any ::), | |
422 | in the interpreter | |
423 | denoted by \fIpath\fR. | |
424 | If an exposed command with the targeted name already exists, this command | |
425 | fails. | |
426 | Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. | |
427 | .TP | |
428 | \fBinterp\fR \fBhide\fR \fIpath\fR \fIexposedCmdName\fR ?\fIhiddenCmdName\fR? | |
429 | Makes the exposed command \fIexposedCmdName\fR hidden, renaming | |
430 | it to the hidden command \fIhiddenCmdName\fR, or keeping the same name if | |
431 | \fIhiddenCmdName\fR is not given, in the interpreter denoted | |
432 | by \fIpath\fR. | |
433 | If a hidden command with the targeted name already exists, this command | |
434 | fails. | |
435 | Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can | |
436 | not contain namespace qualifiers, or an error is raised. | |
437 | Commands to be hidden by \fBinterp hide\fR are looked up in the global | |
438 | namespace even if the current namespace is not the global one. This | |
439 | prevents slaves from fooling a master interpreter into hiding the wrong | |
440 | command, by making the current namespace be different from the global one. | |
441 | Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. | |
442 | .TP | |
443 | \fBinterp\fR \fBhidden\fR \fIpath\fR | |
444 | Returns a list of the names of all hidden commands in the interpreter | |
445 | identified by \fIpath\fR. | |
446 | .TP | |
447 | \fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fB-global\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR? | |
448 | Invokes the hidden command \fIhiddenCmdName\fR with the arguments supplied | |
449 | in the interpreter denoted by \fIpath\fR. No substitutions or evaluation | |
450 | are applied to the arguments. | |
451 | If the \fB-global\fR flag is present, the hidden command is invoked at the | |
452 | global level in the target interpreter; otherwise it is invoked at the | |
453 | current call frame and can access local variables in that and outer call | |
454 | frames. | |
455 | Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. | |
456 | .VE | |
457 | .TP | |
458 | \fBinterp issafe\fR ?\fIpath\fR? | |
459 | Returns \fB1\fR if the interpreter identified by the specified \fIpath\fR | |
460 | is safe, \fB0\fR otherwise. | |
461 | .VS "" BR | |
462 | .TP | |
463 | \fBinterp marktrusted\fR \fIpath\fR | |
464 | Marks the interpreter identified by \fIpath\fR as trusted. Does | |
465 | not expose the hidden commands. This command can only be invoked from a | |
466 | trusted interpreter. | |
467 | The command has no effect if the interpreter identified by \fIpath\fR is | |
468 | already trusted. | |
469 | .VE | |
470 | .TP | |
471 | \fBinterp\fR \fBrecursionlimit\fR \fIpath\fR ?\fInewlimit\fR? | |
472 | Returns the maximum allowable nesting depth for the interpreter | |
473 | specified by \fIpath\fR. If \fInewlimit\fR is specified, | |
474 | the interpreter recursion limit will be set so that nesting | |
475 | of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR | |
476 | and related procedures in that interpreter will return an error. | |
477 | The \fInewlimit\fR value is also returned. | |
478 | The \fInewlimit\fR value must be a positive integer between 1 and the | |
479 | maximum value of a non-long integer on the platform. | |
480 | .sp | |
481 | The command sets the maximum size of the Tcl call stack only. It cannot | |
482 | by itself prevent stack overflows on the C stack being used by the | |
483 | application. If your machine has a limit on the size of the C stack, you | |
484 | may get stack overflows before reaching the limit set by the command. If | |
485 | this happens, see if there is a mechanism in your system for increasing | |
486 | the maximum size of the C stack. | |
487 | .TP | |
488 | \fBinterp\fR \fBshare\fR \fIsrcPath channelId destPath\fR | |
489 | Causes the IO channel identified by \fIchannelId\fR to become shared | |
490 | between the interpreter identified by \fIsrcPath\fR and the interpreter | |
491 | identified by \fIdestPath\fR. Both interpreters have the same permissions | |
492 | on the IO channel. | |
493 | Both interpreters must close it to close the underlying IO channel; IO | |
494 | channels accessible in an interpreter are automatically closed when an | |
495 | interpreter is destroyed. | |
496 | .TP | |
497 | \fBinterp\fR \fBslaves\fR ?\fIpath\fR? | |
498 | Returns a Tcl list of the names of all the slave interpreters associated | |
499 | with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted, | |
500 | the invoking interpreter is used. | |
501 | .TP | |
502 | \fBinterp\fR \fBtarget\fR \fIpath alias\fR | |
503 | Returns a Tcl list describing the target interpreter for an alias. The | |
504 | alias is specified with an interpreter path and source command name, just | |
505 | as in \fBinterp alias\fR above. The name of the target interpreter is | |
506 | returned as an interpreter path, relative to the invoking interpreter. | |
507 | If the target interpreter for the alias is the invoking interpreter then an | |
508 | empty list is returned. If the target interpreter for the alias is not the | |
509 | invoking interpreter or one of its descendants then an error is generated. | |
510 | The target command does not have to be defined at the time of this invocation. | |
511 | .TP | |
512 | \fBinterp\fR \fBtransfer\fR \fIsrcPath channelId destPath\fR | |
513 | Causes the IO channel identified by \fIchannelId\fR to become available in | |
514 | the interpreter identified by \fIdestPath\fR and unavailable in the | |
515 | interpreter identified by \fIsrcPath\fR. | |
516 | .SH "SLAVE COMMAND" | |
517 | .PP | |
518 | For each slave interpreter created with the \fBinterp\fR command, a | |
519 | new Tcl command is created in the master interpreter with the same | |
520 | name as the new interpreter. This command may be used to invoke | |
521 | various operations on the interpreter. It has the following | |
522 | general form: | |
523 | .CS | |
524 | \fIslave command \fR?\fIarg arg ...\fR? | |
525 | .CE | |
526 | \fISlave\fR is the name of the interpreter, and \fIcommand\fR | |
527 | and the \fIarg\fRs determine the exact behavior of the command. | |
528 | The valid forms of this command are: | |
529 | .TP | |
530 | \fIslave \fBaliases\fR | |
531 | Returns a Tcl list whose elements are the tokens of all the | |
532 | aliases in \fIslave\fR. The tokens correspond to the values returned when | |
533 | the aliases were created (which may not be the same | |
534 | as the current names of the commands). | |
535 | .TP | |
536 | \fIslave \fBalias \fIsrcToken\fR | |
537 | Returns a Tcl list whose elements are the \fItargetCmd\fR and | |
538 | \fIarg\fRs associated with the alias represented by \fIsrcToken\fR | |
539 | (this is the value returned when the alias was | |
540 | created; it is possible that the actual source command in the | |
541 | slave is different from \fIsrcToken\fR). | |
542 | .TP | |
543 | \fIslave \fBalias \fIsrcToken \fB{}\fR | |
544 | Deletes the alias for \fIsrcToken\fR in the slave interpreter. | |
545 | \fIsrcToken\fR refers to the value returned when the alias | |
546 | was created; if the source command has been renamed, the renamed | |
547 | command will be deleted. | |
548 | .TP | |
549 | \fIslave \fBalias \fIsrcCmd targetCmd \fR?\fIarg ..\fR? | |
550 | Creates an alias such that whenever \fIsrcCmd\fR is invoked | |
551 | in \fIslave\fR, \fItargetCmd\fR is invoked in the master. | |
552 | The \fIarg\fR arguments will be passed to \fItargetCmd\fR as additional | |
553 | arguments, prepended before any arguments passed in the invocation of | |
554 | \fIsrcCmd\fR. | |
555 | See \fBALIAS INVOCATION\fR below for details. | |
556 | The command returns a token that uniquely identifies the command created | |
557 | \fIsrcCmd\fR, even if the command is renamed afterwards. The token may but | |
558 | does not have to be equal to \fIsrcCmd\fR. | |
559 | .TP | |
560 | \fIslave \fBeval \fIarg \fR?\fIarg ..\fR? | |
561 | This command concatenates all of the \fIarg\fR arguments in | |
562 | the same fashion as the \fBconcat\fR command, then evaluates | |
563 | the resulting string as a Tcl script in \fIslave\fR. | |
564 | The result of this evaluation (including error information | |
565 | such as the \fBerrorInfo\fR and \fBerrorCode\fR variables, if an | |
566 | error occurs) is returned to the invoking interpreter. | |
567 | Note that the script will be executed in the current context stack frame | |
568 | of \fIslave\fR; this is so that the implementations (in a master | |
569 | interpreter) of aliases in a slave interpreter can execute scripts in | |
570 | the slave that find out information about the slave's current state | |
571 | and stack frame. | |
572 | .VS "" BR | |
573 | .TP | |
574 | \fIslave \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR? | |
575 | This command exposes the hidden command \fIhiddenName\fR, eventually bringing | |
576 | it back under a new \fIexposedCmdName\fR name (this name is currently | |
577 | accepted only if it is a valid global name space name without any ::), | |
578 | in \fIslave\fR. | |
579 | If an exposed command with the targeted name already exists, this command | |
580 | fails. | |
581 | For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. | |
582 | .TP | |
583 | \fIslave \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR? | |
584 | This command hides the exposed command \fIexposedCmdName\fR, renaming it to | |
585 | the hidden command \fIhiddenCmdName\fR, or keeping the same name if the | |
586 | argument is not given, in the \fIslave\fR interpreter. | |
587 | If a hidden command with the targeted name already exists, this command | |
588 | fails. | |
589 | Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can | |
590 | not contain namespace qualifiers, or an error is raised. | |
591 | Commands to be hidden are looked up in the global | |
592 | namespace even if the current namespace is not the global one. This | |
593 | prevents slaves from fooling a master interpreter into hiding the wrong | |
594 | command, by making the current namespace be different from the global one. | |
595 | For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. | |
596 | .TP | |
597 | \fIslave \fBhidden\fR | |
598 | Returns a list of the names of all hidden commands in \fIslave\fR. | |
599 | .TP | |
600 | \fIslave \fBinvokehidden\fR ?\fB-global\fR \fIhiddenName \fR?\fIarg ..\fR? | |
601 | This command invokes the hidden command \fIhiddenName\fR with the | |
602 | supplied arguments, in \fIslave\fR. No substitutions or evaluations are | |
603 | applied to the arguments. | |
604 | If the \fB-global\fR flag is given, the command is invoked at the global | |
605 | level in the slave; otherwise it is invoked at the current call frame and | |
606 | can access local variables in that or outer call frames. | |
607 | For more details on hidden commands, | |
608 | see \fBHIDDEN COMMANDS\fR, below. | |
609 | .VE | |
610 | .TP | |
611 | \fIslave \fBissafe\fR | |
612 | Returns \fB1\fR if the slave interpreter is safe, \fB0\fR otherwise. | |
613 | .VS "" BR | |
614 | .TP | |
615 | \fIslave \fBmarktrusted\fR | |
616 | Marks the slave interpreter as trusted. Can only be invoked by a | |
617 | trusted interpreter. This command does not expose any hidden | |
618 | commands in the slave interpreter. The command has no effect if the slave | |
619 | is already trusted. | |
620 | .VE | |
621 | .TP | |
622 | \fIslave\fR \fBrecursionlimit\fR ?\fInewlimit\fR? | |
623 | Returns the maximum allowable nesting depth for the \fIslave\fR interpreter. | |
624 | If \fInewlimit\fR is specified, the recursion limit in \fIslave\fR will be | |
625 | set so that nesting of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR | |
626 | and related procedures in \fIslave\fR will return an error. | |
627 | The \fInewlimit\fR value is also returned. | |
628 | The \fInewlimit\fR value must be a positive integer between 1 and the | |
629 | maximum value of a non-long integer on the platform. | |
630 | .sp | |
631 | The command sets the maximum size of the Tcl call stack only. It cannot | |
632 | by itself prevent stack overflows on the C stack being used by the | |
633 | application. If your machine has a limit on the size of the C stack, you | |
634 | may get stack overflows before reaching the limit set by the command. If | |
635 | this happens, see if there is a mechanism in your system for increasing | |
636 | the maximum size of the C stack. | |
637 | .SH "SAFE INTERPRETERS" | |
638 | .PP | |
639 | A safe interpreter is one with restricted functionality, so that | |
640 | is safe to execute an arbitrary script from your worst enemy without | |
641 | fear of that script damaging the enclosing application or the rest | |
642 | of your computing environment. In order to make an interpreter | |
643 | safe, certain commands and variables are removed from the interpreter. | |
644 | For example, commands to create files on disk are removed, and the | |
645 | \fBexec\fR command is removed, since it could be used to cause damage | |
646 | through subprocesses. | |
647 | Limited access to these facilities can be provided, by creating | |
648 | aliases to the master interpreter which check their arguments carefully | |
649 | and provide restricted access to a safe subset of facilities. | |
650 | For example, file creation might be allowed in a particular subdirectory | |
651 | and subprocess invocation might be allowed for a carefully selected and | |
652 | fixed set of programs. | |
653 | .PP | |
654 | A safe interpreter is created by specifying the \fB\-safe\fR switch | |
655 | to the \fBinterp create\fR command. Furthermore, any slave created | |
656 | by a safe interpreter will also be safe. | |
657 | .PP | |
658 | A safe interpreter is created with exactly the following set of | |
659 | built-in commands: | |
660 | .DS | |
661 | .ta 1.2i 2.4i 3.6i | |
662 | \fBafter append array binary | |
663 | break case catch clock | |
664 | close concat continue eof | |
665 | error eval expr fblocked | |
666 | fcopy fileevent flush for | |
667 | foreach format gets global | |
668 | if incr info interp | |
669 | join lappend lindex linsert | |
670 | list llength lrange lreplace | |
671 | lsearch lsort namespace package | |
672 | pid proc puts read | |
673 | regexp regsub rename return | |
674 | scan seek set split | |
675 | string subst switch tell | |
676 | time trace unset update | |
677 | uplevel upvar variable vwait | |
678 | while\fR | |
679 | .DE | |
680 | .VS "" BR | |
681 | The following commands are hidden by \fBinterp create\fR when it | |
682 | creates a safe interpreter: | |
683 | .DS | |
684 | .ta 1.2i 2.4i 3.6i | |
685 | \fBcd encoding exec exit | |
686 | fconfigure file glob load | |
687 | open pwd socket source\fR | |
688 | .DE | |
689 | These commands can be recreated later as Tcl procedures or aliases, or | |
690 | re-exposed by \fBinterp expose\fR. | |
691 | .PP | |
692 | The following commands from Tcl's library of support procedures are | |
693 | not present in a safe interpreter: | |
694 | .DS | |
695 | .ta 1.6i 3.2i | |
696 | \fBauto_exec_ok auto_import auto_load | |
697 | auto_load_index auto_qualify unknown\fR | |
698 | .DE | |
699 | Note in particular that safe interpreters have no default \fBunknown\fR | |
700 | command, so Tcl's default autoloading facilities are not available. | |
701 | Autoload access to Tcl's commands that are normally autoloaded: | |
702 | .DS | |
703 | .ta 2.1i | |
704 | \fB | |
705 | auto_mkindex auto_mkindex_old | |
706 | auto_reset history | |
707 | parray pkg_mkIndex | |
708 | ::pkg::create ::safe::interpAddToAccessPath | |
709 | ::safe::interpCreate ::safe::interpConfigure | |
710 | ::safe::interpDelete ::safe::interpFindInAccessPath | |
711 | ::safe::interpInit ::safe::setLogCmd | |
712 | tcl_endOfWord tcl_findLibrary | |
713 | tcl_startOfNextWord tcl_startOfPreviousWord | |
714 | tcl_wordBreakAfter tcl_wordBreakBefore\fR | |
715 | .DE | |
716 | can only be provided by explicit definition of an \fBunknown\fR command | |
717 | in the safe interpreter. This will involve exposing the \fBsource\fR | |
718 | command. This is most easily accomplished by creating the safe interpreter | |
719 | with Tcl's \fBSafe\-Tcl\fR mechanism. \fBSafe\-Tcl\fR provides safe | |
720 | versions of \fBsource\fR, \fBload\fR, and other Tcl commands needed | |
721 | to support autoloading of commands and the loading of packages. | |
722 | .VE | |
723 | .PP | |
724 | In addition, the \fBenv\fR variable is not present in a safe interpreter, | |
725 | so it cannot share environment variables with other interpreters. The | |
726 | \fBenv\fR variable poses a security risk, because users can store | |
727 | sensitive information in an environment variable. For example, the PGP | |
728 | manual recommends storing the PGP private key protection password in | |
729 | the environment variable \fIPGPPASS\fR. Making this variable available | |
730 | to untrusted code executing in a safe interpreter would incur a | |
731 | security risk. | |
732 | .PP | |
733 | If extensions are loaded into a safe interpreter, they may also restrict | |
734 | their own functionality to eliminate unsafe commands. For a discussion of | |
735 | management of extensions for safety see the manual entries for | |
736 | \fBSafe\-Tcl\fR and the \fBload\fR Tcl command. | |
737 | .PP | |
738 | A safe interpreter may not alter the recursion limit of any interpreter, | |
739 | including itself. | |
740 | .SH "ALIAS INVOCATION" | |
741 | .PP | |
742 | The alias mechanism has been carefully designed so that it can | |
743 | be used safely when an untrusted script is executing | |
744 | in a safe slave and the target of the alias is a trusted | |
745 | master. The most important thing in guaranteeing safety is to | |
746 | ensure that information passed from the slave to the master is | |
747 | never evaluated or substituted in the master; if this were to | |
748 | occur, it would enable an evil script in the slave to invoke | |
749 | arbitrary functions in the master, which would compromise security. | |
750 | .PP | |
751 | When the source for an alias is invoked in the slave interpreter, the | |
752 | usual Tcl substitutions are performed when parsing that command. | |
753 | These substitutions are carried out in the source interpreter just | |
754 | as they would be for any other command invoked in that interpreter. | |
755 | The command procedure for the source command takes its arguments | |
756 | and merges them with the \fItargetCmd\fR and \fIarg\fRs for the | |
757 | alias to create a new array of arguments. If the words | |
758 | of \fIsrcCmd\fR were ``\fIsrcCmd arg1 arg2 ... argN\fR'', | |
759 | the new set of words will be | |
760 | ``\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR'', | |
761 | where \fItargetCmd\fR and \fIarg\fRs are the values supplied when the | |
762 | alias was created. \fITargetCmd\fR is then used to locate a command | |
763 | procedure in the target interpreter, and that command procedure | |
764 | is invoked with the new set of arguments. An error occurs if | |
765 | there is no command named \fItargetCmd\fR in the target interpreter. | |
766 | No additional substitutions are performed on the words: the | |
767 | target command procedure is invoked directly, without | |
768 | going through the normal Tcl evaluation mechanism. | |
769 | Substitutions are thus performed on each word exactly once: | |
770 | \fItargetCmd\fR and \fIargs\fR were substituted when parsing the command | |
771 | that created the alias, and \fIarg1 - argN\fR are substituted when | |
772 | the alias's source command is parsed in the source interpreter. | |
773 | .PP | |
774 | When writing the \fItargetCmd\fRs for aliases in safe interpreters, | |
775 | it is very important that the arguments to that command never be | |
776 | evaluated or substituted, since this would provide an escape | |
777 | mechanism whereby the slave interpreter could execute arbitrary | |
778 | code in the master. This in turn would compromise the security | |
779 | of the system. | |
780 | .VS | |
781 | .SH "HIDDEN COMMANDS" | |
782 | .PP | |
783 | Safe interpreters greatly restrict the functionality available to Tcl | |
784 | programs executing within them. | |
785 | Allowing the untrusted Tcl program to have direct access to this | |
786 | functionality is unsafe, because it can be used for a variety of | |
787 | attacks on the environment. | |
788 | However, there are times when there is a legitimate need to use the | |
789 | dangerous functionality in the context of the safe interpreter. For | |
790 | example, sometimes a program must be \fBsource\fRd into the interpreter. | |
791 | Another example is Tk, where windows are bound to the hierarchy of windows | |
792 | for a specific interpreter; some potentially dangerous functions, e.g. | |
793 | window management, must be performed on these windows within the | |
794 | interpreter context. | |
795 | .PP | |
796 | The \fBinterp\fR command provides a solution to this problem in the form of | |
797 | \fIhidden commands\fR. Instead of removing the dangerous commands entirely | |
798 | from a safe interpreter, these commands are hidden so they become | |
799 | unavailable to Tcl scripts executing in the interpreter. However, such | |
800 | hidden commands can be invoked by any trusted ancestor of the safe | |
801 | interpreter, in the context of the safe interpreter, using \fBinterp | |
802 | invoke\fR. Hidden commands and exposed commands reside in separate name | |
803 | spaces. It is possible to define a hidden command and an exposed command by | |
804 | the same name within one interpreter. | |
805 | .PP | |
806 | Hidden commands in a slave interpreter can be invoked in the body of | |
807 | procedures called in the master during alias invocation. For example, an | |
808 | alias for \fBsource\fR could be created in a slave interpreter. When it is | |
809 | invoked in the slave interpreter, a procedure is called in the master | |
810 | interpreter to check that the operation is allowable (e.g. it asks to | |
811 | source a file that the slave interpreter is allowed to access). The | |
812 | procedure then it invokes the hidden \fBsource\fR command in the slave | |
813 | interpreter to actually source in the contents of the file. Note that two | |
814 | commands named \fBsource\fR exist in the slave interpreter: the alias, and | |
815 | the hidden command. | |
816 | .PP | |
817 | Because a master interpreter may invoke a hidden command as part of | |
818 | handling an alias invocation, great care must be taken to avoid evaluating | |
819 | any arguments passed in through the alias invocation. | |
820 | Otherwise, malicious slave interpreters could cause a trusted master | |
821 | interpreter to execute dangerous commands on their behalf. See the section | |
822 | on \fBALIAS INVOCATION\fR for a more complete discussion of this topic. | |
823 | To help avoid this problem, no substitutions or evaluations are | |
824 | applied to arguments of \fBinterp invokehidden\fR. | |
825 | .PP | |
826 | Safe interpreters are not allowed to invoke hidden commands in themselves | |
827 | or in their descendants. This prevents safe slaves from gaining access to | |
828 | hidden functionality in themselves or their descendants. | |
829 | .PP | |
830 | The set of hidden commands in an interpreter can be manipulated by a trusted | |
831 | interpreter using \fBinterp expose\fR and \fBinterp hide\fR. The \fBinterp | |
832 | expose\fR command moves a hidden command to the | |
833 | set of exposed commands in the interpreter identified by \fIpath\fR, | |
834 | potentially renaming the command in the process. If an exposed command by | |
835 | the targeted name already exists, the operation fails. Similarly, | |
836 | \fBinterp hide\fR moves an exposed command to the set of hidden commands in | |
837 | that interpreter. Safe interpreters are not allowed to move commands | |
838 | between the set of hidden and exposed commands, in either themselves or | |
839 | their descendants. | |
840 | .PP | |
841 | Currently, the names of hidden commands cannot contain namespace | |
842 | qualifiers, and you must first rename a command in a namespace to the | |
843 | global namespace before you can hide it. | |
844 | Commands to be hidden by \fBinterp hide\fR are looked up in the global | |
845 | namespace even if the current namespace is not the global one. This | |
846 | prevents slaves from fooling a master interpreter into hiding the wrong | |
847 | command, by making the current namespace be different from the global one. | |
848 | .VE | |
849 | .SH CREDITS | |
850 | .PP | |
851 | This mechanism is based on the Safe-Tcl prototype implemented | |
852 | by Nathaniel Borenstein and Marshall Rose. | |
853 | .SH EXAMPLES | |
854 | Creating and using an alias for a command in the current interpreter: | |
855 | .CS | |
856 | \fBinterp alias\fR {} getIndex {} lsearch {alpha beta gamma delta} | |
857 | set idx [getIndex delta] | |
858 | .CE | |
859 | .PP | |
860 | Executing an arbitrary command in a safe interpreter where every | |
861 | invokation of \fBlappend\fR is logged: | |
862 | .CS | |
863 | set i [\fBinterp create\fR -safe] | |
864 | \fBinterp hide\fR $i lappend | |
865 | \fBinterp alias\fR $i lappend {} loggedLappend $i | |
866 | proc loggedLappend {i args} { | |
867 | puts "logged invokation of lappend $args" | |
868 | # Be extremely careful about command construction | |
869 | eval [linsert $args 0 \\ | |
870 | \fBinterp invokehidden\fR $i lappend] | |
871 | } | |
872 | \fBinterp eval\fR $i $someUntrustedScript | |
873 | .CE | |
874 | ||
875 | .SH "SEE ALSO" | |
876 | load(n), safe(n), Tcl_CreateSlave(3) | |
877 | ||
878 | .SH KEYWORDS | |
879 | alias, master interpreter, safe interpreter, slave interpreter |