* Added the [interp recursionlimit] command to

        set/query the recursion limit of an interpreter.  Proposal and
        implementation from Stephen Trier. [TIP 87, Patch 522849]

1 files changed, 39 insertions, 2 deletions

diff --git a/doc/interp.n b/doc/interp.n
index 52d3bfd..e753299 100644
--- a/doc/interp.n
+++ b/doc/interp.n
@@ -4,7 +4,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.7 2001/08/07 02:54:30 hobbs Exp $
+'\" RCS: @(#) $Id: interp.n,v 1.8 2002/03/07 20:17:22 dgp Exp $
 '\" 
 .so man.macros
 .TH interp n 7.6 Tcl "Tcl Built-In Commands"
@@ -147,6 +147,8 @@ 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 \fBdelete \fR?\fIpath ...?\fR
 Deletes zero or more interpreters given by the optional \fIpath\fR
@@ -222,6 +224,23 @@ The command has no effect if the interpreter identified by \fIpath\fR is
 already trusted.
 .VE
 .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.  
+.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. 
+.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
@@ -349,7 +368,22 @@ 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.
 .VE
-
+.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.  
+.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. 
 .SH "SAFE INTERPRETERS"
 .PP
 A safe interpreter is one with restricted functionality, so that
@@ -450,6 +484,9 @@ 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