More tidies and documentation for stack frame measurement.

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

4 files changed, 60 insertions, 8 deletions

diff --git a/doc/pcreapi.3 b/doc/pcreapi.3
index 114efee..b6f2507 100644
--- a/doc/pcreapi.3
+++ b/doc/pcreapi.3
@@ -2413,6 +2413,32 @@ other alternatives. Ultimately, when it runs out of matches, \fBpcre_exec()\fP
 will yield PCRE_ERROR_NOMATCH.
 .
 .
+.SH "OBTAINING AN ESTIMATE OF STACK USAGE"
+.rs
+.sp
+Matching certain patterns using \fBpcre_exec()\fP can use a lot of process
+stack, which in certain environments can be rather limited in size. Some users 
+find it helpful to have an estimate of the amount of stack that is used by 
+\fBpcre_exec()\fP, to help them set recursion limits, as described in the
+.\" HREF
+\fBpcrestack\fP
+.\"
+documentation. The estimate that is output by \fBpcretest\fP when called with 
+the \fB-m\fP and \fB-C\fP options is obtained by calling \fBpcre_exec\fP with 
+the values NULL, NULL, NULL, -999, and -999 for its first five arguments.
+.P
+Normally, if its first argument is NULL, \fBpcre_exec()\fP immediately returns
+the negative error code PCRE_ERROR_NULL, but with this special combination of
+arguments, it returns instead a negative number whose absolute value is the
+approximate stack frame size in bytes. (A negative number is used so that it is
+clear that no match has happened.) The value is approximate because in some
+cases, recursive calls to \fBpcre_exec()\fP occur when there are one or two 
+additional variables on the stack.
+.P
+If PCRE has been compiled to use the heap instead of the stack for recursion, 
+the value returned is the size of each block that is obtained from the heap.
+.
+.
 .\" HTML <a name="dfamatch"></a>
 .SH "MATCHING A PATTERN: THE ALTERNATIVE FUNCTION"
 .rs
@@ -2618,6 +2644,6 @@ Cambridge CB2 3QH, England.
 .rs
 .sp
 .nf
-Last updated: 17 January 2012
+Last updated: 21 January 2012
 Copyright (c) 1997-2012 University of Cambridge.
 .fi
diff --git a/doc/pcrestack.3 b/doc/pcrestack.3
index 0191842..37a6fe4 100644
--- a/doc/pcrestack.3
+++ b/doc/pcrestack.3
@@ -123,9 +123,9 @@ in the
 documentation.
 .P
 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.
+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.
 .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
@@ -135,6 +135,31 @@ string. This is done by calling \fBpcre[16]_exec()\fP repeatedly with different
 limits.
 .
 .
+.SS "Obtaining an estimate of stack usage"
+.rs
+.sp
+The actual amount of stack used per recursion can vary quite a lot, depending
+on the compiler that was used to build PCRE and the optimization or debugging
+options that were set for it. The rule of thumb value of 500 bytes mentioned 
+above may be larger or smaller than what is actually needed. A better 
+approximation can be obtained by running this command:
+.sp
+  pcretest -m -C
+.sp
+The \fB-C\fP option causes \fBpcretest\fP to output information about the 
+options with which PCRE was compiled. When \fB-m\fP is also given (before 
+\fB-C\fP), information about stack use is given in a line like this:
+.sp
+  Match recursion uses stack: approximate frame size = 640 bytes
+.sp      
+The value is approximate because some recursions need a bit more (up to perhaps 
+16 more bytes).
+.P
+If the above command is given when PCRE is compiled to use the heap instead of 
+the stack for recursion, the value that is output is the size of each block 
+that is obtained from the heap. 
+.
+.
 .SS "Changing stack size in Unix-like systems"
 .rs
 .sp
@@ -185,6 +210,6 @@ Cambridge CB2 3QH, England.
 .rs
 .sp
 .nf
-Last updated: 10 January 2012
+Last updated: 21 January 2012
 Copyright (c) 1997-2012 University of Cambridge.
 .fi
diff --git a/pcre_exec.c b/pcre_exec.c
index 0b49cf6..9fdda7a 100644
--- a/pcre_exec.c
+++ b/pcre_exec.c
@@ -619,7 +619,7 @@ eptrblock newptrb;
 /* There is a special fudge for calling match() in a way that causes it to 
 measure the size of its basic stack frame when the stack is being used for
 recursion. The second argument (ecode) being NULL triggers this behaviour. It
-cannot normally every be NULL. The return is the negated value of the frame
+cannot normally ever be NULL. The return is the negated value of the frame
 size. */
 
 if (ecode == NULL)
@@ -6210,7 +6210,8 @@ const REAL_PCRE *re = (const REAL_PCRE *)argument_re;
 /* Check for the special magic call that measures the size of the stack used 
 per recursive call of match(). */
 
-if (re == NULL && extra_data == NULL && subject == NULL && length == -1)
+if (re == NULL && extra_data == NULL && subject == NULL && length == -999 &&
+    start_offset == -999)
 #ifdef NO_RECURSE
   return -sizeof(heapframe);
 #else  
diff --git a/pcretest.c b/pcretest.c
index c3e547a..dcb46d6 100644
--- a/pcretest.c
+++ b/pcretest.c
@@ -2439,7 +2439,7 @@ are set, either both UTFs are supported or both are not supported. */
     printf("  Match recursion uses %s", rc? "stack" : "heap");
     if (showstore)
       { 
-      PCRE_EXEC(stack_size, NULL, NULL, NULL, -1, -1, 0, NULL, 0);
+      PCRE_EXEC(stack_size, NULL, NULL, NULL, -999, -999, 0, NULL, 0);
       printf(": %sframe size = %d bytes", rc? "approximate " : "", -stack_size); 
       }
     printf("\n");