From f17eb554bf8940d3a1167a841ccf980bdc288931 Mon Sep 17 00:00:00 2001 From: "Philip.Hazel" Date: Sat, 25 Mar 2017 17:50:54 +0000 Subject: [PATCH] Documentation update. --- Makefile.am | 2 + doc/html/index.html | 7 +++- doc/html/pcre2_match_data_free.html | 4 +- doc/html/pcre2_pattern_info.html | 17 ++++---- doc/html/pcre2_set_callout.html | 2 +- doc/html/pcre2_set_depth_limit.html | 40 +++++++++++++++++++ doc/html/pcre2_set_recursion_limit.html | 4 +- ...pcre2_set_recursion_memory_management.html | 9 +---- doc/html/pcre2test.html | 16 +++++--- doc/index.html.src | 7 +++- doc/pcre2_match_data_free.3 | 6 +-- doc/pcre2_pattern_info.3 | 13 ++++-- doc/pcre2_set_callout.3 | 4 +- doc/pcre2_set_depth_limit.3 | 28 +++++++++++++ doc/pcre2_set_recursion_limit.3 | 6 +-- doc/pcre2_set_recursion_memory_management.3 | 11 ++--- doc/pcre2test.txt | 18 +++++---- 17 files changed, 136 insertions(+), 58 deletions(-) create mode 100644 doc/html/pcre2_set_depth_limit.html create mode 100644 doc/pcre2_set_depth_limit.3 diff --git a/Makefile.am b/Makefile.am index c7e446e..a370db2 100644 --- a/Makefile.am +++ b/Makefile.am @@ -68,6 +68,7 @@ dist_html_DATA = \ doc/html/pcre2_set_callout.html \ doc/html/pcre2_set_character_tables.html \ doc/html/pcre2_set_compile_recursion_guard.html \ + doc/html/pcre2_set_depth_limit.html \ doc/html/pcre2_set_match_limit.html \ doc/html/pcre2_set_max_pattern_length.html \ doc/html/pcre2_set_offset_limit.html \ @@ -151,6 +152,7 @@ dist_man_MANS = \ doc/pcre2_set_callout.3 \ doc/pcre2_set_character_tables.3 \ doc/pcre2_set_compile_recursion_guard.3 \ + doc/pcre2_set_depth_limit.3 \ doc/pcre2_set_match_limit.3 \ doc/pcre2_set_max_pattern_length.3 \ doc/pcre2_set_offset_limit.3 \ diff --git a/doc/html/index.html b/doc/html/index.html index eebb80b..3920426 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -213,6 +213,9 @@ in the library. pcre2_set_compile_recursion_guard   Set up a compile recursion guard function +pcre2_set_depth_limit +   Set the match backtracking depth limit + pcre2_set_match_limit   Set the match limit @@ -229,10 +232,10 @@ in the library.   Set the parentheses nesting limit pcre2_set_recursion_limit -   Set the match recursion limit +   Obsolete: use pcre2_set_depth_limit pcre2_set_recursion_memory_management -   Set match recursion memory management +   Obsolete function that (from 10.30 onwards) does nothing pcre2_substitute   Match a compiled pattern to a subject string and do diff --git a/doc/html/pcre2_match_data_free.html b/doc/html/pcre2_match_data_free.html index 70e107e..840067f 100644 --- a/doc/html/pcre2_match_data_free.html +++ b/doc/html/pcre2_match_data_free.html @@ -26,8 +26,8 @@ DESCRIPTION

This function frees the memory occupied by a match data block, using the memory -freeing function from the general context with which it was created, or -free() if that was not set. +freeing function from the general context or compiled pattern with which it was +created, or free() if that was not set.

