Import Tcl-core 8.6.6 (as of svn r86089)
This commit is contained in:
Zachary Ware
910
doc/interp.n
Normal file
910
doc/interp.n
Normal file
@@ -0,0 +1,910 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
|
||||
'\" Copyright (c) 2004 Donal K. Fellows
|
||||
'\" Copyright (c) 2006-2008 Joe Mistachkin.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
.TH interp n 8.6 Tcl "Tcl Built-In Commands"
|
||||
.so man.macros
|
||||
.BS
|
||||
'\" Note: do not modify the .SH NAME line immediately below!
|
||||
.SH NAME
|
||||
interp \- Create and manipulate Tcl interpreters
|
||||
.SH SYNOPSIS
|
||||
\fBinterp \fIsubcommand \fR?\fIarg arg ...\fR?
|
||||
.BE
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This command makes it possible to create one or more new Tcl
|
||||
interpreters that co-exist with the creating interpreter in the
|
||||
same application. The creating interpreter is called the \fImaster\fR
|
||||
and the new interpreter is called a \fIslave\fR.
|
||||
A master can create any number of slaves, and each slave can
|
||||
itself create additional slaves for which it is master, resulting
|
||||
in a hierarchy of interpreters.
|
||||
.PP
|
||||
Each interpreter is independent from the others: it has its own name
|
||||
space for commands, procedures, and global variables.
|
||||
A master interpreter may create connections between its slaves and
|
||||
itself using a mechanism called an \fIalias\fR. An \fIalias\fR is
|
||||
a command in a slave interpreter which, when invoked, causes a
|
||||
command to be invoked in its master interpreter or in another slave
|
||||
interpreter. The only other connections between interpreters are
|
||||
through environment variables (the \fBenv\fR variable), which are
|
||||
normally shared among all interpreters in the application,
|
||||
and by resource limit exceeded callbacks. Note that the
|
||||
name space for files (such as the names returned by the \fBopen\fR command)
|
||||
is no longer shared between interpreters. Explicit commands are provided to
|
||||
share files and to transfer references to open files from one interpreter
|
||||
to another.
|
||||
.PP
|
||||
The \fBinterp\fR command also provides support for \fIsafe\fR
|
||||
interpreters. A safe interpreter is a slave whose functions have
|
||||
been greatly restricted, so that it is safe to execute untrusted
|
||||
scripts without fear of them damaging other interpreters or the
|
||||
application's environment. For example, all IO channel creation
|
||||
commands and subprocess creation commands are made inaccessible to safe
|
||||
interpreters.
|
||||
See \fBSAFE INTERPRETERS\fR below for more information on
|
||||
what features are present in a safe interpreter.
|
||||
The dangerous functionality is not removed from the safe interpreter;
|
||||
instead, it is \fIhidden\fR, so that only trusted interpreters can obtain
|
||||
access to it. For a detailed explanation of hidden commands, see
|
||||
\fBHIDDEN COMMANDS\fR, below.
|
||||
The alias mechanism can be used for protected communication (analogous to a
|
||||
kernel call) between a slave interpreter and its master.
|
||||
See \fBALIAS INVOCATION\fR, below, for more details
|
||||
on how the alias mechanism works.
|
||||
.PP
|
||||
A qualified interpreter name is a proper Tcl lists containing a subset of its
|
||||
ancestors in the interpreter hierarchy, terminated by the string naming the
|
||||
interpreter in its immediate master. Interpreter names are relative to the
|
||||
interpreter in which they are used. For example, if
|
||||
.QW \fBa\fR
|
||||
is a slave of the current interpreter and it has a slave
|
||||
.QW \fBa1\fR ,
|
||||
which in turn has a slave
|
||||
.QW \fBa11\fR ,
|
||||
the qualified name of
|
||||
.QW \fBa11\fR
|
||||
in
|
||||
.QW \fBa\fR
|
||||
is the list
|
||||
.QW "\fBa1 a11\fR" .
|
||||
.PP
|
||||
The \fBinterp\fR command, described below, accepts qualified interpreter
|
||||
names as arguments; the interpreter in which the command is being evaluated
|
||||
can always be referred to as \fB{}\fR (the empty list or string). Note that
|
||||
it is impossible to refer to a master (ancestor) interpreter by name in a
|
||||
slave interpreter except through aliases. Also, there is no global name by
|
||||
which one can refer to the first interpreter created in an application.
|
||||
Both restrictions are motivated by safety concerns.
|
||||
.SH "THE INTERP COMMAND"
|
||||
.PP
|
||||
The \fBinterp\fR command is used to create, delete, and manipulate
|
||||
slave interpreters, and to share or transfer
|
||||
channels between interpreters. It can have any of several forms, depending
|
||||
on the \fIsubcommand\fR argument:
|
||||
.TP
|
||||
\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR
|
||||
.
|
||||
Returns a Tcl list whose elements are the \fItargetCmd\fR and
|
||||
\fIarg\fRs associated with the alias represented by \fIsrcToken\fR
|
||||
(this is the value returned when the alias was
|
||||
created; it is possible that the name of the source command in the
|
||||
slave is different from \fIsrcToken\fR).
|
||||
.TP
|
||||
\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR \fB{}\fR
|
||||
.
|
||||
Deletes the alias for \fIsrcToken\fR in the slave interpreter identified by
|
||||
\fIsrcPath\fR.
|
||||
\fIsrcToken\fR refers to the value returned when the alias
|
||||
was created; if the source command has been renamed, the renamed
|
||||
command will be deleted.
|
||||
.TP
|
||||
\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR \fItargetPath\fR \fItargetCmd \fR?\fIarg arg ...\fR?
|
||||
.
|
||||
This command creates an alias between one slave and another (see the
|
||||
\fBalias\fR slave command below for creating aliases between a slave
|
||||
and its master). In this command, either of the slave interpreters
|
||||
may be anywhere in the hierarchy of interpreters under the interpreter
|
||||
invoking the command.
|
||||
\fISrcPath\fR and \fIsrcCmd\fR identify the source of the alias.
|
||||
\fISrcPath\fR is a Tcl list whose elements select a particular
|
||||
interpreter. For example,
|
||||
.QW "\fBa b\fR"
|
||||
identifies an interpreter
|
||||
.QW \fBb\fR ,
|
||||
which is a slave of interpreter
|
||||
.QW \fBa\fR ,
|
||||
which is a slave of the invoking interpreter. An empty list specifies
|
||||
the interpreter invoking the command. \fIsrcCmd\fR gives the name of
|
||||
a new command, which will be created in the source interpreter.
|
||||
\fITargetPath\fR and \fItargetCmd\fR specify a target interpreter
|
||||
and command, and the \fIarg\fR arguments, if any, specify additional
|
||||
arguments to \fItargetCmd\fR which are prepended to any arguments specified
|
||||
in the invocation of \fIsrcCmd\fR.
|
||||
\fITargetCmd\fR may be undefined at the time of this call, or it may
|
||||
already exist; it is not created by this command.
|
||||
The alias arranges for the given target command to be invoked
|
||||
in the target interpreter whenever the given source command is
|
||||
invoked in the source interpreter. See \fBALIAS INVOCATION\fR below for
|
||||
more details.
|
||||
The command returns a token that uniquely identifies the command created
|
||||
\fIsrcCmd\fR, even if the command is renamed afterwards. The token may but
|
||||
does not have to be equal to \fIsrcCmd\fR.
|
||||
.TP
|
||||
\fBinterp\fR \fBaliases \fR?\fIpath\fR?
|
||||
.
|
||||
This command returns a Tcl list of the tokens of all the source commands for
|
||||
aliases defined in the interpreter identified by \fIpath\fR. The tokens
|
||||
correspond to the values returned when
|
||||
the aliases were created (which may not be the same
|
||||
as the current names of the commands).
|
||||
.TP
|
||||
\fBinterp bgerror \fIpath\fR ?\fIcmdPrefix\fR?
|
||||
.
|
||||
This command either gets or sets the current background exception handler
|
||||
for the interpreter identified by \fIpath\fR. If \fIcmdPrefix\fR is
|
||||
absent, the current background exception handler is returned, and if it is
|
||||
present, it is a list of words (of minimum length one) that describes
|
||||
what to set the interpreter's background exception handler to. See the
|
||||
\fBBACKGROUND EXCEPTION HANDLING\fR section for more details.
|
||||
.TP
|
||||
\fBinterp\fR \fBcancel \fR?\fB\-unwind\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? ?\fIresult\fR?
|
||||
.VS 8.6
|
||||
Cancels the script being evaluated in the interpreter identified by
|
||||
\fIpath\fR. Without the \fB\-unwind\fR switch the evaluation stack for
|
||||
the interpreter is unwound until an enclosing catch command is found or
|
||||
there are no further invocations of the interpreter left on the call
|
||||
stack. With the \fB\-unwind\fR switch the evaluation stack for the
|
||||
interpreter is unwound without regard to any intervening catch command
|
||||
until there are no further invocations of the interpreter left on the
|
||||
call stack. The \fB\-\|\-\fR switch can be used to mark the end of
|
||||
switches; it may be needed if \fIpath\fR is an unusual value such
|
||||
as \fB\-safe\fR. If \fIresult\fR is present, it will be used as the
|
||||
error message string; otherwise, a default error message string will be
|
||||
used.
|
||||
.VE 8.6
|
||||
.TP
|
||||
\fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR?
|
||||
.
|
||||
Creates a slave interpreter identified by \fIpath\fR and a new command,
|
||||
called a \fIslave command\fR. The name of the slave command is the last
|
||||
component of \fIpath\fR. The new slave interpreter and the slave command
|
||||
are created in the interpreter identified by the path obtained by removing
|
||||
the last component from \fIpath\fR. For example, if \fIpath\fR is \fBa b
|
||||
c\fR then a new slave interpreter and slave command named \fBc\fR are
|
||||
created in the interpreter identified by the path \fBa b\fR.
|
||||
The slave command may be used to manipulate the new interpreter as
|
||||
described below. If \fIpath\fR is omitted, Tcl creates a unique name of the
|
||||
form \fBinterp\fIx\fR, where \fIx\fR is an integer, and uses it for the
|
||||
interpreter and the slave command. If the \fB\-safe\fR switch is specified
|
||||
(or if the master interpreter is a safe interpreter), the new slave
|
||||
interpreter will be created as a safe interpreter with limited
|
||||
functionality; otherwise the slave will include the full set of Tcl
|
||||
built-in commands and variables. The \fB\-\|\-\fR switch can be used to
|
||||
mark the end of switches; it may be needed if \fIpath\fR is an unusual
|
||||
value such as \fB\-safe\fR. The result of the command is the name of the
|
||||
new interpreter. The name of a slave interpreter must be unique among all
|
||||
the slaves for its master; an error occurs if a slave interpreter by the
|
||||
given name already exists in this master.
|
||||
The initial recursion limit of the slave interpreter is set to the
|
||||
current recursion limit of its parent interpreter.
|
||||
.TP
|
||||
\fBinterp\fR \fBdebug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR??
|
||||
.
|
||||
Controls whether frame-level stack information is captured in the
|
||||
slave interpreter identified by \fIpath\fR. If no arguments are
|
||||
given, option and current setting are returned. If \fB\-frame\fR
|
||||
is given, the debug setting is set to the given boolean if provided
|
||||
and the current setting is returned.
|
||||
This only effects the output of \fBinfo frame\fR, in that exact
|
||||
frame-level information for command invocation at the bytecode level
|
||||
is only captured with this setting on.
|
||||
.RS
|
||||
.PP
|
||||
For example, with code like
|
||||
.PP
|
||||
.CS
|
||||
\fBproc\fR mycontrol {... script} {
|
||||
...
|
||||
\fBuplevel\fR 1 $script
|
||||
...
|
||||
}
|
||||
|
||||
\fBproc\fR dosomething {...} {
|
||||
...
|
||||
mycontrol {
|
||||
somecode
|
||||
}
|
||||
}
|
||||
.CE
|
||||
.PP
|
||||
the standard setting will provide a relative line number for the
|
||||
command \fBsomecode\fR and the relevant frame will be of type
|
||||
\fBeval\fR. With frame-debug active on the other hand the tracking
|
||||
extends so far that the system will be able to determine the file and
|
||||
absolute line number of this command, and return a frame of type
|
||||
\fBsource\fR. This more exact information is paid for with slower
|
||||
execution of all commands.
|
||||
.PP
|
||||
Note that once it is on, this flag cannot be switched back off: such
|
||||
attempts are silently ignored. This is needed to maintain the
|
||||
consistency of the underlying interpreter's state.
|
||||
.RE
|
||||
.TP
|
||||
\fBinterp\fR \fBdelete \fR?\fIpath ...?\fR
|
||||
.
|
||||
Deletes zero or more interpreters given by the optional \fIpath\fR
|
||||
arguments, and for each interpreter, it also deletes its slaves. The
|
||||
command also deletes the slave command for each interpreter deleted.
|
||||
For each \fIpath\fR argument, if no interpreter by that name
|
||||
exists, the command raises an error.
|
||||
.TP
|
||||
\fBinterp\fR \fBeval\fR \fIpath arg \fR?\fIarg ...\fR?
|
||||
.
|
||||
This command concatenates all of the \fIarg\fR arguments in the same
|
||||
fashion as the \fBconcat\fR command, then evaluates the resulting string as
|
||||
a Tcl script in the slave interpreter identified by \fIpath\fR. The result
|
||||
of this evaluation (including all \fBreturn\fR options,
|
||||
such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an
|
||||
error occurs) is returned to the invoking interpreter.
|
||||
Note that the script will be executed in the current context stack frame of the
|
||||
\fIpath\fR interpreter; this is so that the implementations (in a master
|
||||
interpreter) of aliases in a slave interpreter can execute scripts in
|
||||
the slave that find out information about the slave's current state
|
||||
and stack frame.
|
||||
.TP
|
||||
\fBinterp exists \fIpath\fR
|
||||
.
|
||||
Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR
|
||||
exists in this master, \fB0\fR otherwise. If \fIpath\fR is omitted, the
|
||||
invoking interpreter is used.
|
||||
.TP
|
||||
\fBinterp expose \fIpath\fR \fIhiddenName\fR ?\fIexposedCmdName\fR?
|
||||
.
|
||||
Makes the hidden command \fIhiddenName\fR exposed, eventually bringing
|
||||
it back under a new \fIexposedCmdName\fR name (this name is currently
|
||||
accepted only if it is a valid global name space name without any ::),
|
||||
in the interpreter
|
||||
denoted by \fIpath\fR.
|
||||
If an exposed command with the targeted name already exists, this command
|
||||
fails.
|
||||
Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
|
||||
.TP
|
||||
\fBinterp\fR \fBhide\fR \fIpath\fR \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
|
||||
.
|
||||
Makes the exposed command \fIexposedCmdName\fR hidden, renaming
|
||||
it to the hidden command \fIhiddenCmdName\fR, or keeping the same name if
|
||||
\fIhiddenCmdName\fR is not given, in the interpreter denoted
|
||||
by \fIpath\fR.
|
||||
If a hidden command with the targeted name already exists, this command
|
||||
fails.
|
||||
Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can
|
||||
not contain namespace qualifiers, or an error is raised.
|
||||
Commands to be hidden by \fBinterp hide\fR are looked up in the global
|
||||
namespace even if the current namespace is not the global one. This
|
||||
prevents slaves from fooling a master interpreter into hiding the wrong
|
||||
command, by making the current namespace be different from the global one.
|
||||
Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
|
||||
.TP
|
||||
\fBinterp\fR \fBhidden\fR \fIpath\fR
|
||||
.
|
||||
Returns a list of the names of all hidden commands in the interpreter
|
||||
identified by \fIpath\fR.
|
||||
.TP
|
||||
\fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fI\-option ...\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR?
|
||||
.
|
||||
Invokes the hidden command \fIhiddenCmdName\fR with the arguments supplied
|
||||
in the interpreter denoted by \fIpath\fR. No substitutions or evaluation
|
||||
are applied to the arguments. Three \fI\-option\fRs are supported, all
|
||||
of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single
|
||||
argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR.
|
||||
If the \fB\-namespace\fR flag is present, the hidden command is invoked in
|
||||
the namespace called \fInsName\fR in the target interpreter.
|
||||
If the \fB\-global\fR flag is present, the hidden command is invoked at the
|
||||
global level in the target interpreter; otherwise it is invoked at the
|
||||
current call frame and can access local variables in that and outer call
|
||||
frames.
|
||||
The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a
|
||||
.QW \-
|
||||
character, and is otherwise unnecessary.
|
||||
If both the \fB\-namespace\fR and \fB\-global\fR flags are present, the
|
||||
\fB\-namespace\fR flag is ignored.
|
||||
Note that the hidden command will be executed (by default) in the
|
||||
current context stack frame of the \fIpath\fR interpreter.
|
||||
Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
|
||||
.TP
|
||||
\fBinterp issafe\fR ?\fIpath\fR?
|
||||
.
|
||||
Returns \fB1\fR if the interpreter identified by the specified \fIpath\fR
|
||||
is safe, \fB0\fR otherwise.
|
||||
.TP
|
||||
\fBinterp\fR \fBlimit\fR \fIpath\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR?
|
||||
.
|
||||
Sets up, manipulates and queries the configuration of the resource
|
||||
limit \fIlimitType\fR for the interpreter denoted by \fIpath\fR. If
|
||||
no \fI\-option\fR is specified, return the current configuration of the
|
||||
limit. If \fI\-option\fR is the sole argument, return the value of that
|
||||
option. Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs
|
||||
must supplied. See \fBRESOURCE LIMITS\fR below for a more detailed
|
||||
explanation of what limits and options are supported.
|
||||
.TP
|
||||
\fBinterp marktrusted\fR \fIpath\fR
|
||||
.
|
||||
Marks the interpreter identified by \fIpath\fR as trusted. Does
|
||||
not expose the hidden commands. This command can only be invoked from a
|
||||
trusted interpreter.
|
||||
The command has no effect if the interpreter identified by \fIpath\fR is
|
||||
already trusted.
|
||||
.TP
|
||||
\fBinterp\fR \fBrecursionlimit\fR \fIpath\fR ?\fInewlimit\fR?
|
||||
.
|
||||
Returns the maximum allowable nesting depth for the interpreter
|
||||
specified by \fIpath\fR. If \fInewlimit\fR is specified,
|
||||
the interpreter recursion limit will be set so that nesting
|
||||
of more than \fInewlimit\fR calls to \fBTcl_Eval\fR
|
||||
and related procedures in that interpreter will return an error.
|
||||
The \fInewlimit\fR value is also returned.
|
||||
The \fInewlimit\fR value must be a positive integer between 1 and the
|
||||
maximum value of a non-long integer on the platform.
|
||||
.RS
|
||||
.PP
|
||||
The command sets the maximum size of the Tcl call stack only. It cannot
|
||||
by itself prevent stack overflows on the C stack being used by the
|
||||
application. If your machine has a limit on the size of the C stack, you
|
||||
may get stack overflows before reaching the limit set by the command. If
|
||||
this happens, see if there is a mechanism in your system for increasing
|
||||
the maximum size of the C stack.
|
||||
.RE
|
||||
.TP
|
||||
\fBinterp\fR \fBshare\fR \fIsrcPath channelId destPath\fR
|
||||
.
|
||||
Causes the IO channel identified by \fIchannelId\fR to become shared
|
||||
between the interpreter identified by \fIsrcPath\fR and the interpreter
|
||||
identified by \fIdestPath\fR. Both interpreters have the same permissions
|
||||
on the IO channel.
|
||||
Both interpreters must close it to close the underlying IO channel; IO
|
||||
channels accessible in an interpreter are automatically closed when an
|
||||
interpreter is destroyed.
|
||||
.TP
|
||||
\fBinterp\fR \fBslaves\fR ?\fIpath\fR?
|
||||
.
|
||||
Returns a Tcl list of the names of all the slave interpreters associated
|
||||
with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted,
|
||||
the invoking interpreter is used.
|
||||
.TP
|
||||
\fBinterp\fR \fBtarget\fR \fIpath alias\fR
|
||||
.
|
||||
Returns a Tcl list describing the target interpreter for an alias. The
|
||||
alias is specified with an interpreter path and source command name, just
|
||||
as in \fBinterp alias\fR above. The name of the target interpreter is
|
||||
returned as an interpreter path, relative to the invoking interpreter.
|
||||
If the target interpreter for the alias is the invoking interpreter then an
|
||||
empty list is returned. If the target interpreter for the alias is not the
|
||||
invoking interpreter or one of its descendants then an error is generated.
|
||||
The target command does not have to be defined at the time of this invocation.
|
||||
.TP
|
||||
\fBinterp\fR \fBtransfer\fR \fIsrcPath channelId destPath\fR
|
||||
.
|
||||
Causes the IO channel identified by \fIchannelId\fR to become available in
|
||||
the interpreter identified by \fIdestPath\fR and unavailable in the
|
||||
interpreter identified by \fIsrcPath\fR.
|
||||
.SH "SLAVE COMMAND"
|
||||
.PP
|
||||
For each slave interpreter created with the \fBinterp\fR command, a
|
||||
new Tcl command is created in the master interpreter with the same
|
||||
name as the new interpreter. This command may be used to invoke
|
||||
various operations on the interpreter. It has the following
|
||||
general form:
|
||||
.PP
|
||||
.CS
|
||||
\fIslave command \fR?\fIarg arg ...\fR?
|
||||
.CE
|
||||
.PP
|
||||
\fISlave\fR is the name of the interpreter, and \fIcommand\fR
|
||||
and the \fIarg\fRs determine the exact behavior of the command.
|
||||
The valid forms of this command are:
|
||||
.TP
|
||||
\fIslave \fBaliases\fR
|
||||
.
|
||||
Returns a Tcl list whose elements are the tokens of all the
|
||||
aliases in \fIslave\fR. The tokens correspond to the values returned when
|
||||
the aliases were created (which may not be the same
|
||||
as the current names of the commands).
|
||||
.TP
|
||||
\fIslave \fBalias \fIsrcToken\fR
|
||||
.
|
||||
Returns a Tcl list whose elements are the \fItargetCmd\fR and
|
||||
\fIarg\fRs associated with the alias represented by \fIsrcToken\fR
|
||||
(this is the value returned when the alias was
|
||||
created; it is possible that the actual source command in the
|
||||
slave is different from \fIsrcToken\fR).
|
||||
.TP
|
||||
\fIslave \fBalias \fIsrcToken \fB{}\fR
|
||||
.
|
||||
Deletes the alias for \fIsrcToken\fR in the slave interpreter.
|
||||
\fIsrcToken\fR refers to the value returned when the alias
|
||||
was created; if the source command has been renamed, the renamed
|
||||
command will be deleted.
|
||||
.TP
|
||||
\fIslave \fBalias \fIsrcCmd targetCmd \fR?\fIarg ..\fR?
|
||||
.
|
||||
Creates an alias such that whenever \fIsrcCmd\fR is invoked
|
||||
in \fIslave\fR, \fItargetCmd\fR is invoked in the master.
|
||||
The \fIarg\fR arguments will be passed to \fItargetCmd\fR as additional
|
||||
arguments, prepended before any arguments passed in the invocation of
|
||||
\fIsrcCmd\fR.
|
||||
See \fBALIAS INVOCATION\fR below for details.
|
||||
The command returns a token that uniquely identifies the command created
|
||||
\fIsrcCmd\fR, even if the command is renamed afterwards. The token may but
|
||||
does not have to be equal to \fIsrcCmd\fR.
|
||||
.TP
|
||||
\fIslave \fBbgerror\fR ?\fIcmdPrefix\fR?
|
||||
.
|
||||
This command either gets or sets the current background exception handler
|
||||
for the \fIslave\fR interpreter. If \fIcmdPrefix\fR is
|
||||
absent, the current background exception handler is returned, and if it is
|
||||
present, it is a list of words (of minimum length one) that describes
|
||||
what to set the interpreter's background exception handler to. See the
|
||||
\fBBACKGROUND EXCEPTION HANDLING\fR section for more details.
|
||||
.TP
|
||||
\fIslave \fBeval \fIarg \fR?\fIarg ..\fR?
|
||||
.
|
||||
This command concatenates all of the \fIarg\fR arguments in
|
||||
the same fashion as the \fBconcat\fR command, then evaluates
|
||||
the resulting string as a Tcl script in \fIslave\fR.
|
||||
The result of this evaluation (including all \fBreturn\fR options,
|
||||
such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an
|
||||
error occurs) is returned to the invoking interpreter.
|
||||
Note that the script will be executed in the current context stack frame
|
||||
of \fIslave\fR; this is so that the implementations (in a master
|
||||
interpreter) of aliases in a slave interpreter can execute scripts in
|
||||
the slave that find out information about the slave's current state
|
||||
and stack frame.
|
||||
.TP
|
||||
\fIslave \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR?
|
||||
.
|
||||
This command exposes the hidden command \fIhiddenName\fR, eventually bringing
|
||||
it back under a new \fIexposedCmdName\fR name (this name is currently
|
||||
accepted only if it is a valid global name space name without any ::),
|
||||
in \fIslave\fR.
|
||||
If an exposed command with the targeted name already exists, this command
|
||||
fails.
|
||||
For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
|
||||
.TP
|
||||
\fIslave \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
|
||||
.
|
||||
This command hides the exposed command \fIexposedCmdName\fR, renaming it to
|
||||
the hidden command \fIhiddenCmdName\fR, or keeping the same name if the
|
||||
argument is not given, in the \fIslave\fR interpreter.
|
||||
If a hidden command with the targeted name already exists, this command
|
||||
fails.
|
||||
Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can
|
||||
not contain namespace qualifiers, or an error is raised.
|
||||
Commands to be hidden are looked up in the global
|
||||
namespace even if the current namespace is not the global one. This
|
||||
prevents slaves from fooling a master interpreter into hiding the wrong
|
||||
command, by making the current namespace be different from the global one.
|
||||
For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
|
||||
.TP
|
||||
\fIslave \fBhidden\fR
|
||||
.
|
||||
Returns a list of the names of all hidden commands in \fIslave\fR.
|
||||
.TP
|
||||
\fIslave \fBinvokehidden\fR ?\fI\-option ...\fR? \fIhiddenName \fR?\fIarg ..\fR?
|
||||
.
|
||||
This command invokes the hidden command \fIhiddenName\fR with the
|
||||
supplied arguments, in \fIslave\fR. No substitutions or evaluations are
|
||||
applied to the arguments. Three \fI\-option\fRs are supported, all
|
||||
of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single
|
||||
argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR.
|
||||
If the \fB\-namespace\fR flag is given, the hidden command is invoked in
|
||||
the specified namespace in the slave.
|
||||
If the \fB\-global\fR flag is given, the command is invoked at the global
|
||||
level in the slave; otherwise it is invoked at the current call frame and
|
||||
can access local variables in that or outer call frames.
|
||||
The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a
|
||||
.QW \-
|
||||
character, and is otherwise unnecessary.
|
||||
If both the \fB\-namespace\fR and \fB\-global\fR flags are given, the
|
||||
\fB\-namespace\fR flag is ignored.
|
||||
Note that the hidden command will be executed (by default) in the
|
||||
current context stack frame of \fIslave\fR.
|
||||
For more details on hidden commands,
|
||||
see \fBHIDDEN COMMANDS\fR, below.
|
||||
.TP
|
||||
\fIslave \fBissafe\fR
|
||||
.
|
||||
Returns \fB1\fR if the slave interpreter is safe, \fB0\fR otherwise.
|
||||
.TP
|
||||
\fIslave \fBlimit\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR?
|
||||
.
|
||||
Sets up, manipulates and queries the configuration of the resource
|
||||
limit \fIlimitType\fR for the slave interpreter. If no \fI\-option\fR
|
||||
is specified, return the current configuration of the limit. If
|
||||
\fI\-option\fR is the sole argument, return the value of that option.
|
||||
Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must
|
||||
supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of
|
||||
what limits and options are supported.
|
||||
.TP
|
||||
\fIslave \fBmarktrusted\fR
|
||||
.
|
||||
Marks the slave interpreter as trusted. Can only be invoked by a
|
||||
trusted interpreter. This command does not expose any hidden
|
||||
commands in the slave interpreter. The command has no effect if the slave
|
||||
is already trusted.
|
||||
.TP
|
||||
\fIslave\fR \fBrecursionlimit\fR ?\fInewlimit\fR?
|
||||
.
|
||||
Returns the maximum allowable nesting depth for the \fIslave\fR interpreter.
|
||||
If \fInewlimit\fR is specified, the recursion limit in \fIslave\fR will be
|
||||
set so that nesting of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR
|
||||
and related procedures in \fIslave\fR will return an error.
|
||||
The \fInewlimit\fR value is also returned.
|
||||
The \fInewlimit\fR value must be a positive integer between 1 and the
|
||||
maximum value of a non-long integer on the platform.
|
||||
.RS
|
||||
.PP
|
||||
The command sets the maximum size of the Tcl call stack only. It cannot
|
||||
by itself prevent stack overflows on the C stack being used by the
|
||||
application. If your machine has a limit on the size of the C stack, you
|
||||
may get stack overflows before reaching the limit set by the command. If
|
||||
this happens, see if there is a mechanism in your system for increasing
|
||||
the maximum size of the C stack.
|
||||
.RE
|
||||
.SH "SAFE INTERPRETERS"
|
||||
.PP
|
||||
A safe interpreter is one with restricted functionality, so that
|
||||
is safe to execute an arbitrary script from your worst enemy without
|
||||
fear of that script damaging the enclosing application or the rest
|
||||
of your computing environment. In order to make an interpreter
|
||||
safe, certain commands and variables are removed from the interpreter.
|
||||
For example, commands to create files on disk are removed, and the
|
||||
\fBexec\fR command is removed, since it could be used to cause damage
|
||||
through subprocesses.
|
||||
Limited access to these facilities can be provided, by creating
|
||||
aliases to the master interpreter which check their arguments carefully
|
||||
and provide restricted access to a safe subset of facilities.
|
||||
For example, file creation might be allowed in a particular subdirectory
|
||||
and subprocess invocation might be allowed for a carefully selected and
|
||||
fixed set of programs.
|
||||
.PP
|
||||
A safe interpreter is created by specifying the \fB\-safe\fR switch
|
||||
to the \fBinterp create\fR command. Furthermore, any slave created
|
||||
by a safe interpreter will also be safe.
|
||||
.PP
|
||||
A safe interpreter is created with exactly the following set of
|
||||
built-in commands:
|
||||
.DS
|
||||
.ta 1.2i 2.4i 3.6i
|
||||
\fBafter\fR \fBappend\fR \fBapply\fR \fBarray\fR
|
||||
\fBbinary\fR \fBbreak\fR \fBcatch\fR \fBchan\fR
|
||||
\fBclock\fR \fBclose\fR \fBconcat\fR \fBcontinue\fR
|
||||
\fBdict\fR \fBeof\fR \fBerror\fR \fBeval\fR
|
||||
\fBexpr\fR \fBfblocked\fR \fBfcopy\fR \fBfileevent\fR
|
||||
\fBflush\fR \fBfor\fR \fBforeach\fR \fBformat\fR
|
||||
\fBgets\fR \fBglobal\fR \fBif\fR \fBincr\fR
|
||||
\fBinfo\fR \fBinterp\fR \fBjoin\fR \fBlappend\fR
|
||||
\fBlassign\fR \fBlindex\fR \fBlinsert\fR \fBlist\fR
|
||||
\fBllength\fR \fBlrange\fR \fBlrepeat\fR \fBlreplace\fR
|
||||
\fBlsearch\fR \fBlset\fR \fBlsort\fR \fBnamespace\fR
|
||||
\fBpackage\fR \fBpid\fR \fBproc\fR \fBputs\fR
|
||||
\fBread\fR \fBregexp\fR \fBregsub\fR \fBrename\fR
|
||||
\fBreturn\fR \fBscan\fR \fBseek\fR \fBset\fR
|
||||
\fBsplit\fR \fBstring\fR \fBsubst\fR \fBswitch\fR
|
||||
\fBtell\fR \fBtime\fR \fBtrace\fR \fBunset\fR
|
||||
\fBupdate\fR \fBuplevel\fR \fBupvar\fR \fBvariable\fR
|
||||
\fBvwait\fR \fBwhile\fR
|
||||
.DE
|
||||
The following commands are hidden by \fBinterp create\fR when it
|
||||
creates a safe interpreter:
|
||||
.DS
|
||||
.ta 1.2i 2.4i 3.6i
|
||||
\fBcd\fR \fBencoding\fR \fBexec\fR \fBexit\fR
|
||||
\fBfconfigure\fR \fBfile\fR \fBglob\fR \fBload\fR
|
||||
\fBopen\fR \fBpwd\fR \fBsocket\fR \fBsource\fR
|
||||
\fBunload\fR
|
||||
.DE
|
||||
These commands can be recreated later as Tcl procedures or aliases, or
|
||||
re-exposed by \fBinterp expose\fR.
|
||||
.PP
|
||||
The following commands from Tcl's library of support procedures are
|
||||
not present in a safe interpreter:
|
||||
.DS
|
||||
.ta 1.6i 3.2i
|
||||
\fBauto_exec_ok\fR \fBauto_import\fR \fBauto_load\fR
|
||||
\fBauto_load_index\fR \fBauto_qualify\fR \fBunknown\fR
|
||||
.DE
|
||||
Note in particular that safe interpreters have no default \fBunknown\fR
|
||||
command, so Tcl's default autoloading facilities are not available.
|
||||
Autoload access to Tcl's commands that are normally autoloaded:
|
||||
.DS
|
||||
.ta 2.1i
|
||||
\fBauto_mkindex\fR \fBauto_mkindex_old\fR
|
||||
\fBauto_reset\fR \fBhistory\fR
|
||||
\fBparray\fR \fBpkg_mkIndex\fR
|
||||
\fB::pkg::create\fR \fB::safe::interpAddToAccessPath\fR
|
||||
\fB::safe::interpCreate\fR \fB::safe::interpConfigure\fR
|
||||
\fB::safe::interpDelete\fR \fB::safe::interpFindInAccessPath\fR
|
||||
\fB::safe::interpInit\fR \fB::safe::setLogCmd\fR
|
||||
\fBtcl_endOfWord\fR \fBtcl_findLibrary\fR
|
||||
\fBtcl_startOfNextWord\fR \fBtcl_startOfPreviousWord\fR
|
||||
\fBtcl_wordBreakAfter\fR \fBtcl_wordBreakBefore\fR
|
||||
.DE
|
||||
can only be provided by explicit definition of an \fBunknown\fR command
|
||||
in the safe interpreter. This will involve exposing the \fBsource\fR
|
||||
command. This is most easily accomplished by creating the safe interpreter
|
||||
with Tcl's \fBSafe\-Tcl\fR mechanism. \fBSafe\-Tcl\fR provides safe
|
||||
versions of \fBsource\fR, \fBload\fR, and other Tcl commands needed
|
||||
to support autoloading of commands and the loading of packages.
|
||||
.PP
|
||||
In addition, the \fBenv\fR variable is not present in a safe interpreter,
|
||||
so it cannot share environment variables with other interpreters. The
|
||||
\fBenv\fR variable poses a security risk, because users can store
|
||||
sensitive information in an environment variable. For example, the PGP
|
||||
manual recommends storing the PGP private key protection password in
|
||||
the environment variable \fIPGPPASS\fR. Making this variable available
|
||||
to untrusted code executing in a safe interpreter would incur a
|
||||
security risk.
|
||||
.PP
|
||||
If extensions are loaded into a safe interpreter, they may also restrict
|
||||
their own functionality to eliminate unsafe commands. For a discussion of
|
||||
management of extensions for safety see the manual entries for
|
||||
\fBSafe\-Tcl\fR and the \fBload\fR Tcl command.
|
||||
.PP
|
||||
A safe interpreter may not alter the recursion limit of any interpreter,
|
||||
including itself.
|
||||
.SH "ALIAS INVOCATION"
|
||||
.PP
|
||||
The alias mechanism has been carefully designed so that it can
|
||||
be used safely when an untrusted script is executing
|
||||
in a safe slave and the target of the alias is a trusted
|
||||
master. The most important thing in guaranteeing safety is to
|
||||
ensure that information passed from the slave to the master is
|
||||
never evaluated or substituted in the master; if this were to
|
||||
occur, it would enable an evil script in the slave to invoke
|
||||
arbitrary functions in the master, which would compromise security.
|
||||
.PP
|
||||
When the source for an alias is invoked in the slave interpreter, the
|
||||
usual Tcl substitutions are performed when parsing that command.
|
||||
These substitutions are carried out in the source interpreter just
|
||||
as they would be for any other command invoked in that interpreter.
|
||||
The command procedure for the source command takes its arguments
|
||||
and merges them with the \fItargetCmd\fR and \fIarg\fRs for the
|
||||
alias to create a new array of arguments. If the words
|
||||
of \fIsrcCmd\fR were
|
||||
.QW "\fIsrcCmd arg1 arg2 ... argN\fR" ,
|
||||
the new set of words will be
|
||||
.QW "\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR" ,
|
||||
where \fItargetCmd\fR and \fIarg\fRs are the values supplied when the
|
||||
alias was created. \fITargetCmd\fR is then used to locate a command
|
||||
procedure in the target interpreter, and that command procedure
|
||||
is invoked with the new set of arguments. An error occurs if
|
||||
there is no command named \fItargetCmd\fR in the target interpreter.
|
||||
No additional substitutions are performed on the words: the
|
||||
target command procedure is invoked directly, without
|
||||
going through the normal Tcl evaluation mechanism.
|
||||
Substitutions are thus performed on each word exactly once:
|
||||
\fItargetCmd\fR and \fIargs\fR were substituted when parsing the command
|
||||
that created the alias, and \fIarg1 - argN\fR are substituted when
|
||||
the alias's source command is parsed in the source interpreter.
|
||||
.PP
|
||||
When writing the \fItargetCmd\fRs for aliases in safe interpreters,
|
||||
it is very important that the arguments to that command never be
|
||||
evaluated or substituted, since this would provide an escape
|
||||
mechanism whereby the slave interpreter could execute arbitrary
|
||||
code in the master. This in turn would compromise the security
|
||||
of the system.
|
||||
.SH "HIDDEN COMMANDS"
|
||||
.PP
|
||||
Safe interpreters greatly restrict the functionality available to Tcl
|
||||
programs executing within them.
|
||||
Allowing the untrusted Tcl program to have direct access to this
|
||||
functionality is unsafe, because it can be used for a variety of
|
||||
attacks on the environment.
|
||||
However, there are times when there is a legitimate need to use the
|
||||
dangerous functionality in the context of the safe interpreter. For
|
||||
example, sometimes a program must be \fBsource\fRd into the interpreter.
|
||||
Another example is Tk, where windows are bound to the hierarchy of windows
|
||||
for a specific interpreter; some potentially dangerous functions, e.g.
|
||||
window management, must be performed on these windows within the
|
||||
interpreter context.
|
||||
.PP
|
||||
The \fBinterp\fR command provides a solution to this problem in the form of
|
||||
\fIhidden commands\fR. Instead of removing the dangerous commands entirely
|
||||
from a safe interpreter, these commands are hidden so they become
|
||||
unavailable to Tcl scripts executing in the interpreter. However, such
|
||||
hidden commands can be invoked by any trusted ancestor of the safe
|
||||
interpreter, in the context of the safe interpreter, using \fBinterp
|
||||
invoke\fR. Hidden commands and exposed commands reside in separate name
|
||||
spaces. It is possible to define a hidden command and an exposed command by
|
||||
the same name within one interpreter.
|
||||
.PP
|
||||
Hidden commands in a slave interpreter can be invoked in the body of
|
||||
procedures called in the master during alias invocation. For example, an
|
||||
alias for \fBsource\fR could be created in a slave interpreter. When it is
|
||||
invoked in the slave interpreter, a procedure is called in the master
|
||||
interpreter to check that the operation is allowable (e.g. it asks to
|
||||
source a file that the slave interpreter is allowed to access). The
|
||||
procedure then it invokes the hidden \fBsource\fR command in the slave
|
||||
interpreter to actually source in the contents of the file. Note that two
|
||||
commands named \fBsource\fR exist in the slave interpreter: the alias, and
|
||||
the hidden command.
|
||||
.PP
|
||||
Because a master interpreter may invoke a hidden command as part of
|
||||
handling an alias invocation, great care must be taken to avoid evaluating
|
||||
any arguments passed in through the alias invocation.
|
||||
Otherwise, malicious slave interpreters could cause a trusted master
|
||||
interpreter to execute dangerous commands on their behalf. See the section
|
||||
on \fBALIAS INVOCATION\fR for a more complete discussion of this topic.
|
||||
To help avoid this problem, no substitutions or evaluations are
|
||||
applied to arguments of \fBinterp invokehidden\fR.
|
||||
.PP
|
||||
Safe interpreters are not allowed to invoke hidden commands in themselves
|
||||
or in their descendants. This prevents safe slaves from gaining access to
|
||||
hidden functionality in themselves or their descendants.
|
||||
.PP
|
||||
The set of hidden commands in an interpreter can be manipulated by a trusted
|
||||
interpreter using \fBinterp expose\fR and \fBinterp hide\fR. The \fBinterp
|
||||
expose\fR command moves a hidden command to the
|
||||
set of exposed commands in the interpreter identified by \fIpath\fR,
|
||||
potentially renaming the command in the process. If an exposed command by
|
||||
the targeted name already exists, the operation fails. Similarly,
|
||||
\fBinterp hide\fR moves an exposed command to the set of hidden commands in
|
||||
that interpreter. Safe interpreters are not allowed to move commands
|
||||
between the set of hidden and exposed commands, in either themselves or
|
||||
their descendants.
|
||||
.PP
|
||||
Currently, the names of hidden commands cannot contain namespace
|
||||
qualifiers, and you must first rename a command in a namespace to the
|
||||
global namespace before you can hide it.
|
||||
Commands to be hidden by \fBinterp hide\fR are looked up in the global
|
||||
namespace even if the current namespace is not the global one. This
|
||||
prevents slaves from fooling a master interpreter into hiding the wrong
|
||||
command, by making the current namespace be different from the global one.
|
||||
.SH "RESOURCE LIMITS"
|
||||
.PP
|
||||
Every interpreter has two kinds of resource limits that may be imposed by any
|
||||
master interpreter upon its slaves. Command limits (of type \fBcommand\fR)
|
||||
restrict the total number of Tcl commands that may be executed by an
|
||||
interpreter (as can be inspected via the \fBinfo cmdcount\fR command), and
|
||||
time limits (of type \fBtime\fR) place a limit by which execution within the
|
||||
interpreter must complete. Note that time limits are expressed as
|
||||
\fIabsolute\fR times (as in \fBclock seconds\fR) and not relative times (as in
|
||||
\fBafter\fR) because they may be modified after creation.
|
||||
.PP
|
||||
When a limit is exceeded for an interpreter, first any handler callbacks
|
||||
defined by master interpreters are called. If those callbacks increase or
|
||||
remove the limit, execution within the (previously) limited interpreter
|
||||
continues. If the limit is still in force, an error is generated at that point
|
||||
and normal processing of errors within the interpreter (by the \fBcatch\fR
|
||||
command) is disabled, so the error propagates outwards (building a stack-trace
|
||||
as it goes) to the point where the limited interpreter was invoked (e.g. by
|
||||
\fBinterp eval\fR) where it becomes the responsibility of the calling code to
|
||||
catch and handle.
|
||||
.SS "LIMIT OPTIONS"
|
||||
.PP
|
||||
Every limit has a number of options associated with it, some of which are
|
||||
common across all kinds of limits, and others of which are particular to the
|
||||
kind of limit.
|
||||
.TP
|
||||
\fB\-command\fR
|
||||
.
|
||||
This option (common for all limit types) specifies (if non-empty) a Tcl script
|
||||
to be executed in the global namespace of the interpreter reading and writing
|
||||
the option when the particular limit in the limited interpreter is exceeded.
|
||||
The callback may modify the limit on the interpreter if it wishes the limited
|
||||
interpreter to continue executing. If the callback generates an exception, it
|
||||
is reported through the background exception mechanism (see
|
||||
\fBBACKGROUND EXCEPTION HANDLING\fR).
|
||||
Note that the callbacks defined by one interpreter are
|
||||
completely isolated from the callbacks defined by another, and that the order
|
||||
in which those callbacks are called is undefined.
|
||||
.TP
|
||||
\fB\-granularity\fR
|
||||
.
|
||||
This option (common for all limit types) specifies how frequently (out of the
|
||||
points when the Tcl interpreter is in a consistent state where limit checking
|
||||
is possible) that the limit is actually checked. This allows the tuning of how
|
||||
frequently a limit is checked, and hence how often the limit-checking overhead
|
||||
(which may be substantial in the case of time limits) is incurred.
|
||||
.TP
|
||||
\fB\-milliseconds\fR
|
||||
.
|
||||
This option specifies the number of milliseconds after the moment defined in
|
||||
the \fB\-seconds\fR option that the time limit will fire. It should only ever
|
||||
be specified in conjunction with the \fB\-seconds\fR option (whether it was
|
||||
set previously or is being set this invocation.)
|
||||
.TP
|
||||
\fB\-seconds\fR
|
||||
.
|
||||
This option specifies the number of seconds after the epoch (see \fBclock
|
||||
seconds\fR) that the time limit for the interpreter will be triggered. The
|
||||
limit will be triggered at the start of the second unless specified at a
|
||||
sub-second level using the \fB\-milliseconds\fR option. This option may be the
|
||||
empty string, which indicates that a time limit is not set for the
|
||||
interpreter.
|
||||
.TP
|
||||
\fB\-value\fR
|
||||
.
|
||||
This option specifies the number of commands that the interpreter may execute
|
||||
before triggering the command limit. This option may be the empty string,
|
||||
which indicates that a command limit is not set for the interpreter.
|
||||
.PP
|
||||
Where an interpreter with a resource limit set on it creates a slave
|
||||
interpreter, that slave interpreter will have resource limits imposed on it
|
||||
that are at least as restrictive as the limits on the creating master
|
||||
interpreter. If the master interpreter of the limited master wishes to relax
|
||||
these conditions, it should hide the \fBinterp\fR command in the child and
|
||||
then use aliases and the \fBinterp invokehidden\fR subcommand to provide such
|
||||
access as it chooses to the \fBinterp\fR command to the limited master as
|
||||
necessary.
|
||||
.SH "BACKGROUND EXCEPTION HANDLING"
|
||||
.PP
|
||||
When an exception happens in a situation where it cannot be reported directly up
|
||||
the stack (e.g. when processing events in an \fBupdate\fR or \fBvwait\fR call)
|
||||
the exception is instead reported through the background exception handling mechanism.
|
||||
Every interpreter has a background exception handler registered; the default exception
|
||||
handler arranges for the \fBbgerror\fR command in the interpreter's global
|
||||
namespace to be called, but other exception handlers may be installed and process
|
||||
background exceptions in substantially different ways.
|
||||
.PP
|
||||
A background exception handler consists of a non-empty list of words to which will
|
||||
be appended two further words at invocation time. The first word will be the
|
||||
interpreter result at time of the exception, typically an error message,
|
||||
and the second will be the dictionary of return options at the time of
|
||||
the exception. These are the same values that \fBcatch\fR can capture
|
||||
when it controls script evaluation in a non-background situation.
|
||||
The resulting list will then be executed
|
||||
in the interpreter's global namespace without further substitutions being
|
||||
performed.
|
||||
.SH CREDITS
|
||||
The safe interpreter mechanism is based on the Safe-Tcl prototype implemented
|
||||
by Nathaniel Borenstein and Marshall Rose.
|
||||
.SH EXAMPLES
|
||||
.PP
|
||||
Creating and using an alias for a command in the current interpreter:
|
||||
.PP
|
||||
.CS
|
||||
\fBinterp alias\fR {} getIndex {} lsearch {alpha beta gamma delta}
|
||||
set idx [getIndex delta]
|
||||
.CE
|
||||
.PP
|
||||
Executing an arbitrary command in a safe interpreter where every
|
||||
invocation of \fBlappend\fR is logged:
|
||||
.PP
|
||||
.CS
|
||||
set i [\fBinterp create\fR -safe]
|
||||
\fBinterp hide\fR $i lappend
|
||||
\fBinterp alias\fR $i lappend {} loggedLappend $i
|
||||
proc loggedLappend {i args} {
|
||||
puts "logged invocation of lappend $args"
|
||||
\fBinterp invokehidden\fR $i lappend {*}$args
|
||||
}
|
||||
\fBinterp eval\fR $i $someUntrustedScript
|
||||
.CE
|
||||
.PP
|
||||
Setting a resource limit on an interpreter so that an infinite loop
|
||||
terminates.
|
||||
.PP
|
||||
.CS
|
||||
set i [\fBinterp create\fR]
|
||||
\fBinterp limit\fR $i command -value 1000
|
||||
\fBinterp eval\fR $i {
|
||||
set x 0
|
||||
while {1} {
|
||||
puts "Counting up... [incr x]"
|
||||
}
|
||||
}
|
||||
.CE
|
||||
.SH "SEE ALSO"
|
||||
bgerror(n), load(n), safe(n), Tcl_CreateSlave(3), Tcl_Eval(3), Tcl_BackgroundException(3)
|
||||
.SH KEYWORDS
|
||||
alias, master interpreter, safe interpreter, slave interpreter
|
||||
'\"Local Variables:
|
||||
'\"mode: nroff
|
||||
'\"End:
|
||||
Reference in New Issue
Block a user