Revision: 480
http://vcs.pcre.org/viewvc?view=rev&revision=480
Author: ph10
Date: 2010-01-03 17:29:59 +0000 (Sun, 03 Jan 2010)
Log Message:
-----------
Update stack documentation to be clearer about pcre_dfa_exec().
Modified Paths:
--------------
code/trunk/ChangeLog
code/trunk/doc/pcrestack.3
Modified: code/trunk/ChangeLog
===================================================================
--- code/trunk/ChangeLog 2010-01-03 16:31:39 UTC (rev 479)
+++ code/trunk/ChangeLog 2010-01-03 17:29:59 UTC (rev 480)
@@ -76,6 +76,11 @@
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.
Modified: code/trunk/doc/pcrestack.3
===================================================================
--- code/trunk/doc/pcrestack.3 2010-01-03 16:31:39 UTC (rev 479)
+++ code/trunk/doc/pcrestack.3 2010-01-03 17:29:59 UTC (rev 480)
@@ -17,23 +17,22 @@
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.
+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
-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.
-.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 @@
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 @@
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,9 +110,16 @@
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
.sp
@@ -129,6 +143,7 @@
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 @@
.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