There is a complete description of the PCRE2 native API in the diff --git a/doc/html/pcre2_pattern_info.html b/doc/html/pcre2_pattern_info.html index b4cd6f5..fdda26b 100644 --- a/doc/html/pcre2_pattern_info.html +++ b/doc/html/pcre2_pattern_info.html @@ -41,27 +41,25 @@ request are as follows: PCRE2_BSR_UNICODE: Unicode line endings PCRE2_BSR_ANYCRLF: CR, LF, or CRLF only PCRE2_INFO_CAPTURECOUNT Number of capturing subpatterns + PCRE2_INFO_DEPTHLIMIT Backtracking depth limit if set, otherwise PCRE2_ERROR_UNSET PCRE2_INFO_FIRSTBITMAP Bitmap of first code units, or NULL PCRE2_INFO_FIRSTCODETYPE Type of start-of-match information 0 nothing set 1 first code unit is set 2 start of string or after newline PCRE2_INFO_FIRSTCODEUNIT First code unit when type is 1 + PCRE2_INFO_FRAMESIZE Size of backtracking frame PCRE2_INFO_HASBACKSLASHC Return 1 if pattern contains \C - PCRE2_INFO_HASCRORLF Return 1 if explicit CR or LF matches - exist in the pattern + PCRE2_INFO_HASCRORLF Return 1 if explicit CR or LF matches exist in the pattern PCRE2_INFO_JCHANGED Return 1 if (?J) or (?-J) was used PCRE2_INFO_JITSIZE Size of JIT compiled code, or 0 PCRE2_INFO_LASTCODETYPE Type of must-be-present information 0 nothing set 1 code unit is set PCRE2_INFO_LASTCODEUNIT Last code unit when type is 1 - PCRE2_INFO_MATCHEMPTY 1 if the pattern can match an - empty string, 0 otherwise - PCRE2_INFO_MATCHLIMIT Match limit if set, - otherwise PCRE2_ERROR_UNSET - PCRE2_INFO_MAXLOOKBEHIND Length (in characters) of the longest - lookbehind assertion + PCRE2_INFO_MATCHEMPTY 1 if the pattern can match an empty string, 0 otherwise + PCRE2_INFO_MATCHLIMIT Match limit if set, otherwise PCRE2_ERROR_UNSET + PCRE2_INFO_MAXLOOKBEHIND Length (in characters) of the longest lookbehind assertion PCRE2_INFO_MINLENGTH Lower bound length of matching strings PCRE2_INFO_NAMECOUNT Number of named subpatterns PCRE2_INFO_NAMEENTRYSIZE Size of name table entries @@ -72,8 +70,7 @@ request are as follows: PCRE2_NEWLINE_CRLF PCRE2_NEWLINE_ANY PCRE2_NEWLINE_ANYCRLF - PCRE2_INFO_RECURSIONLIMIT Recursion limit if set, - otherwise PCRE2_ERROR_UNSET + PCRE2_INFO_RECURSIONLIMIT Obsolete synonym for PCRE2_INFO_DEPTHLIMIT PCRE2_INFO_SIZE Size of compiled pattern If where is NULL, the function returns the amount of memory needed for diff --git a/doc/html/pcre2_set_callout.html b/doc/html/pcre2_set_callout.html index 635e0c2..4e7aca6 100644 --- a/doc/html/pcre2_set_callout.html +++ b/doc/html/pcre2_set_callout.html @@ -29,7 +29,7 @@ DESCRIPTION

This function sets the callout fields in a match context (the first argument). The second argument specifies a callout function, and the third argument is an -opaque data time that is passed to it. The result of this function is always +opaque data item that is passed to it. The result of this function is always zero.

diff --git a/doc/html/pcre2_set_depth_limit.html b/doc/html/pcre2_set_depth_limit.html new file mode 100644 index 0000000..a1cf706 --- /dev/null +++ b/doc/html/pcre2_set_depth_limit.html @@ -0,0 +1,40 @@ + + +pcre2_set_depth_limit specification + + +

pcre2_set_depth_limit man page

+

+Return to the PCRE2 index page. +

+

+This page is part of the PCRE2 HTML documentation. It was generated +automatically from the original man page. If there is any nonsense in it, +please consult the man page, in case the conversion went wrong. +
+
+SYNOPSIS +
+

+#include <pcre2.h> +

+

+int pcre2_set_depth_limit(pcre2_match_context *mcontext, + uint32_t value); +

+
+DESCRIPTION +
+

+This function sets the backtracking depth limit field in a match context. The +result is always zero. +

+

+There is a complete description of the PCRE2 native API in the +pcre2api +page and a description of the POSIX API in the +pcre2posix +page. +

+Return to the PCRE2 index page. +

diff --git a/doc/html/pcre2_set_recursion_limit.html b/doc/html/pcre2_set_recursion_limit.html index 5adcc99..c415aa3 100644 --- a/doc/html/pcre2_set_recursion_limit.html +++ b/doc/html/pcre2_set_recursion_limit.html @@ -26,8 +26,8 @@ SYNOPSIS DESCRIPTION

