| 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 |