From 20cafacaa4d4c2fca25f7f3f7dd1af592073101c Mon Sep 17 00:00:00 2001 From: "Philip.Hazel" Date: Tue, 21 Mar 2017 12:21:55 +0000 Subject: [PATCH] Documentation update. --- doc/pcre2grep.1 | 46 +++++++++++++++++++++------------------------- 1 file changed, 21 insertions(+), 25 deletions(-) diff --git a/doc/pcre2grep.1 b/doc/pcre2grep.1 index 80e8899..b2d248b 100644 --- a/doc/pcre2grep.1 +++ b/doc/pcre2grep.1 @@ -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 @@ compatibility with GNU grep), "recurse" (equivalent to the \fB-r\fP option), or 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 @@ locale is specified, the PCRE2 library's default (usually the "C" locale) is 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 @@ message and the line that caused the problem to the standard error stream. If 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 @@ Cambridge, England. .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