Update stack documentation to be clearer about pcre_dfa_exec().

git-svn-id: svn://vcs.exim.org/pcre/code/trunk@480 2f5784b3-3f2a-0410-8824-cb99058d5e15

2 files changed, 50 insertions, 30 deletions

diff --git a/ChangeLog b/ChangeLog
index 4624702..3754c38 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -76,6 +76,11 @@ Version 8.01 11-Dec-09
       Consider adding `-I m4' to ACLOCAL_AMFLAGS in Makefile.am.
       
     I have done both of these things.
+    
+12. Although pcre_dfa_exec() does not use nearly as much stack as pcre_exec()
+    most of the time, it *can* run out if it is given a pattern that contains a 
+    runaway infinite recursion. I updated the discussion in the pcrestack man 
+    page.  
  
 
 
diff --git a/doc/pcrestack.3 b/doc/pcrestack.3
index 845425d..686fe6a 100644
--- a/doc/pcrestack.3
+++ b/doc/pcrestack.3
@@ -17,23 +17,22 @@ the recursive call would immediately be passed back as the result of the
 current call (a "tail recursion"), the function is just restarted instead.
 .P
 The \fBpcre_dfa_exec()\fP function operates in an entirely different way, and
-hardly uses recursion at all. The limit on its complexity is the amount of
-workspace it is given. The comments that follow do NOT apply to
-\fBpcre_dfa_exec()\fP; they are relevant only for \fBpcre_exec()\fP.
-.P
-You can set limits on the number of times that \fBmatch()\fP is called, both in
-total and recursively. If the limit is exceeded, an error occurs. For details,
-see the
-.\" HTML <a href="pcreapi.html#extradata">
-.\" </a>
-section on extra data for \fBpcre_exec()\fP
-.\"
-in the
-.\" HREF
-\fBpcreapi\fP
-.\"
-documentation.
+uses recursion only when there is a regular expression recursion or subroutine
+call in the pattern. This includes the processing of assertion and "once-only"
+subpatterns, which are handled like subroutine calls. Normally, these are never
+very deep, and the limit on the complexity of \fBpcre_dfa_exec()\fP is
+controlled by the amount of workspace it is given. However, it is possible to
+write patterns with runaway infinite recursions; such patterns will cause
+\fBpcre_dfa_exec()\fP to run out of stack. At present, there is no protection
+against this.
 .P
+The comments that follow do NOT apply to \fBpcre_dfa_exec()\fP; they are
+relevant only for \fBpcre_exec()\fP.
+.
+.
+.SS "Reducing \fBpcre_exec()\fP's stack usage"
+.rs
+.sp
 Each time that \fBmatch()\fP is actually called recursively, it uses memory
 from the process stack. For certain kinds of pattern and data, very large
 amounts of stack may be needed, despite the recognition of "tail recursion".
@@ -65,13 +64,14 @@ This example shows that one way of avoiding stack problems when matching long
 subject strings is to write repeated parenthesized subpatterns to match more
 than one character whenever possible.
 .
-.SS "Compiling PCRE to use heap instead of stack"
+.
+.SS "Compiling PCRE to use heap instead of stack for \fBpcre_exec()\fP"
 .rs
 .sp
 In environments where stack memory is constrained, you might want to compile
-PCRE to use heap memory instead of stack for remembering back-up points. This
-makes it run a lot more slowly, however. Details of how to do this are given in
-the
+PCRE to use heap memory instead of stack for remembering back-up points when
+\fBpcre_exec()\fP is running. This makes it run a lot more slowly, however.
+Details of how to do this are given in the
 .\" HREF
 \fBpcrebuild\fP
 .\"
@@ -83,18 +83,25 @@ cause PCRE to use your own functions. Since the block sizes are always the
 same, and are always freed in reverse order, it may be possible to implement
 customized memory handlers that are more efficient than the standard functions.
 .
-.SS "Limiting PCRE's stack usage"
+.
+.SS "Limiting \fBpcre_exec()\fP's stack usage"
 .rs
 .sp
-PCRE has an internal counter that can be used to limit the depth of recursion,
-and thus cause \fBpcre_exec()\fP to give an error code before it runs out of
-stack. By default, the limit is very large, and unlikely ever to operate. It
-can be changed when PCRE is built, and it can also be set when
+You can set limits on the number of times that \fBmatch()\fP is called, both in
+total and recursively. If a limit is exceeded, \fBpcre_exec()\fP returns an
+error code. Setting suitable limits should prevent it from running out of
+stack. The default values of the limits are very large, and unlikely ever to
+operate. They can be changed when PCRE is built, and they can also be set when
 \fBpcre_exec()\fP is called. For details of these interfaces, see the
 .\" HREF
 \fBpcrebuild\fP
 .\"
-and
+documentation and the
+.\" HTML <a href="pcreapi.html#extradata">
+.\" </a>
+section on extra data for \fBpcre_exec()\fP
+.\"
+in the
 .\" HREF
 \fBpcreapi\fP
 .\"
@@ -103,8 +110,15 @@ documentation.
 As a very rough rule of thumb, you should reckon on about 500 bytes per
 recursion. Thus, if you want to limit your stack usage to 8Mb, you
 should set the limit at 16000 recursions. A 64Mb stack, on the other hand, can
-support around 128000 recursions. The \fBpcretest\fP test program has a command
-line option (\fB-S\fP) that can be used to increase the size of its stack.
+support around 128000 recursions. 
+.P
+In Unix-like environments, the \fBpcretest\fP test program has a command line
+option (\fB-S\fP) that can be used to increase the size of its stack. As long
+as the stack is large enough, another option (\fB-M\fP) can be used to find the
+smallest limits that allow a particular pattern to match a given subject
+string. This is done by calling \fBpcre_exec()\fP repeatedly with different
+limits.
+.
 .
 .SS "Changing stack size in Unix-like systems"
 .rs
@@ -129,6 +143,7 @@ This reads the current limits (soft and hard) using \fBgetrlimit()\fP, then
 attempts to increase the soft limit to 100Mb using \fBsetrlimit()\fP. You must
 do this before calling \fBpcre_exec()\fP.
 .
+.
 .SS "Changing stack size in Mac OS X"
 .rs
 .sp
@@ -155,6 +170,6 @@ Cambridge CB2 3QH, England.
 .rs
 .sp
 .nf
-Last updated: 09 July 2008
-Copyright (c) 1997-2008 University of Cambridge.
+Last updated: 03 January 2010
+Copyright (c) 1997-2010 University of Cambridge.
 .fi