update tcl/tk

1 files changed, 0 insertions, 910 deletions

diff --git a/tcl8.6/doc/interp.n b/tcl8.6/doc/interp.n
deleted file mode 100644
index 92113a6..0000000
--- a/tcl8.6/doc/interp.n
+++ /dev/null
@@ -1,910 +0,0 @@
-'\"
-'\" 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: