diff options
Diffstat (limited to 'doc/interp.n')
| -rw-r--r-- | doc/interp.n | 79 |
1 files changed, 40 insertions, 39 deletions
diff --git a/doc/interp.n b/doc/interp.n index 880925a..615fbbd 100644 --- a/doc/interp.n +++ b/doc/interp.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: interp.n,v 1.25 2006/11/03 00:34:52 hobbs Exp $ +'\" RCS: @(#) $Id: interp.n,v 1.26 2007/02/18 01:06:14 dkf Exp $ '\" .so man.macros .TH interp n 7.6 Tcl "Tcl Built-In Commands" @@ -19,10 +19,10 @@ interp \- Create and manipulate Tcl interpreters .SH DESCRIPTION .PP -This command makes it possible to create one or more new Tcl +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. +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. @@ -59,8 +59,8 @@ 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 +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 @@ -121,7 +121,7 @@ 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. +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. @@ -129,8 +129,8 @@ does not have to be equal to \fIsrcCmd\fR. \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 +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? @@ -205,11 +205,11 @@ Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. \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 +\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 +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 @@ -231,7 +231,7 @@ 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. -If both the \fB-namespace\fR and \fB-global\fR flags are present, the +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. @@ -267,14 +267,14 @@ 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. +maximum value of a non-long integer on the platform. .sp 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. +the maximum size of the C stack. .TP \fBinterp\fR \fBshare\fR \fIsrcPath channelId destPath\fR Causes the IO channel identified by \fIchannelId\fR to become shared @@ -321,7 +321,7 @@ The valid forms of this command are: \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 +the aliases were created (which may not be the same as the current names of the commands). .TP \fIslave \fBalias \fIsrcToken\fR @@ -381,12 +381,12 @@ 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 +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 +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 @@ -406,11 +406,11 @@ 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. -If both the \fB-namespace\fR and \fB-global\fR flags are given, the +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, +For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. .TP \fIslave \fBissafe\fR @@ -440,14 +440,14 @@ 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. +maximum value of a non-long integer on the platform. .sp 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. +the maximum size of the C stack. .SH "SAFE INTERPRETERS" .PP A safe interpreter is one with restricted functionality, so that @@ -473,23 +473,24 @@ A safe interpreter is created with exactly the following set of built-in commands: .DS .ta 1.2i 2.4i 3.6i -\fBafter append array binary -break case catch clock -close concat continue eof -error eval expr fblocked -fcopy fileevent flush for -foreach format gets global -if incr info interp -join lappend lindex linsert -list llength lrange lreplace -lsearch lsort namespace package -pid proc puts read -regexp regsub rename return -scan seek set split -string subst switch tell -time trace unset update -uplevel upvar variable vwait -while\fR +\fBafter append apply array +binary break case catch +clock close concat continue +dict eof error eval +expr fblocked fcopy fileevent +flush for foreach format +gets global if incr +info interp join lappend +lassign lindex linsert list +llength lrange lrepeat lreplace +lsearch lset lsort namespace +package pid proc puts +read regexp regsub rename +return scan seek set +split string subst switch +tell time trace unset +update uplevel upvar variable +vwait while\fR .DE The following commands are hidden by \fBinterp create\fR when it creates a safe interpreter: @@ -497,7 +498,7 @@ creates a safe interpreter: .ta 1.2i 2.4i 3.6i \fBcd encoding exec exit fconfigure file glob load -open pwd socket source\fR +open pwd socket source unload\fR .DE These commands can be recreated later as Tcl procedures or aliases, or re-exposed by \fBinterp expose\fR. @@ -510,7 +511,7 @@ not present in a safe interpreter: auto_load_index auto_qualify unknown\fR .DE Note in particular that safe interpreters have no default \fBunknown\fR -command, so Tcl's default autoloading facilities are not available. +command, so Tcl's default autoloading facilities are not available. Autoload access to Tcl's commands that are normally autoloaded: .DS .ta 2.1i |