diff options
Diffstat (limited to 'doc/pcre2api.3')
| -rw-r--r-- | doc/pcre2api.3 | 66 |
1 files changed, 35 insertions, 31 deletions
diff --git a/doc/pcre2api.3 b/doc/pcre2api.3 index edde3db7..28c6033a 100644 --- a/doc/pcre2api.3 +++ b/doc/pcre2api.3 @@ -1,4 +1,4 @@ -.TH PCRE2API 3 "14 December 2021" "PCRE2 10.40" +.TH PCRE2API 3 "27 July 2022" "PCRE2 10.41" .SH NAME PCRE2 - Perl-compatible regular expressions (revised API) .sp @@ -953,7 +953,7 @@ has its own memory control arrangements (see the documentation for more details). If the limit is reached, the negative error code PCRE2_ERROR_HEAPLIMIT is returned. The default limit can be set when PCRE2 is built; if it is not, the default is set very large and is essentially -"unlimited". +unlimited. .P A value for the heap limit may also be supplied by an item at the start of a pattern of the form @@ -964,18 +964,18 @@ where ddd is a decimal number. However, such a setting is ignored unless ddd is less than the limit set by the caller of \fBpcre2_match()\fP or, if no such limit is set, less than the default. .P -The \fBpcre2_match()\fP function starts out using a 20KiB vector on the system -stack for recording backtracking points. The more nested backtracking points -there are (that is, the deeper the search tree), the more memory is needed. -Heap memory is used only if the initial vector is too small. If the heap limit -is set to a value less than 21 (in particular, zero) no heap memory will be -used. In this case, only patterns that do not have a lot of nested backtracking -can be successfully processed. +The \fBpcre2_match()\fP function always needs some heap memory, so setting a +value of zero guarantees a "heap limit exceeded" error. Details of how +\fBpcre2_match()\fP uses the heap are given in the +.\" HREF +\fBpcre2perform\fP +.\" +documentation. .P -Similarly, for \fBpcre2_dfa_match()\fP, a vector on the system stack is used -when processing pattern recursions, lookarounds, or atomic groups, and only if -this is not big enough is heap memory used. In this case, too, setting a value -of zero disables the use of the heap. +For \fBpcre2_dfa_match()\fP, a vector on the system stack is used when +processing pattern recursions, lookarounds, or atomic groups, and only if this +is not big enough is heap memory used. In this case, setting a value of zero +disables the use of the heap. .sp .nf .B int pcre2_set_match_limit(pcre2_match_context *\fImcontext\fP, @@ -1019,10 +1019,10 @@ less than the limit set by the caller of \fBpcre2_match()\fP or .fi .sp This parameter limits the depth of nested backtracking in \fBpcre2_match()\fP. -Each time a nested backtracking point is passed, a new memory "frame" is used +Each time a nested backtracking point is passed, a new memory frame is used to remember the state of matching at that point. Thus, this parameter indirectly limits the amount of memory that is used in a match. However, -because the size of each memory "frame" depends on the number of capturing +because the size of each memory frame depends on the number of capturing parentheses, the actual memory limit varies from pattern to pattern. This limit was more useful in versions before 10.30, where function recursion was used for backtracking. @@ -1323,8 +1323,7 @@ If \fIerrorcode\fP or \fIerroroffset\fP is NULL, \fBpcre2_compile()\fP returns NULL immediately. Otherwise, the variables to which these point are set to an error code and an offset (number of code units) within the pattern, respectively, when \fBpcre2_compile()\fP returns NULL because a compilation -error has occurred. The values are not defined when compilation is successful -and \fBpcre2_compile()\fP returns a non-NULL value. +error has occurred. .P There are nearly 100 positive error codes that \fBpcre2_compile()\fP may return if it finds an error in the pattern. There are also some negative error codes @@ -1343,14 +1342,17 @@ message" below) .\" should be self-explanatory. Macro names starting with PCRE2_ERROR_ are defined -for both positive and negative error codes in \fBpcre2.h\fP. +for both positive and negative error codes in \fBpcre2.h\fP. When compilation +is successful \fIerrorcode\fP is set to a value that returns the message "no +error" if passed to \fBpcre2_get_error_message()\fP. .P The value returned in \fIerroroffset\fP is an indication of where in the -pattern the error occurred. It is not necessarily the furthest point in the -pattern that was read. For example, after the error "lookbehind assertion is -not fixed length", the error offset points to the start of the failing -assertion. For an invalid UTF-8 or UTF-16 string, the offset is that of the -first code unit of the failing character. +pattern an error occurred. When there is no error, zero is returned. A non-zero +value is not necessarily the furthest point in the pattern that was read. For +example, after the error "lookbehind assertion is not fixed length", the error +offset points to the start of the failing assertion. For an invalid UTF-8 or +UTF-16 string, the offset is that of the first code unit of the failing +character. .P Some errors are not detected until the whole pattern has been scanned; in these cases, the offset passed back is the length of the pattern. Note that the @@ -2517,7 +2519,9 @@ large enough to hold as many as are expected. A minimum of at least 1 pair is imposed by \fBpcre2_match_data_create()\fP, so it is always possible to return the overall matched string in the case of \fBpcre2_match()\fP or the longest match in the case of -\fBpcre2_dfa_match()\fP. +\fBpcre2_dfa_match()\fP. The maximum number of pairs is 65535; if the the first +argument of \fBpcre2_match_data_create()\fP is greater than this, 65535 is +used. .P The second argument of \fBpcre2_match_data_create()\fP is a pointer to a general context, which can specify custom memory management for obtaining the @@ -3160,11 +3164,11 @@ The backtracking match limit was reached. .sp PCRE2_ERROR_NOMEMORY .sp -If a pattern contains many nested backtracking points, heap memory is used to -remember them. This error is given when the memory allocation function (default -or custom) fails. Note that a different error, PCRE2_ERROR_HEAPLIMIT, is given -if the amount of memory needed exceeds the heap limit. PCRE2_ERROR_NOMEMORY is -also returned if PCRE2_COPY_MATCHED_SUBJECT is set and memory allocation fails. +Heap memory is used to remember backgracking points. This error is given when +the memory allocation function (default or custom) fails. Note that a different +error, PCRE2_ERROR_HEAPLIMIT, is given if the amount of memory needed exceeds +the heap limit. PCRE2_ERROR_NOMEMORY is also returned if +PCRE2_COPY_MATCHED_SUBJECT is set and memory allocation fails. .sp PCRE2_ERROR_NULL .sp @@ -4025,6 +4029,6 @@ Cambridge, England. .rs .sp .nf -Last updated: 14 December 2021 -Copyright (c) 1997-2021 University of Cambridge. +Last updated: 27 July 2022 +Copyright (c) 1997-2022 University of Cambridge. .fi |