From 32bab50c0132c5a0ef0863500fbd4907d10b2056 Mon Sep 17 00:00:00 2001 From: "Philip.Hazel" Date: Thu, 23 Mar 2017 19:24:16 +0000 Subject: [PATCH] Documentation update. --- doc/pcre2.3 | 13 +++++++------ doc/pcre2_callout_enumerate.3 | 27 ++++++++++++++------------- doc/pcre2_code_free.3 | 6 ++++-- doc/pcre2_compile.3 | 31 +++++++++++++++++++------------ 4 files changed, 44 insertions(+), 33 deletions(-) diff --git a/doc/pcre2.3 b/doc/pcre2.3 index 9a84ce3..7444649 100644 --- a/doc/pcre2.3 +++ b/doc/pcre2.3 @@ -1,4 +1,4 @@ -.TH PCRE2 3 "16 October 2015" "PCRE2 10.21" +.TH PCRE2 3 "23 March 2017" "PCRE2 10.30" .SH NAME PCRE2 - Perl-compatible regular expressions (revised API) .SH INTRODUCTION @@ -104,7 +104,7 @@ lose performance. One way of guarding against this possibility is to use the \fBpcre2_pattern_info()\fP function to check the compiled pattern's options for PCRE2_UTF. Alternatively, you can set the PCRE2_NEVER_UTF option when calling -\fBpcre2_compile()\fP. This causes an compile time error if a pattern contains +\fBpcre2_compile()\fP. This causes a compile time error if the pattern contains a UTF-setting sequence. .P The use of Unicode properties for character types such as \ed can also be @@ -130,7 +130,8 @@ against this: see the \fBpcre2_set_match_limit()\fP function in the .\" HREF \fBpcre2api\fP .\" -page. +page. There is a similar function called \fBpcre2_set_depth_limit()\fP that can +be used to restrict the amount of memory that is used. . . .SH "USER DOCUMENTATION" @@ -163,7 +164,7 @@ listing), and the short pages for individual functions, are concatenated in pcre2perform discussion of performance issues pcre2posix the POSIX-compatible C API for the 8-bit library pcre2sample discussion of the pcre2demo program - pcre2stack discussion of stack usage + pcre2stack discussion of stack and memory usage pcre2syntax quick syntax reference pcre2test description of the \fBpcre2test\fP command pcre2unicode discussion of Unicode and UTF support @@ -189,6 +190,6 @@ use my two initials, followed by the two digits 10, at the domain cam.ac.uk. .rs .sp .nf -Last updated: 16 October 2015 -Copyright (c) 1997-2015 University of Cambridge. +Last updated: 27 March 2017 +Copyright (c) 1997-2017 University of Cambridge. .fi diff --git a/doc/pcre2_callout_enumerate.3 b/doc/pcre2_callout_enumerate.3 index 4573bb4..109c9be 100644 --- a/doc/pcre2_callout_enumerate.3 +++ b/doc/pcre2_callout_enumerate.3 @@ -1,4 +1,4 @@ -.TH PCRE2_COMPILE 3 "23 March 2015" "PCRE2 10.20" +.TH PCRE2_COMPILE 3 "23 March 2017" "PCRE2 10.30" .SH NAME PCRE2 - Perl-compatible regular expressions (revised API) .SH SYNOPSIS @@ -24,20 +24,21 @@ for success and non-zero otherwise. The arguments are: \fIcallout_data\fP User data that is passed to the callback .sp The \fIcallback()\fP function is passed a pointer to a data block containing -the following fields: +the following fields (not necessarily in this order): .sp - \fIversion\fP Block version number - \fIpattern_position\fP Offset to next item in pattern - \fInext_item_length\fP Length of next item in pattern - \fIcallout_number\fP Number for numbered callouts - \fIcallout_string_offset\fP Offset to string within pattern - \fIcallout_string_length\fP Length of callout string - \fIcallout_string\fP Points to callout string or is NULL + uint32_t \fIversion\fP Block version number + uint32_t \fIcallout_number\fP Number for numbered callouts + PCRE2_SIZE \fIpattern_position\fP Offset to next item in pattern + PCRE2_SIZE \fInext_item_length\fP Length of next item in pattern + PCRE2_SIZE \fIcallout_string_offset\fP Offset to string within pattern + PCRE2_SIZE \fIcallout_string_length\fP Length of callout string + PCRE2_SPTR \fIcallout_string\fP Points to callout string or is NULL .sp -The second argument is the callout data that was passed to -\fBpcre2_callout_enumerate()\fP. The \fBcallback()\fP function must return zero -for success. Any other value causes the pattern scan to stop, with the value -being passed back as the result of \fBpcre2_callout_enumerate()\fP. +The second argument passed to the \fBcallback()\fP function is the callout data +that was passed to \fBpcre2_callout_enumerate()\fP. The \fBcallback()\fP +function must return zero for success. Any other value causes the pattern scan +to stop, with the value being passed back as the result of +\fBpcre2_callout_enumerate()\fP. .P There is a complete description of the PCRE2 native API in the .\" HREF diff --git a/doc/pcre2_code_free.3 b/doc/pcre2_code_free.3 index 5127081..58a8b1c 100644 --- a/doc/pcre2_code_free.3 +++ b/doc/pcre2_code_free.3 @@ -1,4 +1,4 @@ -.TH PCRE2_CODE_FREE 3 "29 July 2015" "PCRE2 10.21" +.TH PCRE2_CODE_FREE 3 "23 March 2017" "PCRE2 10.30" .SH NAME PCRE2 - Perl-compatible regular expressions (revised API) .SH SYNOPSIS @@ -14,7 +14,9 @@ PCRE2 - Perl-compatible regular expressions (revised API) .rs .sp This function frees the memory used for a compiled pattern, including any -memory used by the JIT compiler. +memory used by the JIT compiler. If the compiled pattern was created by a call +to \fBpcre2_code_copy_with_tables()\fP, the memory for the character tables is +also freed. .P There is a complete description of the PCRE2 native API in the .\" HREF diff --git a/doc/pcre2_compile.3 b/doc/pcre2_compile.3 index 1e0dca5..9d9157f 100644 --- a/doc/pcre2_compile.3 +++ b/doc/pcre2_compile.3 @@ -1,4 +1,4 @@ -.TH PCRE2_COMPILE 3 "22 April 2015" "PCRE2 10.20" +.TH PCRE2_COMPILE 3 "23 March 2017" "PCRE2 10.30" .SH NAME PCRE2 - Perl-compatible regular expressions (revised API) .SH SYNOPSIS @@ -25,19 +25,24 @@ arguments are: \fIerroffset\fP Where to put an error offset \fIccontext\fP Pointer to a compile context or NULL .sp -The length of the string and any error offset that is returned are in code -units, not characters. A compile context is needed only if you want to change +The length of the pattern and any error offset that is returned are in code +units, not characters. A compile context is needed only if you want to provide +custom memory allocation functions, or to provide an external function for +system stack size checking, or to change one or more of these parameters: .sp - What \eR matches (Unicode newlines or CR, LF, CRLF only) - PCRE2's character tables - The newline character sequence - The compile time nested parentheses limit + What \eR matches (Unicode newlines, or CR, LF, CRLF only); + PCRE2's character tables; + The newline character sequence; + The compile time nested parentheses limit; + The maximum pattern length (in code units) that is allowed. .sp -or provide an external function for stack size checking. The option bits are: +The option bits are: .sp PCRE2_ANCHORED Force pattern anchoring + PCRE2_ALLOW_EMPTY_CLASS Allow empty classes PCRE2_ALT_BSUX Alternative handling of \eu, \eU, and \ex PCRE2_ALT_CIRCUMFLEX Alternative handling of ^ in multiline mode + PCRE2_ALT_VERBNAMES Process backslashes in verb names PCRE2_AUTO_CALLOUT Compile automatic callouts PCRE2_CASELESS Do caseless matching PCRE2_DOLLAR_ENDONLY $ not to match newline at end @@ -59,19 +64,21 @@ or provide an external function for stack size checking. The option bits are: (only relevant if PCRE2_UTF is set) PCRE2_UCP Use Unicode properties for \ed, \ew, etc. PCRE2_UNGREEDY Invert greediness of quantifiers + PCRE2_USE_OFFSET_LIMIT Enable offset limit for unanchored matching PCRE2_UTF Treat pattern and subjects as UTF strings .sp -PCRE2 must be built with Unicode support in order to use PCRE2_UTF, PCRE2_UCP -and related options. +PCRE2 must be built with Unicode support (the default) in order to use +PCRE2_UTF, PCRE2_UCP and related options. .P The yield of the function is a pointer to a private data structure that contains the compiled pattern, or NULL if an error was detected. .P -There is a complete description of the PCRE2 native API in the +There is a complete description of the PCRE2 native API, with more detail on +each option, in the .\" HREF \fBpcre2api\fP .\" -page and a description of the POSIX API in the +page, and a description of the POSIX API in the .\" HREF \fBpcre2posix\fP .\"