-This function sets the recursion limit field in a match context. The result is -always zero. +This function is obsolete and should not be used in new code. Use +pcre2_set_depth_limit() instead.

There is a complete description of the PCRE2 native API in the diff --git a/doc/html/pcre2_set_recursion_memory_management.html b/doc/html/pcre2_set_recursion_memory_management.html index ec18947..1e057b9 100644 --- a/doc/html/pcre2_set_recursion_memory_management.html +++ b/doc/html/pcre2_set_recursion_memory_management.html @@ -28,13 +28,8 @@ SYNOPSIS DESCRIPTION

-This function sets the match context fields for custom memory management when -PCRE2 is compiled to use the heap instead of the system stack for recursive -function calls while matching. When PCRE2 is compiled to use the stack (the -default) this function does nothing. The first argument is a match context, the -second and third specify the memory allocation and freeing functions, and the -final argument is an opaque value that is passed to them whenever they are -called. The result of this function is always zero. +From release 10.30 onwards, this function is obsolete and does nothing. The +result is always zero.

There is a complete description of the PCRE2 native API in the diff --git a/doc/html/pcre2test.html b/doc/html/pcre2test.html index 005df95..76dbae1 100644 --- a/doc/html/pcre2test.html +++ b/doc/html/pcre2test.html @@ -1377,11 +1377,15 @@ is added to the non-match message. Showing memory usage

-The memory modifier causes pcre2test to log all heap memory -allocation and freeing calls that occur during a call to pcre2_match(). -These occur only when a match requires a bigger vector than the default for -remembering backtracking points. In many cases there will be none. No heap -memory is allocated during matching with pcre2_dfa_match or with JIT. +The memory modifier causes pcre2test to log the sizes of all heap +memory allocation and freeing calls that occur during a call to +pcre2_match(). These occur only when a match requires a bigger vector +than the default for remembering backtracking points. In many cases there will +be no heap memory used and therefore no additional output. No heap memory is +allocated during matching with pcre2_dfa_match or with JIT, so in those +cases the memory modifier never has any effect. For this modifier to +work, the null_context modifier must not be set on both the pattern and +the subject, though it can be set on one or the other.


Setting a starting offset @@ -1794,7 +1798,7 @@ Cambridge, England.


REVISION

