More tidies and documentation for stack frame measurement.

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

1 files changed, 29 insertions, 4 deletions

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