[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. |
---|
| 3 | '\" Copyright (c) 2004 Donal K. Fellows |
---|
| 4 | '\" |
---|
| 5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 7 | '\" |
---|
| 8 | '\" RCS: @(#) $Id: interp.n,v 1.38 2007/12/13 15:22:32 dgp Exp $ |
---|
| 9 | '\" |
---|
| 10 | .so man.macros |
---|
| 11 | .TH interp n 7.6 Tcl "Tcl Built-In Commands" |
---|
| 12 | .BS |
---|
| 13 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
| 14 | .SH NAME |
---|
| 15 | interp \- Create and manipulate Tcl interpreters |
---|
| 16 | .SH SYNOPSIS |
---|
| 17 | \fBinterp \fIsubcommand \fR?\fIarg arg ...\fR? |
---|
| 18 | .BE |
---|
| 19 | .SH DESCRIPTION |
---|
| 20 | .PP |
---|
| 21 | This command makes it possible to create one or more new Tcl |
---|
| 22 | interpreters that co-exist with the creating interpreter in the |
---|
| 23 | same application. The creating interpreter is called the \fImaster\fR |
---|
| 24 | and the new interpreter is called a \fIslave\fR. |
---|
| 25 | A master can create any number of slaves, and each slave can |
---|
| 26 | itself create additional slaves for which it is master, resulting |
---|
| 27 | in a hierarchy of interpreters. |
---|
| 28 | .PP |
---|
| 29 | Each interpreter is independent from the others: it has its own name |
---|
| 30 | space for commands, procedures, and global variables. |
---|
| 31 | A master interpreter may create connections between its slaves and |
---|
| 32 | itself using a mechanism called an \fIalias\fR. An \fIalias\fR is |
---|
| 33 | a command in a slave interpreter which, when invoked, causes a |
---|
| 34 | command to be invoked in its master interpreter or in another slave |
---|
| 35 | interpreter. The only other connections between interpreters are |
---|
| 36 | through environment variables (the \fBenv\fR variable), which are |
---|
| 37 | normally shared among all interpreters in the application, |
---|
| 38 | .VS 8.5 |
---|
| 39 | and by resource limit exceeded callbacks. |
---|
| 40 | .VE 8.5 |
---|
| 41 | Note that the |
---|
| 42 | name space for files (such as the names returned by the \fBopen\fR command) |
---|
| 43 | is no longer shared between interpreters. Explicit commands are provided to |
---|
| 44 | share files and to transfer references to open files from one interpreter |
---|
| 45 | to another. |
---|
| 46 | .PP |
---|
| 47 | The \fBinterp\fR command also provides support for \fIsafe\fR |
---|
| 48 | interpreters. A safe interpreter is a slave whose functions have |
---|
| 49 | been greatly restricted, so that it is safe to execute untrusted |
---|
| 50 | scripts without fear of them damaging other interpreters or the |
---|
| 51 | application's environment. For example, all IO channel creation |
---|
| 52 | commands and subprocess creation commands are made inaccessible to safe |
---|
| 53 | interpreters. |
---|
| 54 | See \fBSAFE INTERPRETERS\fR below for more information on |
---|
| 55 | what features are present in a safe interpreter. |
---|
| 56 | The dangerous functionality is not removed from the safe interpreter; |
---|
| 57 | instead, it is \fIhidden\fR, so that only trusted interpreters can obtain |
---|
| 58 | access to it. For a detailed explanation of hidden commands, see |
---|
| 59 | \fBHIDDEN COMMANDS\fR, below. |
---|
| 60 | The alias mechanism can be used for protected communication (analogous to a |
---|
| 61 | kernel call) between a slave interpreter and its master. |
---|
| 62 | See \fBALIAS INVOCATION\fR, below, for more details |
---|
| 63 | on how the alias mechanism works. |
---|
| 64 | .PP |
---|
| 65 | A qualified interpreter name is a proper Tcl lists containing a subset of its |
---|
| 66 | ancestors in the interpreter hierarchy, terminated by the string naming the |
---|
| 67 | interpreter in its immediate master. Interpreter names are relative to the |
---|
| 68 | interpreter in which they are used. For example, if \fBa\fR is a slave of |
---|
| 69 | the current interpreter and it has a slave \fBa1\fR, which in turn has a |
---|
| 70 | slave \fBa11\fR, the qualified name of \fBa11\fR in \fBa\fR is the list |
---|
| 71 | \fBa1 a11\fR. |
---|
| 72 | .PP |
---|
| 73 | The \fBinterp\fR command, described below, accepts qualified interpreter |
---|
| 74 | names as arguments; the interpreter in which the command is being evaluated |
---|
| 75 | can always be referred to as \fB{}\fR (the empty list or string). Note that |
---|
| 76 | it is impossible to refer to a master (ancestor) interpreter by name in a |
---|
| 77 | slave interpreter except through aliases. Also, there is no global name by |
---|
| 78 | which one can refer to the first interpreter created in an application. |
---|
| 79 | Both restrictions are motivated by safety concerns. |
---|
| 80 | .SH "THE INTERP COMMAND" |
---|
| 81 | .PP |
---|
| 82 | The \fBinterp\fR command is used to create, delete, and manipulate |
---|
| 83 | slave interpreters, and to share or transfer |
---|
| 84 | channels between interpreters. It can have any of several forms, depending |
---|
| 85 | on the \fIsubcommand\fR argument: |
---|
| 86 | .TP |
---|
| 87 | \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR |
---|
| 88 | Returns a Tcl list whose elements are the \fItargetCmd\fR and |
---|
| 89 | \fIarg\fRs associated with the alias represented by \fIsrcToken\fR |
---|
| 90 | (this is the value returned when the alias was |
---|
| 91 | created; it is possible that the name of the source command in the |
---|
| 92 | slave is different from \fIsrcToken\fR). |
---|
| 93 | .TP |
---|
| 94 | \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR \fB{}\fR |
---|
| 95 | Deletes the alias for \fIsrcToken\fR in the slave interpreter identified by |
---|
| 96 | \fIsrcPath\fR. |
---|
| 97 | \fIsrcToken\fR refers to the value returned when the alias |
---|
| 98 | was created; if the source command has been renamed, the renamed |
---|
| 99 | command will be deleted. |
---|
| 100 | .TP |
---|
| 101 | \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR \fItargetPath\fR \fItargetCmd \fR?\fIarg arg ...\fR? |
---|
| 102 | This command creates an alias between one slave and another (see the |
---|
| 103 | \fBalias\fR slave command below for creating aliases between a slave |
---|
| 104 | and its master). In this command, either of the slave interpreters |
---|
| 105 | may be anywhere in the hierarchy of interpreters under the interpreter |
---|
| 106 | invoking the command. |
---|
| 107 | \fISrcPath\fR and \fIsrcCmd\fR identify the source of the alias. |
---|
| 108 | \fISrcPath\fR is a Tcl list whose elements select a particular |
---|
| 109 | interpreter. For example, |
---|
| 110 | .QW "\fBa b\fR" |
---|
| 111 | identifies an interpreter |
---|
| 112 | \fBb\fR, which is a slave of interpreter \fBa\fR, which is a slave |
---|
| 113 | of the invoking interpreter. An empty list specifies the interpreter |
---|
| 114 | invoking the command. \fIsrcCmd\fR gives the name of a new |
---|
| 115 | command, which will be created in the source interpreter. |
---|
| 116 | \fITargetPath\fR and \fItargetCmd\fR specify a target interpreter |
---|
| 117 | and command, and the \fIarg\fR arguments, if any, specify additional |
---|
| 118 | arguments to \fItargetCmd\fR which are prepended to any arguments specified |
---|
| 119 | in the invocation of \fIsrcCmd\fR. |
---|
| 120 | \fITargetCmd\fR may be undefined at the time of this call, or it may |
---|
| 121 | already exist; it is not created by this command. |
---|
| 122 | The alias arranges for the given target command to be invoked |
---|
| 123 | in the target interpreter whenever the given source command is |
---|
| 124 | invoked in the source interpreter. See \fBALIAS INVOCATION\fR below for |
---|
| 125 | more details. |
---|
| 126 | The command returns a token that uniquely identifies the command created |
---|
| 127 | \fIsrcCmd\fR, even if the command is renamed afterwards. The token may but |
---|
| 128 | does not have to be equal to \fIsrcCmd\fR. |
---|
| 129 | .TP |
---|
| 130 | \fBinterp\fR \fBaliases \fR?\fIpath\fR? |
---|
| 131 | This command returns a Tcl list of the tokens of all the source commands for |
---|
| 132 | aliases defined in the interpreter identified by \fIpath\fR. The tokens |
---|
| 133 | correspond to the values returned when |
---|
| 134 | the aliases were created (which may not be the same |
---|
| 135 | as the current names of the commands). |
---|
| 136 | .TP |
---|
| 137 | \fBinterp bgerror \fIpath\fR ?\fIcmdPrefix\fR? |
---|
| 138 | .VS 8.5 |
---|
| 139 | This command either gets or sets the current background error handler |
---|
| 140 | for the interpreter identified by \fIpath\fR. If \fIcmdPrefix\fR is |
---|
| 141 | absent, the current background error handler is returned, and if it is |
---|
| 142 | present, it is a list of words (of minimum length one) that describes |
---|
| 143 | what to set the interpreter's background error to. See the |
---|
| 144 | \fBBACKGROUND ERROR HANDLING\fR section for more details. |
---|
| 145 | .VE 8.5 |
---|
| 146 | .TP |
---|
| 147 | \fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? |
---|
| 148 | Creates a slave interpreter identified by \fIpath\fR and a new command, |
---|
| 149 | called a \fIslave command\fR. The name of the slave command is the last |
---|
| 150 | component of \fIpath\fR. The new slave interpreter and the slave command |
---|
| 151 | are created in the interpreter identified by the path obtained by removing |
---|
| 152 | the last component from \fIpath\fR. For example, if \fIpath\fR is \fBa b |
---|
| 153 | c\fR then a new slave interpreter and slave command named \fBc\fR are |
---|
| 154 | created in the interpreter identified by the path \fBa b\fR. |
---|
| 155 | The slave command may be used to manipulate the new interpreter as |
---|
| 156 | described below. If \fIpath\fR is omitted, Tcl creates a unique name of the |
---|
| 157 | form \fBinterp\fIx\fR, where \fIx\fR is an integer, and uses it for the |
---|
| 158 | interpreter and the slave command. If the \fB\-safe\fR switch is specified |
---|
| 159 | (or if the master interpreter is a safe interpreter), the new slave |
---|
| 160 | interpreter will be created as a safe interpreter with limited |
---|
| 161 | functionality; otherwise the slave will include the full set of Tcl |
---|
| 162 | built-in commands and variables. The \fB\-\|\-\fR switch can be used to |
---|
| 163 | mark the end of switches; it may be needed if \fIpath\fR is an unusual |
---|
| 164 | value such as \fB\-safe\fR. The result of the command is the name of the |
---|
| 165 | new interpreter. The name of a slave interpreter must be unique among all |
---|
| 166 | the slaves for its master; an error occurs if a slave interpreter by the |
---|
| 167 | given name already exists in this master. |
---|
| 168 | The initial recursion limit of the slave interpreter is set to the |
---|
| 169 | current recursion limit of its parent interpreter. |
---|
| 170 | .TP |
---|
| 171 | \fBinterp\fR \fBdelete \fR?\fIpath ...?\fR |
---|
| 172 | Deletes zero or more interpreters given by the optional \fIpath\fR |
---|
| 173 | arguments, and for each interpreter, it also deletes its slaves. The |
---|
| 174 | command also deletes the slave command for each interpreter deleted. |
---|
| 175 | For each \fIpath\fR argument, if no interpreter by that name |
---|
| 176 | exists, the command raises an error. |
---|
| 177 | .TP |
---|
| 178 | \fBinterp\fR \fBeval\fR \fIpath arg \fR?\fIarg ...\fR? |
---|
| 179 | This command concatenates all of the \fIarg\fR arguments in the same |
---|
| 180 | fashion as the \fBconcat\fR command, then evaluates the resulting string as |
---|
| 181 | a Tcl script in the slave interpreter identified by \fIpath\fR. The result |
---|
| 182 | of this evaluation (including all \fBreturn\fR options, |
---|
| 183 | such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an |
---|
| 184 | error occurs) is returned to the invoking interpreter. |
---|
| 185 | Note that the script will be executed in the current context stack frame of the |
---|
| 186 | \fIpath\fR interpreter; this is so that the implementations (in a master |
---|
| 187 | interpreter) of aliases in a slave interpreter can execute scripts in |
---|
| 188 | the slave that find out information about the slave's current state |
---|
| 189 | and stack frame. |
---|
| 190 | .TP |
---|
| 191 | \fBinterp exists \fIpath\fR |
---|
| 192 | Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR |
---|
| 193 | exists in this master, \fB0\fR otherwise. If \fIpath\fR is omitted, the |
---|
| 194 | invoking interpreter is used. |
---|
| 195 | .TP |
---|
| 196 | \fBinterp expose \fIpath\fR \fIhiddenName\fR ?\fIexposedCmdName\fR? |
---|
| 197 | Makes the hidden command \fIhiddenName\fR exposed, eventually bringing |
---|
| 198 | it back under a new \fIexposedCmdName\fR name (this name is currently |
---|
| 199 | accepted only if it is a valid global name space name without any ::), |
---|
| 200 | in the interpreter |
---|
| 201 | denoted by \fIpath\fR. |
---|
| 202 | If an exposed command with the targeted name already exists, this command |
---|
| 203 | fails. |
---|
| 204 | Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. |
---|
| 205 | .TP |
---|
| 206 | \fBinterp\fR \fBhide\fR \fIpath\fR \fIexposedCmdName\fR ?\fIhiddenCmdName\fR? |
---|
| 207 | Makes the exposed command \fIexposedCmdName\fR hidden, renaming |
---|
| 208 | it to the hidden command \fIhiddenCmdName\fR, or keeping the same name if |
---|
| 209 | \fIhiddenCmdName\fR is not given, in the interpreter denoted |
---|
| 210 | by \fIpath\fR. |
---|
| 211 | If a hidden command with the targeted name already exists, this command |
---|
| 212 | fails. |
---|
| 213 | Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can |
---|
| 214 | not contain namespace qualifiers, or an error is raised. |
---|
| 215 | Commands to be hidden by \fBinterp hide\fR are looked up in the global |
---|
| 216 | namespace even if the current namespace is not the global one. This |
---|
| 217 | prevents slaves from fooling a master interpreter into hiding the wrong |
---|
| 218 | command, by making the current namespace be different from the global one. |
---|
| 219 | Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. |
---|
| 220 | .TP |
---|
| 221 | \fBinterp\fR \fBhidden\fR \fIpath\fR |
---|
| 222 | Returns a list of the names of all hidden commands in the interpreter |
---|
| 223 | identified by \fIpath\fR. |
---|
| 224 | .TP |
---|
| 225 | \fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fI\-option ...\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR? |
---|
| 226 | Invokes the hidden command \fIhiddenCmdName\fR with the arguments supplied |
---|
| 227 | in the interpreter denoted by \fIpath\fR. No substitutions or evaluation |
---|
| 228 | are applied to the arguments. Three \fI\-option\fRs are supported, all |
---|
| 229 | of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single |
---|
| 230 | argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR. |
---|
| 231 | If the \fB\-namespace\fR flag is present, the hidden command is invoked in |
---|
| 232 | the namespace called \fInsName\fR in the target interpreter. |
---|
| 233 | If the \fB\-global\fR flag is present, the hidden command is invoked at the |
---|
| 234 | global level in the target interpreter; otherwise it is invoked at the |
---|
| 235 | current call frame and can access local variables in that and outer call |
---|
| 236 | frames. |
---|
| 237 | The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a |
---|
| 238 | .QW \- |
---|
| 239 | character, and is otherwise unnecessary. |
---|
| 240 | If both the \fB\-namespace\fR and \fB\-global\fR flags are present, the |
---|
| 241 | \fB\-namespace\fR flag is ignored. |
---|
| 242 | Note that the hidden command will be executed (by default) in the |
---|
| 243 | current context stack frame of the \fIpath\fR interpreter. |
---|
| 244 | Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. |
---|
| 245 | .TP |
---|
| 246 | \fBinterp\fR \fBlimit\fR \fIpath\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR? |
---|
| 247 | .VS 8.5 |
---|
| 248 | Sets up, manipulates and queries the configuration of the resource |
---|
| 249 | limit \fIlimitType\fR for the interpreter denoted by \fIpath\fR. If |
---|
| 250 | no \fI\-option\fR is specified, return the current configuration of the |
---|
| 251 | limit. If \fI\-option\fR is the sole argument, return the value of that |
---|
| 252 | option. Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs |
---|
| 253 | must supplied. See \fBRESOURCE LIMITS\fR below for a more detailed |
---|
| 254 | explanation of what limits and options are supported. |
---|
| 255 | .VE 8.5 |
---|
| 256 | .TP |
---|
| 257 | \fBinterp issafe\fR ?\fIpath\fR? |
---|
| 258 | Returns \fB1\fR if the interpreter identified by the specified \fIpath\fR |
---|
| 259 | is safe, \fB0\fR otherwise. |
---|
| 260 | .TP |
---|
| 261 | \fBinterp marktrusted\fR \fIpath\fR |
---|
| 262 | Marks the interpreter identified by \fIpath\fR as trusted. Does |
---|
| 263 | not expose the hidden commands. This command can only be invoked from a |
---|
| 264 | trusted interpreter. |
---|
| 265 | The command has no effect if the interpreter identified by \fIpath\fR is |
---|
| 266 | already trusted. |
---|
| 267 | .TP |
---|
| 268 | \fBinterp\fR \fBrecursionlimit\fR \fIpath\fR ?\fInewlimit\fR? |
---|
| 269 | Returns the maximum allowable nesting depth for the interpreter |
---|
| 270 | specified by \fIpath\fR. If \fInewlimit\fR is specified, |
---|
| 271 | the interpreter recursion limit will be set so that nesting |
---|
| 272 | of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR |
---|
| 273 | and related procedures in that interpreter will return an error. |
---|
| 274 | The \fInewlimit\fR value is also returned. |
---|
| 275 | The \fInewlimit\fR value must be a positive integer between 1 and the |
---|
| 276 | maximum value of a non-long integer on the platform. |
---|
| 277 | .RS |
---|
| 278 | .PP |
---|
| 279 | The command sets the maximum size of the Tcl call stack only. It cannot |
---|
| 280 | by itself prevent stack overflows on the C stack being used by the |
---|
| 281 | application. If your machine has a limit on the size of the C stack, you |
---|
| 282 | may get stack overflows before reaching the limit set by the command. If |
---|
| 283 | this happens, see if there is a mechanism in your system for increasing |
---|
| 284 | the maximum size of the C stack. |
---|
| 285 | .RE |
---|
| 286 | .TP |
---|
| 287 | \fBinterp\fR \fBshare\fR \fIsrcPath channelId destPath\fR |
---|
| 288 | Causes the IO channel identified by \fIchannelId\fR to become shared |
---|
| 289 | between the interpreter identified by \fIsrcPath\fR and the interpreter |
---|
| 290 | identified by \fIdestPath\fR. Both interpreters have the same permissions |
---|
| 291 | on the IO channel. |
---|
| 292 | Both interpreters must close it to close the underlying IO channel; IO |
---|
| 293 | channels accessible in an interpreter are automatically closed when an |
---|
| 294 | interpreter is destroyed. |
---|
| 295 | .TP |
---|
| 296 | \fBinterp\fR \fBslaves\fR ?\fIpath\fR? |
---|
| 297 | Returns a Tcl list of the names of all the slave interpreters associated |
---|
| 298 | with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted, |
---|
| 299 | the invoking interpreter is used. |
---|
| 300 | .TP |
---|
| 301 | \fBinterp\fR \fBtarget\fR \fIpath alias\fR |
---|
| 302 | Returns a Tcl list describing the target interpreter for an alias. The |
---|
| 303 | alias is specified with an interpreter path and source command name, just |
---|
| 304 | as in \fBinterp alias\fR above. The name of the target interpreter is |
---|
| 305 | returned as an interpreter path, relative to the invoking interpreter. |
---|
| 306 | If the target interpreter for the alias is the invoking interpreter then an |
---|
| 307 | empty list is returned. If the target interpreter for the alias is not the |
---|
| 308 | invoking interpreter or one of its descendants then an error is generated. |
---|
| 309 | The target command does not have to be defined at the time of this invocation. |
---|
| 310 | .TP |
---|
| 311 | \fBinterp\fR \fBtransfer\fR \fIsrcPath channelId destPath\fR |
---|
| 312 | Causes the IO channel identified by \fIchannelId\fR to become available in |
---|
| 313 | the interpreter identified by \fIdestPath\fR and unavailable in the |
---|
| 314 | interpreter identified by \fIsrcPath\fR. |
---|
| 315 | .SH "SLAVE COMMAND" |
---|
| 316 | .PP |
---|
| 317 | For each slave interpreter created with the \fBinterp\fR command, a |
---|
| 318 | new Tcl command is created in the master interpreter with the same |
---|
| 319 | name as the new interpreter. This command may be used to invoke |
---|
| 320 | various operations on the interpreter. It has the following |
---|
| 321 | general form: |
---|
| 322 | .CS |
---|
| 323 | \fIslave command \fR?\fIarg arg ...\fR? |
---|
| 324 | .CE |
---|
| 325 | \fISlave\fR is the name of the interpreter, and \fIcommand\fR |
---|
| 326 | and the \fIarg\fRs determine the exact behavior of the command. |
---|
| 327 | The valid forms of this command are: |
---|
| 328 | .TP |
---|
| 329 | \fIslave \fBaliases\fR |
---|
| 330 | Returns a Tcl list whose elements are the tokens of all the |
---|
| 331 | aliases in \fIslave\fR. The tokens correspond to the values returned when |
---|
| 332 | the aliases were created (which may not be the same |
---|
| 333 | as the current names of the commands). |
---|
| 334 | .TP |
---|
| 335 | \fIslave \fBalias \fIsrcToken\fR |
---|
| 336 | Returns a Tcl list whose elements are the \fItargetCmd\fR and |
---|
| 337 | \fIarg\fRs associated with the alias represented by \fIsrcToken\fR |
---|
| 338 | (this is the value returned when the alias was |
---|
| 339 | created; it is possible that the actual source command in the |
---|
| 340 | slave is different from \fIsrcToken\fR). |
---|
| 341 | .TP |
---|
| 342 | \fIslave \fBalias \fIsrcToken \fB{}\fR |
---|
| 343 | Deletes the alias for \fIsrcToken\fR in the slave interpreter. |
---|
| 344 | \fIsrcToken\fR refers to the value returned when the alias |
---|
| 345 | was created; if the source command has been renamed, the renamed |
---|
| 346 | command will be deleted. |
---|
| 347 | .TP |
---|
| 348 | \fIslave \fBalias \fIsrcCmd targetCmd \fR?\fIarg ..\fR? |
---|
| 349 | Creates an alias such that whenever \fIsrcCmd\fR is invoked |
---|
| 350 | in \fIslave\fR, \fItargetCmd\fR is invoked in the master. |
---|
| 351 | The \fIarg\fR arguments will be passed to \fItargetCmd\fR as additional |
---|
| 352 | arguments, prepended before any arguments passed in the invocation of |
---|
| 353 | \fIsrcCmd\fR. |
---|
| 354 | See \fBALIAS INVOCATION\fR below for details. |
---|
| 355 | The command returns a token that uniquely identifies the command created |
---|
| 356 | \fIsrcCmd\fR, even if the command is renamed afterwards. The token may but |
---|
| 357 | does not have to be equal to \fIsrcCmd\fR. |
---|
| 358 | .TP |
---|
| 359 | \fIslave \fBbgerror\fR ?\fIcmdPrefix\fR? |
---|
| 360 | .VS 8.5 |
---|
| 361 | This command either gets or sets the current background error handler |
---|
| 362 | for the \fIslave\fR interpreter. If \fIcmdPrefix\fR is |
---|
| 363 | absent, the current background error handler is returned, and if it is |
---|
| 364 | present, it is a list of words (of minimum length one) that describes |
---|
| 365 | what to set the interpreter's background error to. See the |
---|
| 366 | \fBBACKGROUND ERROR HANDLING\fR section for more details. |
---|
| 367 | .VE 8.5 |
---|
| 368 | .TP |
---|
| 369 | \fIslave \fBeval \fIarg \fR?\fIarg ..\fR? |
---|
| 370 | This command concatenates all of the \fIarg\fR arguments in |
---|
| 371 | the same fashion as the \fBconcat\fR command, then evaluates |
---|
| 372 | the resulting string as a Tcl script in \fIslave\fR. |
---|
| 373 | The result of this evaluation (including all \fBreturn\fR options, |
---|
| 374 | such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an |
---|
| 375 | error occurs) is returned to the invoking interpreter. |
---|
| 376 | Note that the script will be executed in the current context stack frame |
---|
| 377 | of \fIslave\fR; this is so that the implementations (in a master |
---|
| 378 | interpreter) of aliases in a slave interpreter can execute scripts in |
---|
| 379 | the slave that find out information about the slave's current state |
---|
| 380 | and stack frame. |
---|
| 381 | .TP |
---|
| 382 | \fIslave \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR? |
---|
| 383 | This command exposes the hidden command \fIhiddenName\fR, eventually bringing |
---|
| 384 | it back under a new \fIexposedCmdName\fR name (this name is currently |
---|
| 385 | accepted only if it is a valid global name space name without any ::), |
---|
| 386 | in \fIslave\fR. |
---|
| 387 | If an exposed command with the targeted name already exists, this command |
---|
| 388 | fails. |
---|
| 389 | For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. |
---|
| 390 | .TP |
---|
| 391 | \fIslave \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR? |
---|
| 392 | This command hides the exposed command \fIexposedCmdName\fR, renaming it to |
---|
| 393 | the hidden command \fIhiddenCmdName\fR, or keeping the same name if the |
---|
| 394 | argument is not given, in the \fIslave\fR interpreter. |
---|
| 395 | If a hidden command with the targeted name already exists, this command |
---|
| 396 | fails. |
---|
| 397 | Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can |
---|
| 398 | not contain namespace qualifiers, or an error is raised. |
---|
| 399 | Commands to be hidden are looked up in the global |
---|
| 400 | namespace even if the current namespace is not the global one. This |
---|
| 401 | prevents slaves from fooling a master interpreter into hiding the wrong |
---|
| 402 | command, by making the current namespace be different from the global one. |
---|
| 403 | For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. |
---|
| 404 | .TP |
---|
| 405 | \fIslave \fBhidden\fR |
---|
| 406 | Returns a list of the names of all hidden commands in \fIslave\fR. |
---|
| 407 | .TP |
---|
| 408 | \fIslave \fBinvokehidden\fR ?\fI\-option ...\fR? \fIhiddenName \fR?\fIarg ..\fR? |
---|
| 409 | This command invokes the hidden command \fIhiddenName\fR with the |
---|
| 410 | supplied arguments, in \fIslave\fR. No substitutions or evaluations are |
---|
| 411 | applied to the arguments. Three \fI\-option\fRs are supported, all |
---|
| 412 | of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single |
---|
| 413 | argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR. |
---|
| 414 | If the \fB\-namespace\fR flag is given, the hidden command is invoked in |
---|
| 415 | the specified namespace in the slave. |
---|
| 416 | If the \fB\-global\fR flag is given, the command is invoked at the global |
---|
| 417 | level in the slave; otherwise it is invoked at the current call frame and |
---|
| 418 | can access local variables in that or outer call frames. |
---|
| 419 | The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a |
---|
| 420 | .QW \- |
---|
| 421 | character, and is otherwise unnecessary. |
---|
| 422 | If both the \fB\-namespace\fR and \fB\-global\fR flags are given, the |
---|
| 423 | \fB\-namespace\fR flag is ignored. |
---|
| 424 | Note that the hidden command will be executed (by default) in the |
---|
| 425 | current context stack frame of \fIslave\fR. |
---|
| 426 | For more details on hidden commands, |
---|
| 427 | see \fBHIDDEN COMMANDS\fR, below. |
---|
| 428 | .TP |
---|
| 429 | \fIslave \fBissafe\fR |
---|
| 430 | Returns \fB1\fR if the slave interpreter is safe, \fB0\fR otherwise. |
---|
| 431 | .TP |
---|
| 432 | \fIslave \fBlimit\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR? |
---|
| 433 | .VS 8.5 |
---|
| 434 | Sets up, manipulates and queries the configuration of the resource |
---|
| 435 | limit \fIlimitType\fR for the slave interpreter. If no \fI\-option\fR |
---|
| 436 | is specified, return the current configuration of the limit. If |
---|
| 437 | \fI\-option\fR is the sole argument, return the value of that option. |
---|
| 438 | Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must |
---|
| 439 | supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of |
---|
| 440 | what limits and options are supported. |
---|
| 441 | .VE 8.5 |
---|
| 442 | .TP |
---|
| 443 | \fIslave \fBmarktrusted\fR |
---|
| 444 | Marks the slave interpreter as trusted. Can only be invoked by a |
---|
| 445 | trusted interpreter. This command does not expose any hidden |
---|
| 446 | commands in the slave interpreter. The command has no effect if the slave |
---|
| 447 | is already trusted. |
---|
| 448 | .TP |
---|
| 449 | \fIslave\fR \fBrecursionlimit\fR ?\fInewlimit\fR? |
---|
| 450 | Returns the maximum allowable nesting depth for the \fIslave\fR interpreter. |
---|
| 451 | If \fInewlimit\fR is specified, the recursion limit in \fIslave\fR will be |
---|
| 452 | set so that nesting of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR |
---|
| 453 | and related procedures in \fIslave\fR will return an error. |
---|
| 454 | The \fInewlimit\fR value is also returned. |
---|
| 455 | The \fInewlimit\fR value must be a positive integer between 1 and the |
---|
| 456 | maximum value of a non-long integer on the platform. |
---|
| 457 | .RS |
---|
| 458 | .PP |
---|
| 459 | The command sets the maximum size of the Tcl call stack only. It cannot |
---|
| 460 | by itself prevent stack overflows on the C stack being used by the |
---|
| 461 | application. If your machine has a limit on the size of the C stack, you |
---|
| 462 | may get stack overflows before reaching the limit set by the command. If |
---|
| 463 | this happens, see if there is a mechanism in your system for increasing |
---|
| 464 | the maximum size of the C stack. |
---|
| 465 | .RE |
---|
| 466 | .SH "SAFE INTERPRETERS" |
---|
| 467 | .PP |
---|
| 468 | A safe interpreter is one with restricted functionality, so that |
---|
| 469 | is safe to execute an arbitrary script from your worst enemy without |
---|
| 470 | fear of that script damaging the enclosing application or the rest |
---|
| 471 | of your computing environment. In order to make an interpreter |
---|
| 472 | safe, certain commands and variables are removed from the interpreter. |
---|
| 473 | For example, commands to create files on disk are removed, and the |
---|
| 474 | \fBexec\fR command is removed, since it could be used to cause damage |
---|
| 475 | through subprocesses. |
---|
| 476 | Limited access to these facilities can be provided, by creating |
---|
| 477 | aliases to the master interpreter which check their arguments carefully |
---|
| 478 | and provide restricted access to a safe subset of facilities. |
---|
| 479 | For example, file creation might be allowed in a particular subdirectory |
---|
| 480 | and subprocess invocation might be allowed for a carefully selected and |
---|
| 481 | fixed set of programs. |
---|
| 482 | .PP |
---|
| 483 | A safe interpreter is created by specifying the \fB\-safe\fR switch |
---|
| 484 | to the \fBinterp create\fR command. Furthermore, any slave created |
---|
| 485 | by a safe interpreter will also be safe. |
---|
| 486 | .PP |
---|
| 487 | A safe interpreter is created with exactly the following set of |
---|
| 488 | built-in commands: |
---|
| 489 | .DS |
---|
| 490 | .ta 1.2i 2.4i 3.6i |
---|
| 491 | \fBafter\fR \fBappend\fR \fBapply\fR \fBarray\fR |
---|
| 492 | \fBbinary\fR \fBbreak\fR \fBcatch\fR \fBchan\fR |
---|
| 493 | \fBclock\fR \fBclose\fR \fBconcat\fR \fBcontinue\fR |
---|
| 494 | \fBdict\fR \fBeof\fR \fBerror\fR \fBeval\fR |
---|
| 495 | \fBexpr\fR \fBfblocked\fR \fBfcopy\fR \fBfileevent\fR |
---|
| 496 | \fBflush\fR \fBfor\fR \fBforeach\fR \fBformat\fR |
---|
| 497 | \fBgets\fR \fBglobal\fR \fBif\fR \fBincr\fR |
---|
| 498 | \fBinfo\fR \fBinterp\fR \fBjoin\fR \fBlappend\fR |
---|
| 499 | \fBlassign\fR \fBlindex\fR \fBlinsert\fR \fBlist\fR |
---|
| 500 | \fBllength\fR \fBlrange\fR \fBlrepeat\fR \fBlreplace\fR |
---|
| 501 | \fBlsearch\fR \fBlset\fR \fBlsort\fR \fBnamespace\fR |
---|
| 502 | \fBpackage\fR \fBpid\fR \fBproc\fR \fBputs\fR |
---|
| 503 | \fBread\fR \fBregexp\fR \fBregsub\fR \fBrename\fR |
---|
| 504 | \fBreturn\fR \fBscan\fR \fBseek\fR \fBset\fR |
---|
| 505 | \fBsplit\fR \fBstring\fR \fBsubst\fR \fBswitch\fR |
---|
| 506 | \fBtell\fR \fBtime\fR \fBtrace\fR \fBunset\fR |
---|
| 507 | \fBupdate\fR \fBuplevel\fR \fBupvar\fR \fBvariable\fR |
---|
| 508 | \fBvwait\fR \fBwhile\fR |
---|
| 509 | .DE |
---|
| 510 | The following commands are hidden by \fBinterp create\fR when it |
---|
| 511 | creates a safe interpreter: |
---|
| 512 | .DS |
---|
| 513 | .ta 1.2i 2.4i 3.6i |
---|
| 514 | \fBcd\fR \fBencoding\fR \fBexec\fR \fBexit\fR |
---|
| 515 | \fBfconfigure\fR \fBfile\fR \fBglob\fR \fBload\fR |
---|
| 516 | \fBopen\fR \fBpwd\fR \fBsocket\fR \fBsource\fR |
---|
| 517 | \fBunload\fR |
---|
| 518 | .DE |
---|
| 519 | These commands can be recreated later as Tcl procedures or aliases, or |
---|
| 520 | re-exposed by \fBinterp expose\fR. |
---|
| 521 | .PP |
---|
| 522 | The following commands from Tcl's library of support procedures are |
---|
| 523 | not present in a safe interpreter: |
---|
| 524 | .DS |
---|
| 525 | .ta 1.6i 3.2i |
---|
| 526 | \fBauto_exec_ok\fR \fBauto_import\fR \fBauto_load\fR |
---|
| 527 | \fBauto_load_index\fR \fBauto_qualify\fR \fBunknown\fR |
---|
| 528 | .DE |
---|
| 529 | Note in particular that safe interpreters have no default \fBunknown\fR |
---|
| 530 | command, so Tcl's default autoloading facilities are not available. |
---|
| 531 | Autoload access to Tcl's commands that are normally autoloaded: |
---|
| 532 | .DS |
---|
| 533 | .ta 2.1i |
---|
| 534 | \fBauto_mkindex\fR \fBauto_mkindex_old\fR |
---|
| 535 | \fBauto_reset\fR \fBhistory\fR |
---|
| 536 | \fBparray\fR \fBpkg_mkIndex\fR |
---|
| 537 | \fB::pkg::create\fR \fB::safe::interpAddToAccessPath\fR |
---|
| 538 | \fB::safe::interpCreate\fR \fB::safe::interpConfigure\fR |
---|
| 539 | \fB::safe::interpDelete\fR \fB::safe::interpFindInAccessPath\fR |
---|
| 540 | \fB::safe::interpInit\fR \fB::safe::setLogCmd\fR |
---|
| 541 | \fBtcl_endOfWord\fR \fBtcl_findLibrary\fR |
---|
| 542 | \fBtcl_startOfNextWord\fR \fBtcl_startOfPreviousWord\fR |
---|
| 543 | \fBtcl_wordBreakAfter\fR \fBtcl_wordBreakBefore\fR |
---|
| 544 | .DE |
---|
| 545 | can only be provided by explicit definition of an \fBunknown\fR command |
---|
| 546 | in the safe interpreter. This will involve exposing the \fBsource\fR |
---|
| 547 | command. This is most easily accomplished by creating the safe interpreter |
---|
| 548 | with Tcl's \fBSafe\-Tcl\fR mechanism. \fBSafe\-Tcl\fR provides safe |
---|
| 549 | versions of \fBsource\fR, \fBload\fR, and other Tcl commands needed |
---|
| 550 | to support autoloading of commands and the loading of packages. |
---|
| 551 | .PP |
---|
| 552 | In addition, the \fBenv\fR variable is not present in a safe interpreter, |
---|
| 553 | so it cannot share environment variables with other interpreters. The |
---|
| 554 | \fBenv\fR variable poses a security risk, because users can store |
---|
| 555 | sensitive information in an environment variable. For example, the PGP |
---|
| 556 | manual recommends storing the PGP private key protection password in |
---|
| 557 | the environment variable \fIPGPPASS\fR. Making this variable available |
---|
| 558 | to untrusted code executing in a safe interpreter would incur a |
---|
| 559 | security risk. |
---|
| 560 | .PP |
---|
| 561 | If extensions are loaded into a safe interpreter, they may also restrict |
---|
| 562 | their own functionality to eliminate unsafe commands. For a discussion of |
---|
| 563 | management of extensions for safety see the manual entries for |
---|
| 564 | \fBSafe\-Tcl\fR and the \fBload\fR Tcl command. |
---|
| 565 | .PP |
---|
| 566 | A safe interpreter may not alter the recursion limit of any interpreter, |
---|
| 567 | including itself. |
---|
| 568 | .SH "ALIAS INVOCATION" |
---|
| 569 | .PP |
---|
| 570 | The alias mechanism has been carefully designed so that it can |
---|
| 571 | be used safely when an untrusted script is executing |
---|
| 572 | in a safe slave and the target of the alias is a trusted |
---|
| 573 | master. The most important thing in guaranteeing safety is to |
---|
| 574 | ensure that information passed from the slave to the master is |
---|
| 575 | never evaluated or substituted in the master; if this were to |
---|
| 576 | occur, it would enable an evil script in the slave to invoke |
---|
| 577 | arbitrary functions in the master, which would compromise security. |
---|
| 578 | .PP |
---|
| 579 | When the source for an alias is invoked in the slave interpreter, the |
---|
| 580 | usual Tcl substitutions are performed when parsing that command. |
---|
| 581 | These substitutions are carried out in the source interpreter just |
---|
| 582 | as they would be for any other command invoked in that interpreter. |
---|
| 583 | The command procedure for the source command takes its arguments |
---|
| 584 | and merges them with the \fItargetCmd\fR and \fIarg\fRs for the |
---|
| 585 | alias to create a new array of arguments. If the words |
---|
| 586 | of \fIsrcCmd\fR were |
---|
| 587 | .QW "\fIsrcCmd arg1 arg2 ... argN\fR" , |
---|
| 588 | the new set of words will be |
---|
| 589 | .QW "\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR" , |
---|
| 590 | where \fItargetCmd\fR and \fIarg\fRs are the values supplied when the |
---|
| 591 | alias was created. \fITargetCmd\fR is then used to locate a command |
---|
| 592 | procedure in the target interpreter, and that command procedure |
---|
| 593 | is invoked with the new set of arguments. An error occurs if |
---|
| 594 | there is no command named \fItargetCmd\fR in the target interpreter. |
---|
| 595 | No additional substitutions are performed on the words: the |
---|
| 596 | target command procedure is invoked directly, without |
---|
| 597 | going through the normal Tcl evaluation mechanism. |
---|
| 598 | Substitutions are thus performed on each word exactly once: |
---|
| 599 | \fItargetCmd\fR and \fIargs\fR were substituted when parsing the command |
---|
| 600 | that created the alias, and \fIarg1 - argN\fR are substituted when |
---|
| 601 | the alias's source command is parsed in the source interpreter. |
---|
| 602 | .PP |
---|
| 603 | When writing the \fItargetCmd\fRs for aliases in safe interpreters, |
---|
| 604 | it is very important that the arguments to that command never be |
---|
| 605 | evaluated or substituted, since this would provide an escape |
---|
| 606 | mechanism whereby the slave interpreter could execute arbitrary |
---|
| 607 | code in the master. This in turn would compromise the security |
---|
| 608 | of the system. |
---|
| 609 | .SH "HIDDEN COMMANDS" |
---|
| 610 | .PP |
---|
| 611 | Safe interpreters greatly restrict the functionality available to Tcl |
---|
| 612 | programs executing within them. |
---|
| 613 | Allowing the untrusted Tcl program to have direct access to this |
---|
| 614 | functionality is unsafe, because it can be used for a variety of |
---|
| 615 | attacks on the environment. |
---|
| 616 | However, there are times when there is a legitimate need to use the |
---|
| 617 | dangerous functionality in the context of the safe interpreter. For |
---|
| 618 | example, sometimes a program must be \fBsource\fRd into the interpreter. |
---|
| 619 | Another example is Tk, where windows are bound to the hierarchy of windows |
---|
| 620 | for a specific interpreter; some potentially dangerous functions, e.g. |
---|
| 621 | window management, must be performed on these windows within the |
---|
| 622 | interpreter context. |
---|
| 623 | .PP |
---|
| 624 | The \fBinterp\fR command provides a solution to this problem in the form of |
---|
| 625 | \fIhidden commands\fR. Instead of removing the dangerous commands entirely |
---|
| 626 | from a safe interpreter, these commands are hidden so they become |
---|
| 627 | unavailable to Tcl scripts executing in the interpreter. However, such |
---|
| 628 | hidden commands can be invoked by any trusted ancestor of the safe |
---|
| 629 | interpreter, in the context of the safe interpreter, using \fBinterp |
---|
| 630 | invoke\fR. Hidden commands and exposed commands reside in separate name |
---|
| 631 | spaces. It is possible to define a hidden command and an exposed command by |
---|
| 632 | the same name within one interpreter. |
---|
| 633 | .PP |
---|
| 634 | Hidden commands in a slave interpreter can be invoked in the body of |
---|
| 635 | procedures called in the master during alias invocation. For example, an |
---|
| 636 | alias for \fBsource\fR could be created in a slave interpreter. When it is |
---|
| 637 | invoked in the slave interpreter, a procedure is called in the master |
---|
| 638 | interpreter to check that the operation is allowable (e.g. it asks to |
---|
| 639 | source a file that the slave interpreter is allowed to access). The |
---|
| 640 | procedure then it invokes the hidden \fBsource\fR command in the slave |
---|
| 641 | interpreter to actually source in the contents of the file. Note that two |
---|
| 642 | commands named \fBsource\fR exist in the slave interpreter: the alias, and |
---|
| 643 | the hidden command. |
---|
| 644 | .PP |
---|
| 645 | Because a master interpreter may invoke a hidden command as part of |
---|
| 646 | handling an alias invocation, great care must be taken to avoid evaluating |
---|
| 647 | any arguments passed in through the alias invocation. |
---|
| 648 | Otherwise, malicious slave interpreters could cause a trusted master |
---|
| 649 | interpreter to execute dangerous commands on their behalf. See the section |
---|
| 650 | on \fBALIAS INVOCATION\fR for a more complete discussion of this topic. |
---|
| 651 | To help avoid this problem, no substitutions or evaluations are |
---|
| 652 | applied to arguments of \fBinterp invokehidden\fR. |
---|
| 653 | .PP |
---|
| 654 | Safe interpreters are not allowed to invoke hidden commands in themselves |
---|
| 655 | or in their descendants. This prevents safe slaves from gaining access to |
---|
| 656 | hidden functionality in themselves or their descendants. |
---|
| 657 | .PP |
---|
| 658 | The set of hidden commands in an interpreter can be manipulated by a trusted |
---|
| 659 | interpreter using \fBinterp expose\fR and \fBinterp hide\fR. The \fBinterp |
---|
| 660 | expose\fR command moves a hidden command to the |
---|
| 661 | set of exposed commands in the interpreter identified by \fIpath\fR, |
---|
| 662 | potentially renaming the command in the process. If an exposed command by |
---|
| 663 | the targeted name already exists, the operation fails. Similarly, |
---|
| 664 | \fBinterp hide\fR moves an exposed command to the set of hidden commands in |
---|
| 665 | that interpreter. Safe interpreters are not allowed to move commands |
---|
| 666 | between the set of hidden and exposed commands, in either themselves or |
---|
| 667 | their descendants. |
---|
| 668 | .PP |
---|
| 669 | Currently, the names of hidden commands cannot contain namespace |
---|
| 670 | qualifiers, and you must first rename a command in a namespace to the |
---|
| 671 | global namespace before you can hide it. |
---|
| 672 | Commands to be hidden by \fBinterp hide\fR are looked up in the global |
---|
| 673 | namespace even if the current namespace is not the global one. This |
---|
| 674 | prevents slaves from fooling a master interpreter into hiding the wrong |
---|
| 675 | command, by making the current namespace be different from the global one. |
---|
| 676 | .SH "RESOURCE LIMITS" |
---|
| 677 | .VS 8.5 |
---|
| 678 | .PP |
---|
| 679 | Every interpreter has two kinds of resource limits that may be imposed by any |
---|
| 680 | master interpreter upon its slaves. Command limits (of type \fBcommand\fR) |
---|
| 681 | restrict the total number of Tcl commands that may be executed by an |
---|
| 682 | interpreter (as can be inspected via the \fBinfo cmdcount\fR command), and |
---|
| 683 | time limits (of type \fBtime\fR) place a limit by which execution within the |
---|
| 684 | interpreter must complete. Note that time limits are expressed as |
---|
| 685 | \fIabsolute\fR times (as in \fBclock seconds\fR) and not relative times (as in |
---|
| 686 | \fBafter\fR) because they may be modified after creation. |
---|
| 687 | .PP |
---|
| 688 | When a limit is exceeded for an interpreter, first any handler callbacks |
---|
| 689 | defined by master interpreters are called. If those callbacks increase or |
---|
| 690 | remove the limit, execution within the (previously) limited interpreter |
---|
| 691 | continues. If the limit is still in force, an error is generated at that point |
---|
| 692 | and normal processing of errors within the interpreter (by the \fBcatch\fR |
---|
| 693 | command) is disabled, so the error propagates outwards (building a stack-trace |
---|
| 694 | as it goes) to the point where the limited interpreter was invoked (e.g. by |
---|
| 695 | \fBinterp eval\fR) where it becomes the responsibility of the calling code to |
---|
| 696 | catch and handle. |
---|
| 697 | .SS "LIMIT OPTIONS" |
---|
| 698 | .PP |
---|
| 699 | Every limit has a number of options associated with it, some of which are |
---|
| 700 | common across all kinds of limits, and others of which are particular to the |
---|
| 701 | kind of limit. |
---|
| 702 | .VE 8.5 |
---|
| 703 | .TP |
---|
| 704 | \fB\-command\fR |
---|
| 705 | .VS 8.5 |
---|
| 706 | This option (common for all limit types) specifies (if non-empty) a Tcl script |
---|
| 707 | to be executed in the global namespace of the interpreter reading and writing |
---|
| 708 | the option when the particular limit in the limited interpreter is exceeded. |
---|
| 709 | The callback may modify the limit on the interpreter if it wishes the limited |
---|
| 710 | interpreter to continue executing. If the callback generates an error, it is |
---|
| 711 | reported through the background error mechanism (see \fBBACKGROUND ERROR |
---|
| 712 | HANDLING\fR). Note that the callbacks defined by one interpreter are |
---|
| 713 | completely isolated from the callbacks defined by another, and that the order |
---|
| 714 | in which those callbacks are called is undefined. |
---|
| 715 | .VE 8.5 |
---|
| 716 | .TP |
---|
| 717 | \fB\-granularity\fR |
---|
| 718 | .VS 8.5 |
---|
| 719 | This option (common for all limit types) specifies how frequently (out of the |
---|
| 720 | points when the Tcl interpreter is in a consistent state where limit checking |
---|
| 721 | is possible) that the limit is actually checked. This allows the tuning of how |
---|
| 722 | frequently a limit is checked, and hence how often the limit-checking overhead |
---|
| 723 | (which may be substantial in the case of time limits) is incurred. |
---|
| 724 | .VE 8.5 |
---|
| 725 | .TP |
---|
| 726 | \fB\-milliseconds\fR |
---|
| 727 | .VS 8.5 |
---|
| 728 | This option specifies the number of milliseconds after the moment defined in |
---|
| 729 | the \fB\-seconds\fR option that the time limit will fire. It should only ever |
---|
| 730 | be specified in conjunction with the \fB\-seconds\fR option (whether it was |
---|
| 731 | set previously or is being set this invocation.) |
---|
| 732 | .VE 8.5 |
---|
| 733 | .TP |
---|
| 734 | \fB\-seconds\fR |
---|
| 735 | .VS 8.5 |
---|
| 736 | This option specifies the number of seconds after the epoch (see \fBclock |
---|
| 737 | seconds\fR) that the time limit for the interpreter will be triggered. The |
---|
| 738 | limit will be triggered at the start of the second unless specified at a |
---|
| 739 | sub-second level using the \fB\-milliseconds\fR option. This option may be the |
---|
| 740 | empty string, which indicates that a time limit is not set for the |
---|
| 741 | interpreter. |
---|
| 742 | .VE 8.5 |
---|
| 743 | .TP |
---|
| 744 | \fB\-value\fR |
---|
| 745 | .VS 8.5 |
---|
| 746 | This option specifies the number of commands that the interpreter may execute |
---|
| 747 | before triggering the command limit. This option may be the empty string, |
---|
| 748 | which indicates that a command limit is not set for the interpreter. |
---|
| 749 | .PP |
---|
| 750 | Where an interpreter with a resource limit set on it creates a slave |
---|
| 751 | interpreter, that slave interpreter will have resource limits imposed on it |
---|
| 752 | that are at least as restrictive as the limits on the creating master |
---|
| 753 | interpreter. If the master interpreter of the limited master wishes to relax |
---|
| 754 | these conditions, it should hide the \fBinterp\fR command in the child and |
---|
| 755 | then use aliases and the \fBinterp invokehidden\fR subcommand to provide such |
---|
| 756 | access as it chooses to the \fBinterp\fR command to the limited master as |
---|
| 757 | necessary. |
---|
| 758 | .SH "BACKGROUND ERROR HANDLING" |
---|
| 759 | .PP |
---|
| 760 | When an error happens in a situation where it cannot be reported directly up |
---|
| 761 | the stack (e.g. when processing events in an \fBupdate\fR or \fBvwait\fR call) |
---|
| 762 | the error is instead reported through the background error handling mechanism. |
---|
| 763 | Every interpreter has a background error handler registered; the default error |
---|
| 764 | handler arranges for the \fBbgerror\fR command in the interpreter's global |
---|
| 765 | namespace to be called, but other error handlers may be installed and process |
---|
| 766 | background errors in substantially different ways. |
---|
| 767 | .PP |
---|
| 768 | A background error handler consists of a non-empty list of words to which will |
---|
| 769 | be appended two further words at invocation time. The first word will be the |
---|
| 770 | error message string, and the second will a dictionary of return options (this |
---|
| 771 | is also the sort of information that can be obtained by trapping a normal |
---|
| 772 | error using \fBcatch\fR of course.) The resulting list will then be executed |
---|
| 773 | in the interpreter's global namespace without further substitutions being |
---|
| 774 | performed. |
---|
| 775 | .VE 8.5 |
---|
| 776 | .SH CREDITS |
---|
| 777 | The safe interpreter mechanism is based on the Safe-Tcl prototype implemented |
---|
| 778 | by Nathaniel Borenstein and Marshall Rose. |
---|
| 779 | .SH EXAMPLES |
---|
| 780 | Creating and using an alias for a command in the current interpreter: |
---|
| 781 | .CS |
---|
| 782 | \fBinterp alias\fR {} getIndex {} lsearch {alpha beta gamma delta} |
---|
| 783 | set idx [getIndex delta] |
---|
| 784 | .CE |
---|
| 785 | .PP |
---|
| 786 | Executing an arbitrary command in a safe interpreter where every |
---|
| 787 | invocation of \fBlappend\fR is logged: |
---|
| 788 | .CS |
---|
| 789 | set i [\fBinterp create\fR -safe] |
---|
| 790 | \fBinterp hide\fR $i lappend |
---|
| 791 | \fBinterp alias\fR $i lappend {} loggedLappend $i |
---|
| 792 | proc loggedLappend {i args} { |
---|
| 793 | puts "logged invocation of lappend $args" |
---|
| 794 | \fBinterp invokehidden\fR $i lappend {*}$args |
---|
| 795 | } |
---|
| 796 | \fBinterp eval\fR $i $someUntrustedScript |
---|
| 797 | .CE |
---|
| 798 | .PP |
---|
| 799 | .VS 8.5 |
---|
| 800 | Setting a resource limit on an interpreter so that an infinite loop |
---|
| 801 | terminates. |
---|
| 802 | .CS |
---|
| 803 | set i [\fBinterp create\fR] |
---|
| 804 | \fBinterp limit\fR $i command -value 1000 |
---|
| 805 | \fBinterp eval\fR $i { |
---|
| 806 | set x 0 |
---|
| 807 | while {1} { |
---|
| 808 | puts "Counting up... [incr x]" |
---|
| 809 | } |
---|
| 810 | } |
---|
| 811 | .CE |
---|
| 812 | .VE 8.5 |
---|
| 813 | .SH "SEE ALSO" |
---|
| 814 | bgerror(n), load(n), safe(n), Tcl_CreateSlave(3) |
---|
| 815 | .SH KEYWORDS |
---|
| 816 | alias, master interpreter, safe interpreter, slave interpreter |
---|