-Last updated: 24 March 2017 +Last updated: 25 March 2017
Copyright © 1997-2017 University of Cambridge.
diff --git a/doc/index.html.src b/doc/index.html.src index eebb80b..3920426 100644 --- a/doc/index.html.src +++ b/doc/index.html.src @@ -213,6 +213,9 @@ in the library. pcre2_set_compile_recursion_guard   Set up a compile recursion guard function +pcre2_set_depth_limit +   Set the match backtracking depth limit + pcre2_set_match_limit   Set the match limit @@ -229,10 +232,10 @@ in the library.   Set the parentheses nesting limit pcre2_set_recursion_limit -   Set the match recursion limit +   Obsolete: use pcre2_set_depth_limit pcre2_set_recursion_memory_management -   Set match recursion memory management +   Obsolete function that (from 10.30 onwards) does nothing pcre2_substitute   Match a compiled pattern to a subject string and do diff --git a/doc/pcre2_match_data_free.3 b/doc/pcre2_match_data_free.3 index 5e4bc62..e22074b 100644 --- a/doc/pcre2_match_data_free.3 +++ b/doc/pcre2_match_data_free.3 @@ -1,4 +1,4 @@ -.TH PCRE2_MATCH_DATA_FREE 3 "24 October 2014" "PCRE2 10.00" +.TH PCRE2_MATCH_DATA_FREE 3 "25 March 2017" "PCRE2 10.30" .SH NAME PCRE2 - Perl-compatible regular expressions (revised API) .SH SYNOPSIS @@ -14,8 +14,8 @@ PCRE2 - Perl-compatible regular expressions (revised API) .rs .sp This function frees the memory occupied by a match data block, using the memory -freeing function from the general context with which it was created, or -\fBfree()\fP if that was not set. +freeing function from the general context or compiled pattern with which it was +created, or \fBfree()\fP if that was not set. .P There is a complete description of the PCRE2 native API in the .\" HREF diff --git a/doc/pcre2_pattern_info.3 b/doc/pcre2_pattern_info.3 index 575840b..8e7e2f7 100644 --- a/doc/pcre2_pattern_info.3 +++ b/doc/pcre2_pattern_info.3 @@ -1,4 +1,4 @@ -.TH PCRE2_PATTERN_INFO 3 "21 November 2015" "PCRE2 10.21" +.TH PCRE2_PATTERN_INFO 3 "25 March 2017" "PCRE2 10.30" .SH NAME PCRE2 - Perl-compatible regular expressions (revised API) .SH SYNOPSIS @@ -29,13 +29,18 @@ request are as follows: PCRE2_BSR_UNICODE: Unicode line endings PCRE2_BSR_ANYCRLF: CR, LF, or CRLF only PCRE2_INFO_CAPTURECOUNT Number of capturing subpatterns +.\" JOIN + PCRE2_INFO_DEPTHLIMIT Backtracking depth limit if set, + otherwise PCRE2_ERROR_UNSET PCRE2_INFO_FIRSTBITMAP Bitmap of first code units, or NULL PCRE2_INFO_FIRSTCODETYPE Type of start-of-match information 0 nothing set 1 first code unit is set 2 start of string or after newline PCRE2_INFO_FIRSTCODEUNIT First code unit when type is 1 + PCRE2_INFO_FRAMESIZE Size of backtracking frame PCRE2_INFO_HASBACKSLASHC Return 1 if pattern contains \eC +.\" JOIN PCRE2_INFO_HASCRORLF Return 1 if explicit CR or LF matches exist in the pattern PCRE2_INFO_JCHANGED Return 1 if (?J) or (?-J) was used @@ -44,10 +49,13 @@ request are as follows: 0 nothing set 1 code unit is set PCRE2_INFO_LASTCODEUNIT Last code unit when type is 1 +.\" JOIN PCRE2_INFO_MATCHEMPTY 1 if the pattern can match an empty string, 0 otherwise +.\" JOIN PCRE2_INFO_MATCHLIMIT Match limit if set, otherwise PCRE2_ERROR_UNSET +.\" JOIN PCRE2_INFO_MAXLOOKBEHIND Length (in characters) of the longest lookbehind assertion PCRE2_INFO_MINLENGTH Lower bound length of matching strings @@ -60,8 +68,7 @@ request are as follows: PCRE2_NEWLINE_CRLF PCRE2_NEWLINE_ANY PCRE2_NEWLINE_ANYCRLF - PCRE2_INFO_RECURSIONLIMIT Recursion limit if set, - otherwise PCRE2_ERROR_UNSET + PCRE2_INFO_RECURSIONLIMIT Obsolete synonym for PCRE2_INFO_DEPTHLIMIT PCRE2_INFO_SIZE Size of compiled pattern .sp If \fIwhere\fP is NULL, the function returns the amount of memory needed for diff --git a/doc/pcre2_set_callout.3 b/doc/pcre2_set_callout.3 index 2f86f69..cb48e14 100644 --- a/doc/pcre2_set_callout.3 +++ b/doc/pcre2_set_callout.3 @@ -1,4 +1,4 @@ -.TH PCRE2_SET_CALLOUT 3 "24 October 2014" "PCRE2 10.00" +.TH PCRE2_SET_CALLOUT 3 "21 March 2017" "PCRE2 10.30" .SH NAME PCRE2 - Perl-compatible regular expressions (revised API) .SH SYNOPSIS @@ -17,7 +17,7 @@ PCRE2 - Perl-compatible regular expressions (revised API) .sp This function sets the callout fields in a match context (the first argument). The second argument specifies a callout function, and the third argument is an -opaque data time that is passed to it. The result of this function is always +opaque data item that is passed to it. The result of this function is always zero. .P There is a complete description of the PCRE2 native API in the diff --git a/doc/pcre2_set_depth_limit.3 b/doc/pcre2_set_depth_limit.3 new file mode 100644 index 0000000..62bc7fe --- /dev/null +++ b/doc/pcre2_set_depth_limit.3 @@ -0,0 +1,28 @@ +.TH PCRE2_SET_DEPTH_LIMIT 3 "25 March 2017" "PCRE2 10.30" +.SH NAME +PCRE2 - Perl-compatible regular expressions (revised API) +.SH SYNOPSIS +.rs +.sp +.B #include +.PP +.nf +.B int pcre2_set_depth_limit(pcre2_match_context *\fImcontext\fP, +.B " uint32_t \fIvalue\fP);" +.fi +. +.SH DESCRIPTION +.rs +.sp +This function sets the backtracking depth limit field in a match context. The +result is always zero. +.P +There is a complete description of the PCRE2 native API in the +.\" HREF +\fBpcre2api\fP +.\" +page and a description of the POSIX API in the +.\" HREF +\fBpcre2posix\fP +.\" +page. diff --git a/doc/pcre2_set_recursion_limit.3 b/doc/pcre2_set_recursion_limit.3 index ab1f3cd..1b74456 100644 --- a/doc/pcre2_set_recursion_limit.3 +++ b/doc/pcre2_set_recursion_limit.3 @@ -1,4 +1,4 @@ -.TH PCRE2_SET_RECURSION_LIMIT 3 "24 October 2014" "PCRE2 10.00" +.TH PCRE2_SET_RECURSION_LIMIT 3 "25 March 2017" "PCRE2 10.30" .SH NAME PCRE2 - Perl-compatible regular expressions (revised API) .SH SYNOPSIS @@ -14,8 +14,8 @@ PCRE2 - Perl-compatible regular expressions (revised API) .SH DESCRIPTION .rs .sp -This function sets the recursion limit field in a match context. The result is -always zero. +This function is obsolete and should not be used in new code. Use +\fBpcre2_set_depth_limit()\fP instead. .P There is a complete description of the PCRE2 native API in the .\" HREF diff --git a/doc/pcre2_set_recursion_memory_management.3 b/doc/pcre2_set_recursion_memory_management.3 index 9b5887a..12f175d 100644 --- a/doc/pcre2_set_recursion_memory_management.3 +++ b/doc/pcre2_set_recursion_memory_management.3 @@ -1,4 +1,4 @@ -.TH PCRE2_SET_RECURSION_MEMORY_MANAGEMENT 3 "24 October 2014" "PCRE2 10.00" +.TH PCRE2_SET_RECURSION_MEMORY_MANAGEMENT 3 "25 March 2017" "PCRE2 10.30" .SH NAME PCRE2 - Perl-compatible regular expressions (revised API) .SH SYNOPSIS @@ -16,13 +16,8 @@ PCRE2 - Perl-compatible regular expressions (revised API) .SH DESCRIPTION .rs .sp -This function sets the match context fields for custom memory management when -PCRE2 is compiled to use the heap instead of the system stack for recursive -function calls while matching. When PCRE2 is compiled to use the stack (the -default) this function does nothing. The first argument is a match context, the -second and third specify the memory allocation and freeing functions, and the -final argument is an opaque value that is passed to them whenever they are -called. The result of this function is always zero. +From release 10.30 onwards, this function is obsolete and does nothing. The +result is always zero. .P There is a complete description of the PCRE2 native API in the .\" HREF diff --git a/doc/pcre2test.txt b/doc/pcre2test.txt index 6ce7220..4169784 100644 --- a/doc/pcre2test.txt +++ b/doc/pcre2test.txt @@ -1234,12 +1234,16 @@ SUBJECT MODIFIERS Showing memory usage - The memory modifier causes pcre2test to log all heap memory allocation - and freeing calls that occur during a call to pcre2_match(). These - occur only when a match requires a bigger vector than the default for - remembering backtracking points. In many cases there will be none. No - heap memory is allocated during matching with pcre2_dfa_match or with - JIT. + The memory modifier causes pcre2test to log the sizes of all heap mem- + ory allocation and freeing calls that occur during a call to + pcre2_match(). These occur only when a match requires a bigger vector + than the default for remembering backtracking points. In many cases + there will be no heap memory used and therefore no additional output. + No heap memory is allocated during matching with pcre2_dfa_match or + with JIT, so in those cases the memory modifier never has any effect. + For this modifier to work, the null_context modifier must not be set on + both the pattern and the subject, though it can be set on one or the + other. Setting a starting offset @@ -1626,5 +1630,5 @@ AUTHOR REVISION - Last updated: 24 March 2017 + Last updated: 25 March 2017 Copyright (c) 1997-2017 University of Cambridge.