Revision: 689
http://www.exim.org/viewvc/pcre2?view=rev&revision=689
Author: ph10
Date: 2017-03-21 12:21:55 +0000 (Tue, 21 Mar 2017)
Log Message:
-----------
Documentation update.
Modified Paths:
--------------
code/trunk/doc/pcre2grep.1
Modified: code/trunk/doc/pcre2grep.1
===================================================================
--- code/trunk/doc/pcre2grep.1 2017-03-20 10:41:13 UTC (rev 688)
+++ code/trunk/doc/pcre2grep.1 2017-03-21 12:21:55 UTC (rev 689)
@@ -1,4 +1,4 @@
-.TH PCRE2GREP 1 "31 December 2016" "PCRE2 10.23"
+.TH PCRE2GREP 1 "21 March 2017" "PCRE2 10.30"
.SH NAME
pcre2grep - a grep with Perl-compatible regular expressions.
.SH SYNOPSIS
@@ -236,6 +236,9 @@
operating systems the effect of reading a directory like this is an immediate
end-of-file; in others it may provoke an error.
.TP
+\fB--depth-limit\fP=\fInumber\fP
+See \fB--match-limit\fP below.
+.TP
\fB-e\fP \fIpattern\fP, \fB--regex=\fP\fIpattern\fP, \fB--regexp=\fP\fIpattern\fP
Specify a pattern to be matched. This option can be used multiple times in
order to specify several patterns. It can also be used as a way of specifying a
@@ -430,27 +433,20 @@
used. There is no short form for this option.
.TP
\fB--match-limit\fP=\fInumber\fP
-Processing some regular expression patterns can require a very large amount of
-memory, leading in some cases to a program crash if not enough is available.
-Other patterns may take a very long time to search for all possible matching
-strings. The \fBpcre2_match()\fP function that is called by \fBpcre2grep\fP to
-do the matching has two parameters that can limit the resources that it uses.
+Processing some regular expression patterns may take a very long time to search
+for all possible matching strings. Others may require a very large amount of
+memory. There are two options that set resource limits for matching.
.sp
-The \fB--match-limit\fP option provides a means of limiting resource usage
-when processing patterns that are not going to match, but which have a very
-large number of possibilities in their search trees. The classic example is a
-pattern that uses nested unlimited repeats. Internally, PCRE2 uses a function
-called \fBmatch()\fP which it calls repeatedly (sometimes recursively). The
-limit set by \fB--match-limit\fP is imposed on the number of times this
-function is called during a match, which has the effect of limiting the amount
-of backtracking that can take place.
+The \fB--match-limit\fP option provides a means of limiting computing resource
+usage when processing patterns that are not going to match, but which have a
+very large number of possibilities in their search trees. The classic example
+is a pattern that uses nested unlimited repeats. Internally, PCRE2 has a
+counter that is incremented each time around its main processing loop. If the
+value set by \fB--match-limit\fP is reached, an error occurs.
.sp
-The \fB--recursion-limit\fP option is similar to \fB--match-limit\fP, but
-instead of limiting the total number of times that \fBmatch()\fP is called, it
-limits the depth of recursive calls, which in turn limits the amount of memory
-that can be used. The recursion depth is a smaller number than the total number
-of calls, because not all calls to \fBmatch()\fP are recursive. This limit is
-of use only if it is set smaller than \fB--match-limit\fP.
+The \fB--depth-limit\fP option limits the depth of nested backtracking points,
+which in turn limits the amount of memory that is used. This limit is of use
+only if it is set smaller than \fB--match-limit\fP.
.sp
There are no short forms for these options. The default settings are specified
when the PCRE2 library is compiled, with the default default being 10 million.
@@ -758,9 +754,9 @@
there are more than 20 such errors, \fBpcre2grep\fP gives up.
.P
The \fB--match-limit\fP option of \fBpcre2grep\fP can be used to set the
-overall resource limit; there is a second option called \fB--recursion-limit\fP
-that sets a limit on the amount of memory (usually stack) that is used (see the
-discussion of these options above).
+overall resource limit; there is a second option called \fB--depth-limit\fP
+that sets a limit on the amount of memory that is used (see the discussion of
+these options above).
.
.
.SH DIAGNOSTICS
@@ -793,6 +789,6 @@
.rs
.sp
.nf
-Last updated: 31 December 2016
-Copyright (c) 1997-2016 University of Cambridge.
+Last updated: 21 March 2017
+Copyright (c) 1997-2017 University of Cambridge.
.fi
