From 1fffb0d44e7a62ad290cf24586c78bc04b689144 Mon Sep 17 00:00:00 2001 From: Nicholas Wilson Date: Sat, 1 Feb 2025 15:50:20 +0000 Subject: [PATCH] Updates to the README and some documentation (#681) --- AUTHORS.md | 6 +- LICENCE.md | 2 - NON-AUTOTOOLS-BUILD | 35 +- README | 2 +- README.md | 37 +- SECURITY.md | 9 +- doc/html/NON-AUTOTOOLS-BUILD.txt | 35 +- doc/html/README.txt | 2 +- doc/html/index.html | 212 +-- doc/html/pcre2-config.html | 54 +- doc/html/pcre2.html | 82 +- doc/html/pcre2_callout_enumerate.html | 14 +- doc/html/pcre2_code_copy.html | 14 +- doc/html/pcre2_code_copy_with_tables.html | 14 +- doc/html/pcre2_code_free.html | 14 +- doc/html/pcre2_compile.html | 26 +- doc/html/pcre2_compile_context_copy.html | 14 +- doc/html/pcre2_compile_context_create.html | 14 +- doc/html/pcre2_compile_context_free.html | 14 +- doc/html/pcre2_config.html | 18 +- doc/html/pcre2_convert_context_copy.html | 14 +- doc/html/pcre2_convert_context_create.html | 14 +- doc/html/pcre2_convert_context_free.html | 14 +- doc/html/pcre2_converted_pattern_free.html | 14 +- doc/html/pcre2_dfa_match.html | 14 +- doc/html/pcre2_general_context_copy.html | 14 +- doc/html/pcre2_general_context_create.html | 14 +- doc/html/pcre2_general_context_free.html | 14 +- doc/html/pcre2_get_error_message.html | 14 +- doc/html/pcre2_get_mark.html | 18 +- .../pcre2_get_match_data_heapframes_size.html | 14 +- doc/html/pcre2_get_match_data_size.html | 14 +- doc/html/pcre2_get_ovector_count.html | 14 +- doc/html/pcre2_get_ovector_pointer.html | 14 +- doc/html/pcre2_get_startchar.html | 14 +- doc/html/pcre2_jit_compile.html | 26 +- doc/html/pcre2_jit_free_unused_memory.html | 14 +- doc/html/pcre2_jit_match.html | 30 +- doc/html/pcre2_jit_stack_assign.html | 36 +- doc/html/pcre2_jit_stack_create.html | 14 +- doc/html/pcre2_jit_stack_free.html | 14 +- doc/html/pcre2_maketables.html | 18 +- doc/html/pcre2_maketables_free.html | 18 +- doc/html/pcre2_match.html | 10 +- doc/html/pcre2_match_context_copy.html | 14 +- doc/html/pcre2_match_context_create.html | 14 +- doc/html/pcre2_match_context_free.html | 14 +- doc/html/pcre2_match_data_create.html | 18 +- .../pcre2_match_data_create_from_pattern.html | 18 +- doc/html/pcre2_match_data_free.html | 18 +- doc/html/pcre2_pattern_convert.html | 18 +- doc/html/pcre2_pattern_info.html | 16 +- doc/html/pcre2_serialize_decode.html | 14 +- doc/html/pcre2_serialize_encode.html | 14 +- doc/html/pcre2_serialize_free.html | 14 +- .../pcre2_serialize_get_number_of_codes.html | 14 +- doc/html/pcre2_set_bsr.html | 14 +- doc/html/pcre2_set_callout.html | 14 +- doc/html/pcre2_set_character_tables.html | 14 +- doc/html/pcre2_set_compile_extra_options.html | 10 +- .../pcre2_set_compile_recursion_guard.html | 14 +- doc/html/pcre2_set_depth_limit.html | 14 +- doc/html/pcre2_set_glob_escape.html | 14 +- doc/html/pcre2_set_glob_separator.html | 14 +- doc/html/pcre2_set_heap_limit.html | 14 +- doc/html/pcre2_set_match_limit.html | 14 +- ...pcre2_set_max_pattern_compiled_length.html | 14 +- doc/html/pcre2_set_max_pattern_length.html | 14 +- doc/html/pcre2_set_max_varlookbehind.html | 14 +- doc/html/pcre2_set_newline.html | 14 +- doc/html/pcre2_set_offset_limit.html | 14 +- doc/html/pcre2_set_optimize.html | 18 +- doc/html/pcre2_set_parens_nest_limit.html | 14 +- doc/html/pcre2_set_recursion_limit.html | 14 +- ...pcre2_set_recursion_memory_management.html | 14 +- doc/html/pcre2_set_substitute_callout.html | 14 +- .../pcre2_set_substitute_case_callout.html | 14 +- doc/html/pcre2_substitute.html | 26 +- doc/html/pcre2_substring_copy_byname.html | 14 +- doc/html/pcre2_substring_copy_bynumber.html | 16 +- doc/html/pcre2_substring_free.html | 14 +- doc/html/pcre2_substring_get_byname.html | 14 +- doc/html/pcre2_substring_get_bynumber.html | 16 +- doc/html/pcre2_substring_length_byname.html | 14 +- doc/html/pcre2_substring_length_bynumber.html | 14 +- doc/html/pcre2_substring_list_free.html | 14 +- doc/html/pcre2_substring_list_get.html | 14 +- doc/html/pcre2_substring_nametable_scan.html | 14 +- .../pcre2_substring_number_from_name.html | 14 +- doc/html/pcre2api.html | 1264 +++++++------- doc/html/pcre2build.html | 178 +- doc/html/pcre2callout.html | 162 +- doc/html/pcre2compat.html | 108 +- doc/html/pcre2convert.html | 78 +- doc/html/pcre2demo.html | 2 +- doc/html/pcre2grep.html | 418 ++--- doc/html/pcre2jit.html | 188 +-- doc/html/pcre2limits.html | 50 +- doc/html/pcre2matching.html | 126 +- doc/html/pcre2partial.html | 146 +- doc/html/pcre2pattern.html | 1450 ++++++++--------- doc/html/pcre2perform.html | 94 +- doc/html/pcre2posix.html | 130 +- doc/html/pcre2sample.html | 30 +- doc/html/pcre2serialize.html | 46 +- doc/html/pcre2syntax.html | 206 +-- doc/html/pcre2test.html | 712 ++++---- doc/html/pcre2unicode.html | 238 +-- doc/index.html.src | 212 +-- doc/pcre2.3 | 2 +- doc/pcre2.txt | 14 +- doc/pcre2compat.3 | 2 +- doc/pcre2pattern.3 | 2 +- index.md | 56 - maint/132html | 20 +- maint/PrepareRelease | 1 + maint/UpdateCommon.py | 5 +- 117 files changed, 3813 insertions(+), 3803 deletions(-) delete mode 100644 index.md diff --git a/AUTHORS.md b/AUTHORS.md index 708fc2325..37b54d116 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -1,14 +1,14 @@ PCRE2 Authorship and Contributors ================================= -COPYRIGHT +Copyright --------- Please see the file [LICENCE](./LICENCE.md) in the PCRE2 distribution for copyright details. -MAINTAINERS +Maintainers ----------- The PCRE and PCRE2 libraries were authored and maintained by Philip Hazel. @@ -62,7 +62,7 @@ Both administrators are volunteers acting in a personal capacity. -CONTRIBUTORS +Contributors ------------ Many others have participated and contributed to PCRE2 over its history. diff --git a/LICENCE.md b/LICENCE.md index 3a41fbada..7f1654b0d 100644 --- a/LICENCE.md +++ b/LICENCE.md @@ -99,5 +99,3 @@ not apply all the way down a chain of software. If binary package A includes PCRE2, it must respect the condition, but if package B is software that includes package A, the condition is not imposed on package B unless it uses PCRE2 independently. - -End diff --git a/NON-AUTOTOOLS-BUILD b/NON-AUTOTOOLS-BUILD index bb687f7d0..d60e42558 100644 --- a/NON-AUTOTOOLS-BUILD +++ b/NON-AUTOTOOLS-BUILD @@ -1,5 +1,5 @@ Building PCRE2 without using autotools --------------------------------------- +====================================== This document contains the following sections: @@ -16,7 +16,8 @@ This document contains the following sections: Building PCRE2 under VMS -GENERAL +General +------- The source of the PCRE2 libraries consists entirely of code written in Standard C, and so should compile successfully on any system that has a Standard C @@ -37,7 +38,8 @@ provided for those who build PCRE2 without using "configure" or CMake. If you use "configure" or CMake, the .generic versions are not used. -GENERIC INSTRUCTIONS FOR THE PCRE2 C LIBRARIES +Generic instructions for the PCRE2 C libraries +---------------------------------------------- There are three possible PCRE2 libraries, each handling data with a specific code unit width: 8, 16, or 32 bits. You can build any combination of them. The @@ -207,20 +209,23 @@ example. defining SUPPORT_JIT, pcre2grep does not try to make use of JIT. -STACK SIZE IN WINDOWS ENVIRONMENTS +Stack size in Windows environments +---------------------------------- Prior to release 10.30 the default system stack size of 1MiB in some Windows environments caused issues with some tests. This should no longer be the case for 10.30 and later releases. -LINKING PROGRAMS IN WINDOWS ENVIRONMENTS +Linking programs in Windows environments +---------------------------------------- If you want to statically link a program against a PCRE2 library in the form of a non-dll .a file, you must define PCRE2_STATIC before including src/pcre2.h. -CALLING CONVENTIONS IN WINDOWS ENVIRONMENTS +Calling conventions in Windows environments +------------------------------------------- It is possible to compile programs to use different calling conventions using MSVC. Search the web for "calling conventions" for more information. To make it @@ -231,7 +236,8 @@ not set, it defaults to empty; the default calling convention is then used (which is what is wanted most of the time). -COMMENTS ABOUT WIN32 BUILDS (see also "BUILDING PCRE2 ON WINDOWS WITH CMAKE") +Comments about Win32 builds (see also "Building PCRE2 on Windows with CMake") +--------------------------- There are two ways of building PCRE2 using the "configure, make, make install" paradigm on Windows systems: using MinGW or using Cygwin. These are not at all @@ -293,7 +299,8 @@ newline option that includes LF as a valid newline, it may be necessary to change the line terminators in the test files to get some of the tests to work. -BUILDING PCRE2 ON WINDOWS WITH CMAKE +Building PCRE2 on Windows with CMake +------------------------------------ CMake is an alternative configuration facility that can be used instead of "configure". CMake creates project files (make files, solution files, etc.) @@ -364,7 +371,8 @@ be deleted. Regardless of build system used, `ctest` will run the tests. -BUILDING PCRE2 ON WINDOWS WITH VISUAL STUDIO +Building PCRE2 on Windows with Visual Studio +-------------------------------------------- The code currently cannot be compiled without an inttypes.h header, which is available only with Visual Studio 2013 or newer. However, this portable and @@ -376,7 +384,8 @@ alternative: Just rename it and drop it into the top level of the build tree. -TESTING WITH RUNTEST.BAT +Testing with RunTest.bat +------------------------ If configured with CMake, building the test project ("make test" or building ALL_TESTS in Visual Studio) creates (and runs) pcre2_test.bat (and depending @@ -410,7 +419,8 @@ Otherwise: To independently test the just-in-time compiler, run pcre2_jit_test.exe. -BUILDING PCRE2 ON NATIVE Z/OS AND Z/VM +Building PCRE2 on native z/OS and z/VM +-------------------------------------- z/OS and z/VM are operating systems for mainframe computers, produced by IBM. The character code used is EBCDIC, not ASCII or Unicode. In z/OS, UNIX APIs and @@ -429,7 +439,8 @@ z/OS file formats. The port provides an API for LE languages such as COBOL and for the z/OS and z/VM versions of the Rexx languages. -BUILDING PCRE2 UNDER VMS +Building PCRE2 under VMS +------------------------ Alexey Chuphin has contributed some auxiliary files for building PCRE2 under OpenVMS. They are in the "vms" directory in the distribution tarball. Please diff --git a/README b/README index 94cdd9fef..89a862d53 100644 --- a/README +++ b/README @@ -1,5 +1,5 @@ README file for PCRE2 (Perl-compatible regular expression library) ------------------------------------------------------------------- +================================================================== PCRE2 is a re-working of the original PCRE1 library to provide an entirely new API. Since its initial release in 2015, there has been further development of diff --git a/README.md b/README.md index 2f85ed65a..aa9bb5702 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ - - PCRE2: Perl-Compatible Regular Expressions + + PCRE2: Perl-Compatible Regular Expressions ## Overview @@ -64,7 +64,7 @@ x86, ARM, RISC-V, POWER, S390X; many others known to work - + Recording of a terminal session showing the PCRE2 quickstart; reproduced in text form below
@@ -86,12 +86,20 @@ git clone https://github.com/PCRE2Project/pcre2.git ./pcre2 \ # Here's a quick little demo to show how we can make use of PCRE2. # For a fuller example, see './pcre2/src/pcre2demo.c'. -# Try this pre-prepared sample code: -cat demo.c +# See below for the demo code. ----------------------------------------------------------------------- -File: demo.c ----------------------------------------------------------------------- +# Compile the demo: +gcc -g -I./pcre2/build -L./pcre2/build demo.c -o demo -lpcre2-8 + +# Finally, run our demo: +./demo 'c.t' 'dogs and cats' + +# We fetched, built, and called PCRE2 successfully! :) +``` + +File `demo.c`: + +```c /* Set PCRE2_CODE_UNIT_WIDTH to indicate we will use 8-bit input. */ #define PCRE2_CODE_UNIT_WIDTH 8 #include @@ -150,15 +158,6 @@ int main(int argc, char* argv[]) { pcre2_code_free(re); return 0; } ----------------------------------------------------------------------- - -# Compile the demo: -gcc -g -I./pcre2/build -L./pcre2/build demo.c -o demo -lpcre2-8 - -# Finally, run our demo: -./demo 'c.t' 'dogs and cats' - -# We fetched, built, and called PCRE2 successfully! :) ```
@@ -213,7 +212,7 @@ There are accompanying utility functions for converting glob patterns and POSIX As well as the PCRE2 API, the library also offers a POSIX-compatible `` header and `regexec()` function. However, this does not provide the ability to pass PCRE2 flags, so we recommend users consume the PCRE2 API if possible. -See the [full library and API documentation](https://pcre2project.github.io/pcre2/doc/html/index.html) for further details. +See the [full library and API documentation](https://pcre2project.github.io/pcre2/doc/) for further details. For third-party documentation, see further: @@ -241,7 +240,7 @@ Other systems are likely to work (including mobile, embedded platforms, and comm PCRE2 releases support CMake for building, and for UNIX platforms include a `./configure` script built by Autoconf. Build files for the Bazel build system and `zig build` are also included. Integrating PCRE2 with other systems can be done by including the `.c` files in an existing project. -Please see the files [README](./README) and [NON-AUTOTOOLS-BUILD](./NON-AUTOTOOLS-BUILD) for full build documentation, as well as the man pages, including [`man pcre2/doc/pcre2build.3`](https://pcre2project.github.io/pcre2/doc/html/pcre2build.html). +Please see the files [README](./README) and [NON-AUTOTOOLS-BUILD](./NON-AUTOTOOLS-BUILD) for full build documentation, as well as the man pages, including [`man pcre2/doc/pcre2build.3`](https://pcre2project.github.io/pcre2/doc/pcre2build/). ## Licence diff --git a/SECURITY.md b/SECURITY.md index 1e3a05b9a..6e81dca16 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,8 @@ -# Security policies +Security policies +================= -## Release security +Release security +---------------- The PCRE2 project provides source-only releases, with no binaries. @@ -20,7 +22,8 @@ Git checkout of the (GPG-signed) release tag. Please contact the maintainers for any queries about release integrity or the project's supply-chain. -## Reporting vulnerabilities +Reporting vulnerabilities +------------------------- The PCRE2 project prioritises security. We appreciate third-party testing and security research, and would be grateful if you could responsibly disclose your diff --git a/doc/html/NON-AUTOTOOLS-BUILD.txt b/doc/html/NON-AUTOTOOLS-BUILD.txt index bb687f7d0..d60e42558 100644 --- a/doc/html/NON-AUTOTOOLS-BUILD.txt +++ b/doc/html/NON-AUTOTOOLS-BUILD.txt @@ -1,5 +1,5 @@ Building PCRE2 without using autotools --------------------------------------- +====================================== This document contains the following sections: @@ -16,7 +16,8 @@ This document contains the following sections: Building PCRE2 under VMS -GENERAL +General +------- The source of the PCRE2 libraries consists entirely of code written in Standard C, and so should compile successfully on any system that has a Standard C @@ -37,7 +38,8 @@ provided for those who build PCRE2 without using "configure" or CMake. If you use "configure" or CMake, the .generic versions are not used. -GENERIC INSTRUCTIONS FOR THE PCRE2 C LIBRARIES +Generic instructions for the PCRE2 C libraries +---------------------------------------------- There are three possible PCRE2 libraries, each handling data with a specific code unit width: 8, 16, or 32 bits. You can build any combination of them. The @@ -207,20 +209,23 @@ example. defining SUPPORT_JIT, pcre2grep does not try to make use of JIT. -STACK SIZE IN WINDOWS ENVIRONMENTS +Stack size in Windows environments +---------------------------------- Prior to release 10.30 the default system stack size of 1MiB in some Windows environments caused issues with some tests. This should no longer be the case for 10.30 and later releases. -LINKING PROGRAMS IN WINDOWS ENVIRONMENTS +Linking programs in Windows environments +---------------------------------------- If you want to statically link a program against a PCRE2 library in the form of a non-dll .a file, you must define PCRE2_STATIC before including src/pcre2.h. -CALLING CONVENTIONS IN WINDOWS ENVIRONMENTS +Calling conventions in Windows environments +------------------------------------------- It is possible to compile programs to use different calling conventions using MSVC. Search the web for "calling conventions" for more information. To make it @@ -231,7 +236,8 @@ not set, it defaults to empty; the default calling convention is then used (which is what is wanted most of the time). -COMMENTS ABOUT WIN32 BUILDS (see also "BUILDING PCRE2 ON WINDOWS WITH CMAKE") +Comments about Win32 builds (see also "Building PCRE2 on Windows with CMake") +--------------------------- There are two ways of building PCRE2 using the "configure, make, make install" paradigm on Windows systems: using MinGW or using Cygwin. These are not at all @@ -293,7 +299,8 @@ newline option that includes LF as a valid newline, it may be necessary to change the line terminators in the test files to get some of the tests to work. -BUILDING PCRE2 ON WINDOWS WITH CMAKE +Building PCRE2 on Windows with CMake +------------------------------------ CMake is an alternative configuration facility that can be used instead of "configure". CMake creates project files (make files, solution files, etc.) @@ -364,7 +371,8 @@ be deleted. Regardless of build system used, `ctest` will run the tests. -BUILDING PCRE2 ON WINDOWS WITH VISUAL STUDIO +Building PCRE2 on Windows with Visual Studio +-------------------------------------------- The code currently cannot be compiled without an inttypes.h header, which is available only with Visual Studio 2013 or newer. However, this portable and @@ -376,7 +384,8 @@ alternative: Just rename it and drop it into the top level of the build tree. -TESTING WITH RUNTEST.BAT +Testing with RunTest.bat +------------------------ If configured with CMake, building the test project ("make test" or building ALL_TESTS in Visual Studio) creates (and runs) pcre2_test.bat (and depending @@ -410,7 +419,8 @@ Otherwise: To independently test the just-in-time compiler, run pcre2_jit_test.exe. -BUILDING PCRE2 ON NATIVE Z/OS AND Z/VM +Building PCRE2 on native z/OS and z/VM +-------------------------------------- z/OS and z/VM are operating systems for mainframe computers, produced by IBM. The character code used is EBCDIC, not ASCII or Unicode. In z/OS, UNIX APIs and @@ -429,7 +439,8 @@ z/OS file formats. The port provides an API for LE languages such as COBOL and for the z/OS and z/VM versions of the Rexx languages. -BUILDING PCRE2 UNDER VMS +Building PCRE2 under VMS +------------------------ Alexey Chuphin has contributed some auxiliary files for building PCRE2 under OpenVMS. They are in the "vms" directory in the distribution tarball. Please diff --git a/doc/html/README.txt b/doc/html/README.txt index 94cdd9fef..89a862d53 100644 --- a/doc/html/README.txt +++ b/doc/html/README.txt @@ -1,5 +1,5 @@ README file for PCRE2 (Perl-compatible regular expression library) ------------------------------------------------------------------- +================================================================== PCRE2 is a re-working of the original PCRE1 library to provide an entirely new API. Since its initial release in 2015, there has been further development of diff --git a/doc/html/index.html b/doc/html/index.html index 2d81b678f..43b0d595b 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -7,6 +7,22 @@ --> PCRE2 specification +

Perl-compatible Regular Expressions (revised API: PCRE2)

@@ -18,67 +34,67 @@

Perl-compatible Regular Expressions (revised API: PCRE2)

- + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - +
pcre2  Introductory page
Introductory page
pcre2-config  Information about the installation configuration
Information about the installation configuration
pcre2api  PCRE2's native API
PCRE2's native API
pcre2build  Building PCRE2
Building PCRE2
pcre2callout  The callout facility
The callout facility
pcre2compat  Compability with Perl
Compability with Perl
pcre2convert  Experimental foreign pattern conversion functions
Experimental foreign pattern conversion functions
pcre2demo  A demonstration C program that uses the PCRE2 library
A demonstration C program that uses the PCRE2 library
pcre2grep  The pcre2grep command
The pcre2grep command
pcre2jit  Discussion of the just-in-time optimization support
Discussion of the just-in-time optimization support
pcre2limits  Details of size and other limits
Details of size and other limits
pcre2matching  Discussion of the two matching algorithms
Discussion of the two matching algorithms
pcre2partial  Using PCRE2 for partial matching
Using PCRE2 for partial matching
pcre2pattern  Specification of the regular expressions supported by PCRE2
Specification of the regular expressions supported by PCRE2
pcre2perform  Some comments on performance
Some comments on performance
pcre2posix  The POSIX API to the PCRE2 8-bit library
The POSIX API to the PCRE2 8-bit library
pcre2sample  Discussion of the pcre2demo program
Discussion of the pcre2demo program
pcre2serialize  Serializing functions for saving precompiled patterns
Serializing functions for saving precompiled patterns
pcre2syntax  Syntax quick-reference summary
Syntax quick-reference summary
pcre2test  The pcre2test command for testing PCRE2
The pcre2test command for testing PCRE2
pcre2unicode  Discussion of Unicode and UTF-8/UTF-16/UTF-32 support
Discussion of Unicode and UTF-8/UTF-16/UTF-32 support

@@ -89,238 +105,238 @@

Perl-compatible Regular Expressions (revised API: PCRE2)

- + - + - + - + - + - + - + - + - + - + - + - + - + - - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - + - + - + - + - + - + - + - + - + - + - +
pcre2_callout_enumerate  Enumerate callouts in a compiled pattern
Enumerate callouts in a compiled pattern
pcre2_code_copy  Copy a compiled pattern
Copy a compiled pattern
pcre2_code_copy_with_tables  Copy a compiled pattern and its character tables
Copy a compiled pattern and its character tables
pcre2_code_free  Free a compiled pattern
Free a compiled pattern
pcre2_compile  Compile a regular expression pattern
Compile a regular expression pattern
pcre2_compile_context_copy  Copy a compile context
Copy a compile context
pcre2_compile_context_create  Create a compile context
Create a compile context
pcre2_compile_context_free  Free a compile context
Free a compile context
pcre2_config  Show build-time configuration options
Show build-time configuration options
pcre2_convert_context_copy  Copy a convert context
Copy a convert context
pcre2_convert_context_create  Create a convert context
Create a convert context
pcre2_convert_context_free  Free a convert context
Free a convert context
pcre2_converted_pattern_free  Free converted foreign pattern
Free converted foreign pattern
pcre2_dfa_match  Match a compiled pattern to a subject string + Match a compiled pattern to a subject string (DFA algorithm; not Perl compatible)
pcre2_general_context_copy  Copy a general context
Copy a general context
pcre2_general_context_create  Create a general context
Create a general context
pcre2_general_context_free  Free a general context
Free a general context
pcre2_get_error_message  Get textual error message for error number
Get textual error message for error number
pcre2_get_mark  Get a (*MARK) name
Get a (*MARK) name
pcre2_get_match_data_size  Get the size of a match data block
Get the size of a match data block
pcre2_get_ovector_count  Get the ovector count
Get the ovector count
pcre2_get_ovector_pointer  Get a pointer to the ovector
Get a pointer to the ovector
pcre2_get_startchar  Get the starting character offset
Get the starting character offset
pcre2_jit_compile  Process a compiled pattern with the JIT compiler
Process a compiled pattern with the JIT compiler
pcre2_jit_free_unused_memory  Free unused JIT memory
Free unused JIT memory
pcre2_jit_match  Fast path interface to JIT matching
Fast path interface to JIT matching
pcre2_jit_stack_assign  Assign stack for JIT matching
Assign stack for JIT matching
pcre2_jit_stack_create  Create a stack for JIT matching
Create a stack for JIT matching
pcre2_jit_stack_free  Free a JIT matching stack
Free a JIT matching stack
pcre2_maketables  Build character tables in current locale
Build character tables in current locale
pcre2_maketables_free  Free character tables
Free character tables
pcre2_match  Match a compiled pattern to a subject string + Match a compiled pattern to a subject string (Perl compatible)
pcre2_match_context_copy  Copy a match context
Copy a match context
pcre2_match_context_create  Create a match context
Create a match context
pcre2_match_context_free  Free a match context
Free a match context
pcre2_match_data_create  Create a match data block
Create a match data block
pcre2_match_data_create_from_pattern  Create a match data block getting size from pattern
Create a match data block getting size from pattern
pcre2_match_data_free  Free a match data block
Free a match data block
pcre2_pattern_convert  Experimental foreign pattern converter
Experimental foreign pattern converter
pcre2_pattern_info  Extract information about a pattern
Extract information about a pattern
pcre2_serialize_decode  Decode serialized compiled patterns
Decode serialized compiled patterns
pcre2_serialize_encode  Serialize compiled patterns for save/restore
Serialize compiled patterns for save/restore
pcre2_serialize_free  Free serialized compiled patterns
Free serialized compiled patterns
pcre2_serialize_get_number_of_codes  Get number of serialized compiled patterns
Get number of serialized compiled patterns
pcre2_set_bsr  Set \R convention
Set \R convention
pcre2_set_callout  Set up a callout function
Set up a callout function
pcre2_set_character_tables  Set character tables
Set character tables
pcre2_set_compile_extra_options  Set compile time extra options
Set compile time extra options
pcre2_set_compile_recursion_guard  Set up a compile recursion guard function
Set up a compile recursion guard function
pcre2_set_depth_limit  Set the match backtracking depth limit
Set the match backtracking depth limit
pcre2_set_glob_escape  Set glob escape character
Set glob escape character
pcre2_set_glob_separator  Set glob separator character
Set glob separator character
pcre2_set_heap_limit  Set the match backtracking heap limit
Set the match backtracking heap limit
pcre2_set_match_limit  Set the match limit
Set the match limit
pcre2_set_max_pattern_compiled_length  Set the maximum length of a compiled pattern
Set the maximum length of a compiled pattern
pcre2_set_max_pattern_length  Set the maximum length of a pattern
Set the maximum length of a pattern
pcre2_set_max_varlookbehind  Set the maximum match length for a variable-length lookbehind
Set the maximum match length for a variable-length lookbehind
pcre2_set_newline  Set the newline convention
Set the newline convention
pcre2_set_offset_limit  Set the offset limit
Set the offset limit
pcre2_set_optimize  Set an optimization directive
Set an optimization directive
pcre2_set_parens_nest_limit  Set the parentheses nesting limit
Set the parentheses nesting limit
pcre2_set_recursion_limit  Obsolete: use pcre2_set_depth_limit
Obsolete: use pcre2_set_depth_limit
pcre2_set_recursion_memory_management  Obsolete function that (from 10.30 onwards) does nothing
Obsolete function that (from 10.30 onwards) does nothing
pcre2_set_substitute_callout  Set a substitution callout function
Set a substitution callout function
pcre2_set_substitute_case_callout  Set a substitution case callout function
Set a substitution case callout function
pcre2_substitute  Match a compiled pattern to a subject string and do + Match a compiled pattern to a subject string and do substitutions
pcre2_substring_copy_byname  Extract named substring into given buffer
Extract named substring into given buffer
pcre2_substring_copy_bynumber  Extract numbered substring into given buffer
Extract numbered substring into given buffer
pcre2_substring_free  Free extracted substring
Free extracted substring
pcre2_substring_get_byname  Extract named substring into new memory
Extract named substring into new memory
pcre2_substring_get_bynumber  Extract numbered substring into new memory
Extract numbered substring into new memory
pcre2_substring_length_byname  Find length of named substring
Find length of named substring
pcre2_substring_length_bynumber  Find length of numbered substring
Find length of numbered substring
pcre2_substring_list_free  Free list of extracted substrings
Free list of extracted substrings
pcre2_substring_list_get  Extract all substrings into new memory
Extract all substrings into new memory
pcre2_substring_nametable_scan  Find table entries for given string name
Find table entries for given string name
pcre2_substring_number_from_name  Convert captured string name to number
Convert captured string name to number
diff --git a/doc/html/pcre2-config.html b/doc/html/pcre2-config.html index b71d76026..b869f0b06 100644 --- a/doc/html/pcre2-config.html +++ b/doc/html/pcre2-config.html @@ -21,80 +21,80 @@

pcre2-config man page

  • REVISION
    SYNOPSIS
    -

    +

    pcre2-config [--prefix] [--exec-prefix] [--version] [--libs8] [--libs16] [--libs32] [--libs-posix] [--cflags] [--cflags-posix] -

    +


    DESCRIPTION
    -

    +

    pcre2-config returns the configuration of the installed PCRE2 libraries and the options required to compile a program to use them. Some of the options apply only to the 8-bit, or 16-bit, or 32-bit libraries, respectively, and are not available for libraries that have not been built. If an unavailable option is encountered, the "usage" information is output. -

    +


    OPTIONS
    -

    +

    --prefix Writes the directory prefix used in the PCRE2 installation for architecture independent files (/usr on many systems, /usr/local on some systems) to the standard output. -

    -

    +

    +

    --exec-prefix Writes the directory prefix used in the PCRE2 installation for architecture dependent files (normally the same as --prefix) to the standard output. -

    -

    +

    +

    --version Writes the version number of the installed PCRE2 libraries to the standard output. -

    -

    +

    +

    --libs8 Writes to the standard output the command line options required to link with the 8-bit PCRE2 library (-lpcre2-8 on many systems). -

    -

    +

    +

    --libs16 Writes to the standard output the command line options required to link with the 16-bit PCRE2 library (-lpcre2-16 on many systems). -

    -

    +

    +

    --libs32 Writes to the standard output the command line options required to link with the 32-bit PCRE2 library (-lpcre2-32 on many systems). -

    -

    +

    +

    --libs-posix Writes to the standard output the command line options required to link with PCRE2's POSIX API wrapper library (-lpcre2-posix -lpcre2-8 on many systems). -

    -

    +

    +

    --cflags Writes to the standard output the command line options required to compile files that use PCRE2 (this may include some -I options, but is blank on many systems). -

    -

    +

    +

    --cflags-posix Writes to the standard output the command line options required to compile files that use PCRE2's POSIX API wrapper library (this may include some -I options, but is blank on many systems). -

    +


    SEE ALSO
    -

    +

    pcre2(3) -

    +


    AUTHOR
    -

    +

    This manual page was originally written by Mark Baker for the Debian GNU/Linux system. It has been subsequently revised as a generic PCRE2 man page. -

    +


    REVISION
    -

    +

    Last updated: 28 September 2014

    diff --git a/doc/html/pcre2.html b/doc/html/pcre2.html index e72b6b1cb..3b6f9d465 100644 --- a/doc/html/pcre2.html +++ b/doc/html/pcre2.html @@ -20,7 +20,7 @@

    pcre2 man page

  • REVISION
    INTRODUCTION
    -

    +

    PCRE2 is the name used for a revised API for the PCRE library, which is a set of functions, written in C, that implement regular expression pattern matching using the same syntax and semantics as Perl, with just a few differences. After @@ -30,23 +30,23 @@

    pcre2 man page

    automatically optimized where possible. Since forking from PCRE1, the code has been extensively refactored and new features introduced. The old library is now obsolete and is no longer maintained. -

    -

    +

    +

    As well as Perl-style regular expression patterns, some features that appeared in Python and the original PCRE before they appeared in Perl are available using the Python syntax. There is also some support for one or two .NET and Oniguruma syntax items, and there are options for requesting some minor changes that give better ECMAScript (aka JavaScript) compatibility. -

    -

    +

    +

    The source code for PCRE2 can be compiled to support strings of 8-bit, 16-bit, or 32-bit code units, which means that up to three separate libraries may be installed, one for each code unit size. The size of code unit is not related to the bit size of the underlying hardware. In a 64-bit environment that also supports 32-bit applications, versions of PCRE2 that are compiled in both 64-bit and 32-bit modes may be needed. -

    -

    +

    +

    The original work to extend PCRE to 16-bit and 32-bit code units was done by Zoltan Herczeg and Christian Persch, respectively. In all three cases, strings can be interpreted either as one character per code unit, or as UTF-encoded @@ -56,25 +56,25 @@

    pcre2 man page

    in use can be discovered by running 
       pcre2test -C
-
    -

    -

    + +

    +

    The three libraries contain identical sets of functions, with names ending in _8, _16, or _32, respectively (for example, pcre2_compile_8()). However, by defining PCRE2_CODE_UNIT_WIDTH to be 8, 16, or 32, a program that uses just one code unit width can be written using generic names such as pcre2_compile(), and the documentation is written assuming that this is the case. -

    -

    +

    +

    In addition to the Perl-compatible matching function, PCRE2 contains an alternative function that matches the same compiled patterns in a different way. In certain circumstances, the alternative function has some advantages. For a discussion of the two matching algorithms, see the pcre2matching page. -

    -

    +

    +

    Details of exactly which Perl regular expression features are and are not supported by PCRE2 are given in separate documents. See the pcre2pattern @@ -83,8 +83,8 @@

    pcre2 man page

    pages. There is a syntax summary in the pcre2syntax page. -

    -

    +

    +

    Some features of PCRE2 can be included, excluded, or changed when the library is built. The pcre2_config() @@ -95,10 +95,10 @@

    pcre2 man page

    found in the README and -NON-AUTOTOOLS_BUILD +NON-AUTOTOOLS-BUILD files in the source distribution. -

    -

    +

    +

    The libraries contains a number of undocumented internal functions and data tables that are used by more than one of the exported external functions, but which are not intended for use by external callers. Their names all begin with @@ -106,9 +106,9 @@

    pcre2 man page

    environments, it is possible to control which external symbols are exported when a shared library is built, and in these cases the undocumented symbols are not exported. -

    +


    SECURITY CONSIDERATIONS
    -

    +

    If you are using PCRE2 in a non-UTF application that permits users to supply arbitrary patterns for compilation, you should be aware of a feature that allows users to turn on UTF support from within a pattern. For example, an @@ -118,34 +118,34 @@

    pcre2 man page

    matched to be checked for UTF-8 validity. If the data string is very long, such a check might use sufficiently many resources as to cause your application to lose performance. -

    -

    +

    +

    One way of guarding against this possibility is to use the pcre2_pattern_info() function to check the compiled pattern's options for PCRE2_UTF. Alternatively, you can set the PCRE2_NEVER_UTF option when calling pcre2_compile(). This causes a compile time error if the pattern contains a UTF-setting sequence. -

    -

    +

    +

    The use of Unicode properties for character types such as \d can also be enabled from within the pattern, by specifying "(*UCP)". This feature can be disallowed by setting the PCRE2_NEVER_UCP option. -

    -

    +

    +

    If your application is one that supports UTF, be aware that validity checking can take time. If the same data string is to be matched many times, you can use the PCRE2_NO_UTF_CHECK option for the second and subsequent matches to avoid running redundant checks. -

    -

    +

    +

    The use of the \C escape sequence in a UTF-8 or UTF-16 pattern can lead to problems, because it may leave the current matching point in the middle of a multi-code-unit character. The PCRE2_NEVER_BACKSLASH_C option can be used by an application to lock out the use of \C, causing a compile-time error if it is encountered. It is also possible to build PCRE2 with the use of \C permanently disabled. -

    -

    +

    +

    Another way that performance can be hit is by running a pattern that has a very large search tree against a string that will never match. Nested unlimited repeats in a pattern are a common example. PCRE2 provides some protection @@ -153,9 +153,9 @@

    pcre2 man page

    pcre2api page. There is a similar function called pcre2_set_depth_limit() that can be used to restrict the amount of memory that is used. -

    +


    USER DOCUMENTATION
    -

    +

    The user documentation for PCRE2 comprises a number of different sections. In the "man" format, each of these is a separate "man page". In the HTML format, each is a separate page, linked from the index page. In the plain text format, @@ -189,22 +189,22 @@

    pcre2 man page

    In the "man" and HTML formats, there is also a short page for each C library function, listing its arguments and results. -

    +


    AUTHORS
    -

    +

    The current maintainers of PCRE2 are Nicholas Wilson and Zoltan Herczeg. -

    -

    +

    +

    PCRE2 was written by Philip Hazel, of the University Computing Service, Cambridge, England. Many others have also contributed. -

    -

    +

    +

    To contact the maintainers, please use the GitHub issues tracker or PCRE2 mailing list, as described at the project page: https://github.com/PCRE2Project/pcre2 -

    +


    REVISION
    -

    +

    Last updated: 18 December 2024
    Copyright © 1997-2021 University of Cambridge. diff --git a/doc/html/pcre2_callout_enumerate.html b/doc/html/pcre2_callout_enumerate.html index 505ea7b25..08032f6f8 100644 --- a/doc/html/pcre2_callout_enumerate.html +++ b/doc/html/pcre2_callout_enumerate.html @@ -15,18 +15,18 @@

    pcre2_callout_enumerate man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_callout_enumerate(const pcre2_code *code, int (*callback)(pcre2_callout_enumerate_block *, void *), void *callout_data); -

    +


    DESCRIPTION
    -

    +

    This function scans a compiled regular expression and calls the callback() function for each callout within the pattern. The yield of the function is zero for success and non-zero otherwise. The arguments are: @@ -51,8 +51,8 @@

    pcre2_callout_enumerate man page

    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 pcre2_callout_enumerate(). -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_code_copy.html b/doc/html/pcre2_code_copy.html index 667d7b7ff..d4b1c075a 100644 --- a/doc/html/pcre2_code_copy.html +++ b/doc/html/pcre2_code_copy.html @@ -15,24 +15,24 @@

    pcre2_code_copy man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_code *pcre2_code_copy(const pcre2_code *code); -

    +


    DESCRIPTION
    -

    +

    This function makes a copy of the memory used for a compiled pattern, excluding any memory used by the JIT compiler. Without a subsequent call to pcre2_jit_compile(), the copy can be used only for non-JIT matching. The pointer to the character tables is copied, not the tables themselves (see pcre2_code_copy_with_tables()). The yield of the function is NULL if code is NULL or if sufficient memory cannot be obtained. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_code_copy_with_tables.html b/doc/html/pcre2_code_copy_with_tables.html index 67b2e1ffd..ea13c2998 100644 --- a/doc/html/pcre2_code_copy_with_tables.html +++ b/doc/html/pcre2_code_copy_with_tables.html @@ -15,16 +15,16 @@

    pcre2_code_copy_with_tables man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_code *pcre2_code_copy_with_tables(const pcre2_code *code); -

    +


    DESCRIPTION
    -

    +

    This function makes a copy of the memory used for a compiled pattern, excluding any memory used by the JIT compiler. Without a subsequent call to pcre2_jit_compile(), the copy can be used only for non-JIT matching. @@ -32,8 +32,8 @@

    pcre2_code_copy_with_tables man page

    made, with the new code pointing to it. This memory will be automatically freed when pcre2_code_free() is called. The yield of the function is NULL if code is NULL or if sufficient memory cannot be obtained. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_code_free.html b/doc/html/pcre2_code_free.html index ff302fcdf..1a9d9f5c5 100644 --- a/doc/html/pcre2_code_free.html +++ b/doc/html/pcre2_code_free.html @@ -15,23 +15,23 @@

    pcre2_code_free man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    void pcre2_code_free(pcre2_code *code); -

    +


    DESCRIPTION
    -

    +

    If code is NULL, this function does nothing. Otherwise, code must point to a compiled pattern. This function frees its memory, including any memory used by the JIT compiler. If the compiled pattern was created by a call to pcre2_code_copy_with_tables(), the memory for the character tables is also freed. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_compile.html b/doc/html/pcre2_compile.html index ee933f389..50365e0b3 100644 --- a/doc/html/pcre2_compile.html +++ b/doc/html/pcre2_compile.html @@ -15,18 +15,18 @@

    pcre2_compile man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_code *pcre2_compile(PCRE2_SPTR pattern, PCRE2_SIZE length, uint32_t options, int *errorcode, PCRE2_SIZE *erroroffset, pcre2_compile_context *ccontext); -

    +


    DESCRIPTION
    -

    +

    This function compiles a regular expression pattern into an internal form. Its arguments are: 

    @@ -88,13 +88,13 @@ 
    pcre2_compile man page
    PCRE2 must be built with Unicode support (the default) in order to use PCRE2_UTF, PCRE2_UCP and related options. -

    -

    +

    +

    Additional options may be set in the compile context via the pcre2_set_compile_extra_options function. -

    -

    +

    +

    If either of errorcode or erroroffset is NULL, the function returns NULL immediately. Otherwise, the yield of this function is a pointer to a private data structure that contains the compiled pattern, or NULL if an error @@ -102,13 +102,13 @@

    pcre2_compile man page

    passing the value returned via the errorcode argument to the pcre2_get_error_message() function. The offset (in code units) where the error was encountered is returned via the erroroffset argument. -

    -

    +

    +

    If there is no error, the value passed via errorcode returns the message "no error" if passed to pcre2_get_error_message(), and the value passed via erroroffset is zero. -

    -

    +

    +

    There is a complete description of the PCRE2 native API, with more detail on each option, in the pcre2api diff --git a/doc/html/pcre2_compile_context_copy.html b/doc/html/pcre2_compile_context_copy.html index 9e9884b83..d501f30c2 100644 --- a/doc/html/pcre2_compile_context_copy.html +++ b/doc/html/pcre2_compile_context_copy.html @@ -15,22 +15,22 @@

    pcre2_compile_context_copy man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_compile_context *pcre2_compile_context_copy( pcre2_compile_context *ccontext); -

    +


    DESCRIPTION
    -

    +

    This function makes a new copy of a compile context, using the memory allocation function that was used for the original context. The result is NULL if the memory cannot be obtained. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_compile_context_create.html b/doc/html/pcre2_compile_context_create.html index 5eacd4ec7..95c9c4cbd 100644 --- a/doc/html/pcre2_compile_context_create.html +++ b/doc/html/pcre2_compile_context_create.html @@ -15,23 +15,23 @@

    pcre2_compile_context_create man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_compile_context *pcre2_compile_context_create( pcre2_general_context *gcontext); -

    +


    DESCRIPTION
    -

    +

    This function creates and initializes a new compile context. If its argument is NULL, malloc() is used to get the necessary memory; otherwise the memory allocation function within the general context is used. The result is NULL if the memory could not be obtained. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_compile_context_free.html b/doc/html/pcre2_compile_context_free.html index b4159b111..0e54f371a 100644 --- a/doc/html/pcre2_compile_context_free.html +++ b/doc/html/pcre2_compile_context_free.html @@ -15,22 +15,22 @@

    pcre2_compile_context_free man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    void pcre2_compile_context_free(pcre2_compile_context *ccontext); -

    +


    DESCRIPTION
    -

    +

    This function frees the memory occupied by a compile context, using the memory freeing function from the general context with which it was created, or free() if that was not set. If the argument is NULL, the function returns immediately without doing anything. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_config.html b/doc/html/pcre2_config.html index f05bd0627..7ce00e251 100644 --- a/doc/html/pcre2_config.html +++ b/doc/html/pcre2_config.html @@ -15,16 +15,16 @@

    pcre2_config man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_config(uint32_t what, void *where); -

    +


    DESCRIPTION
    -

    +

    This function makes it possible for a client program to find out which optional features are available in the version of the PCRE2 library it is using. The arguments are as follows: @@ -35,8 +35,8 @@

    pcre2_config man page

    If where is NULL, the function returns the amount of memory needed for the requested information. When the information is a string, the value is in code units; for other types of data it is in bytes. -

    -

    +

    +

    If where is not NULL, for PCRE2_CONFIG_JITTARGET, PCRE2_CONFIG_UNICODE_VERSION, and PCRE2_CONFIG_VERSION it must point to a buffer that is large enough to hold the string. For all other codes it must @@ -72,8 +72,8 @@

    pcre2_config man page

    PCRE2_CONFIG_JITTARGET code if JIT support is not available. When a string is requested, the function returns the number of code units used, including the terminating zero. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_convert_context_copy.html b/doc/html/pcre2_convert_context_copy.html index 3c44ac6db..132b21ab8 100644 --- a/doc/html/pcre2_convert_context_copy.html +++ b/doc/html/pcre2_convert_context_copy.html @@ -15,23 +15,23 @@

    pcre2_convert_context_copy man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_convert_context *pcre2_convert_context_copy( pcre2_convert_context *cvcontext); -

    +


    DESCRIPTION
    -

    +

    This function is part of an experimental set of pattern conversion functions. It makes a new copy of a convert context, using the memory allocation function that was used for the original context. The result is NULL if the memory cannot be obtained. -

    -

    +

    +

    The pattern conversion functions are described in the pcre2convert documentation. diff --git a/doc/html/pcre2_convert_context_create.html b/doc/html/pcre2_convert_context_create.html index 256478095..28c008ae2 100644 --- a/doc/html/pcre2_convert_context_create.html +++ b/doc/html/pcre2_convert_context_create.html @@ -15,24 +15,24 @@

    pcre2_convert_context_create man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_convert_context *pcre2_convert_context_create( pcre2_general_context *gcontext); -

    +


    DESCRIPTION
    -

    +

    This function is part of an experimental set of pattern conversion functions. It creates and initializes a new convert context. If its argument is NULL, malloc() is used to get the necessary memory; otherwise the memory allocation function within the general context is used. The result is NULL if the memory could not be obtained. -

    -

    +

    +

    The pattern conversion functions are described in the pcre2convert documentation. diff --git a/doc/html/pcre2_convert_context_free.html b/doc/html/pcre2_convert_context_free.html index e9b142bf7..c4993acfc 100644 --- a/doc/html/pcre2_convert_context_free.html +++ b/doc/html/pcre2_convert_context_free.html @@ -15,23 +15,23 @@

    pcre2_convert_context_free man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    void pcre2_convert_context_free(pcre2_convert_context *cvcontext); -

    +


    DESCRIPTION
    -

    +

    This function is part of an experimental set of pattern conversion functions. It frees the memory occupied by a convert context, using the memory freeing function from the general context with which it was created, or free() if that was not set. If the argument is NULL, the function returns immediately without doing anything. -

    -

    +

    +

    The pattern conversion functions are described in the pcre2convert documentation. diff --git a/doc/html/pcre2_converted_pattern_free.html b/doc/html/pcre2_converted_pattern_free.html index 01d28d7a6..d9b12880b 100644 --- a/doc/html/pcre2_converted_pattern_free.html +++ b/doc/html/pcre2_converted_pattern_free.html @@ -15,23 +15,23 @@

    pcre2_converted_pattern_free man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    void pcre2_converted_pattern_free(PCRE2_UCHAR *converted_pattern); -

    +


    DESCRIPTION
    -

    +

    This function is part of an experimental set of pattern conversion functions. It frees the memory occupied by a converted pattern that was obtained by calling pcre2_pattern_convert() with arguments that caused it to place the converted pattern into newly obtained heap memory. If the argument is NULL, the function returns immediately without doing anything. -

    -

    +

    +

    The pattern conversion functions are described in the pcre2convert documentation. diff --git a/doc/html/pcre2_dfa_match.html b/doc/html/pcre2_dfa_match.html index 0ae428c1f..3a8095479 100644 --- a/doc/html/pcre2_dfa_match.html +++ b/doc/html/pcre2_dfa_match.html @@ -15,20 +15,20 @@

    pcre2_dfa_match man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_dfa_match(const pcre2_code *code, PCRE2_SPTR subject, PCRE2_SIZE length, PCRE2_SIZE startoffset, uint32_t options, pcre2_match_data *match_data, pcre2_match_context *mcontext, int *workspace, PCRE2_SIZE wscount); -

    +


    DESCRIPTION
    -

    +

    This function matches a compiled regular expression against a given subject string, using an alternative matching algorithm that scans the subject string just once (except when processing lookaround assertions). This function is @@ -49,8 +49,8 @@

    pcre2_dfa_match man page

    number of simultaneous matches, not on the number of parentheses in the pattern. Using pcre2_match_data_create_from_pattern() to create the match data block is therefore not advisable when using this function. -

    -

    +

    +

    A match context is needed only if you want to set up a callout function or specify the heap limit or the match or the recursion depth limits. The length and startoffset values are code units, not characters. The diff --git a/doc/html/pcre2_general_context_copy.html b/doc/html/pcre2_general_context_copy.html index 001853468..6a5d45dc4 100644 --- a/doc/html/pcre2_general_context_copy.html +++ b/doc/html/pcre2_general_context_copy.html @@ -15,23 +15,23 @@

    pcre2_general_context_copy man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_general_context *pcre2_general_context_copy( pcre2_general_context *gcontext); -

    +


    DESCRIPTION
    -

    +

    This function makes a new copy of a general context, using the memory allocation functions in the context, if set, to get the necessary memory. Otherwise malloc() is used. The result is NULL if the memory cannot be obtained. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_general_context_create.html b/doc/html/pcre2_general_context_create.html index a1a165d7d..0679a085b 100644 --- a/doc/html/pcre2_general_context_create.html +++ b/doc/html/pcre2_general_context_create.html @@ -15,25 +15,25 @@

    pcre2_general_context_create man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_general_context *pcre2_general_context_create( void *(*private_malloc)(size_t, void *), void (*private_free)(void *, void *), void *memory_data); -

    +


    DESCRIPTION
    -

    +

    This function creates and initializes a general context. The arguments define custom memory management functions and a data value that is passed to them when they are called. The private_malloc() function is used to get memory for the context. If either of the first two arguments is NULL, the system memory management function is used. The result is NULL if no memory could be obtained. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_general_context_free.html b/doc/html/pcre2_general_context_free.html index 9f335f578..0deb23477 100644 --- a/doc/html/pcre2_general_context_free.html +++ b/doc/html/pcre2_general_context_free.html @@ -15,21 +15,21 @@

    pcre2_general_context_free man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    void pcre2_general_context_free(pcre2_general_context *gcontext); -

    +


    DESCRIPTION
    -

    +

    This function frees the memory occupied by a general context, using the memory freeing function within the context, if set. If the argument is NULL, the function returns immediately without doing anything. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_get_error_message.html b/doc/html/pcre2_get_error_message.html index 70057600d..960961204 100644 --- a/doc/html/pcre2_get_error_message.html +++ b/doc/html/pcre2_get_error_message.html @@ -15,17 +15,17 @@

    pcre2_get_error_message man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_get_error_message(int errorcode, PCRE2_UCHAR *buffer, PCRE2_SIZE bufflen); -

    +


    DESCRIPTION
    -

    +

    This function provides a textual error message for each PCRE2 error code. Compilation errors are positive numbers; UTF formatting errors and matching errors are negative numbers. The arguments are: @@ -39,8 +39,8 @@

    pcre2_get_error_message man page

    too small. In this case, the returned message is truncated (but still with a trailing zero). If errorcode does not contain a recognized error code number, the negative value PCRE2_ERROR_BADDATA is returned. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_get_mark.html b/doc/html/pcre2_get_mark.html index 88e632696..8b93f27e7 100644 --- a/doc/html/pcre2_get_mark.html +++ b/doc/html/pcre2_get_mark.html @@ -15,28 +15,28 @@

    pcre2_get_mark man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    PCRE2_SPTR pcre2_get_mark(pcre2_match_data *match_data); -

    +


    DESCRIPTION
    -

    +

    After a call of pcre2_match() that was passed the match block that is this function's argument, this function returns a pointer to the last (*MARK), (*PRUNE), or (*THEN) name that was encountered during the matching process. The name is zero-terminated, and is within the compiled pattern. The length of the name is in the preceding code unit. If no name is available, NULL is returned. -

    -

    +

    +

    After a successful match, the name that is returned is the last one on the matching path. After a failed match or a partial match, the last encountered name is returned. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_get_match_data_heapframes_size.html b/doc/html/pcre2_get_match_data_heapframes_size.html index 3c705c612..dad36dc92 100644 --- a/doc/html/pcre2_get_match_data_heapframes_size.html +++ b/doc/html/pcre2_get_match_data_heapframes_size.html @@ -15,21 +15,21 @@

    pcre2_get_match_data_heapframes_size man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    PCRE2_SIZE pcre2_get_match_data_heapframes_size( pcre2_match_data *match_data); -

    +


    DESCRIPTION
    -

    +

    This function returns the size, in bytes, of the heapframes data block that is owned by its argument. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_get_match_data_size.html b/doc/html/pcre2_get_match_data_size.html index 113ecaab8..0603ff3d4 100644 --- a/doc/html/pcre2_get_match_data_size.html +++ b/doc/html/pcre2_get_match_data_size.html @@ -15,20 +15,20 @@

    pcre2_get_match_data_size man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    PCRE2_SIZE pcre2_get_match_data_size(pcre2_match_data *match_data); -

    +


    DESCRIPTION
    -

    +

    This function returns the size, in bytes, of the match data block that is its argument. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_get_ovector_count.html b/doc/html/pcre2_get_ovector_count.html index 05aacb6de..2483604bb 100644 --- a/doc/html/pcre2_get_ovector_count.html +++ b/doc/html/pcre2_get_ovector_count.html @@ -15,20 +15,20 @@

    pcre2_get_ovector_count man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    uint32_t pcre2_get_ovector_count(pcre2_match_data *match_data); -

    +


    DESCRIPTION
    -

    +

    This function returns the number of pairs of offsets in the ovector that forms part of the given match data block. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_get_ovector_pointer.html b/doc/html/pcre2_get_ovector_pointer.html index ff6317efc..5b4e44162 100644 --- a/doc/html/pcre2_get_ovector_pointer.html +++ b/doc/html/pcre2_get_ovector_pointer.html @@ -15,21 +15,21 @@

    pcre2_get_ovector_pointer man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *match_data); -

    +


    DESCRIPTION
    -

    +

    This function returns a pointer to the vector of offsets that forms part of the given match data block. The number of pairs can be found by calling pcre2_get_ovector_count(). -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_get_startchar.html b/doc/html/pcre2_get_startchar.html index d2c28b2ab..e1fe35a8a 100644 --- a/doc/html/pcre2_get_startchar.html +++ b/doc/html/pcre2_get_startchar.html @@ -15,16 +15,16 @@

    pcre2_get_startchar man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *match_data); -

    +


    DESCRIPTION
    -

    +

    After a successful call of pcre2_match() that was passed the match block that is this function's argument, this function returns the code unit offset of the character at which the successful match started. For a non-partial match, @@ -32,8 +32,8 @@

    pcre2_get_startchar man page

    the \K escape sequence. After a partial match, however, this value is always the same as ovector[0] because \K does not affect the result of a partial match. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_jit_compile.html b/doc/html/pcre2_jit_compile.html index 791dd0c3d..cb43cefef 100644 --- a/doc/html/pcre2_jit_compile.html +++ b/doc/html/pcre2_jit_compile.html @@ -15,24 +15,24 @@

    pcre2_jit_compile man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_jit_compile(pcre2_code *code, uint32_t options); -

    +


    DESCRIPTION
    -

    +

    This function requests JIT compilation, which, if the just-in-time compiler is available, further processes a compiled pattern into machine code that executes much faster than the pcre2_match() interpretive matching function. Full details are given in the pcre2jit documentation. -

    -

    +

    +

    The availability of JIT support can be tested by calling pcre2_compile_jit() with a single option PCRE2_JIT_TEST_ALLOC (the code argument is ignored, so a NULL value is accepted). Such a call @@ -40,8 +40,8 @@

    pcre2_jit_compile man page

    it returns PCRE2_ERROR_NOMEMORY if JIT is available but cannot allocate executable memory, or PCRE2_ERROR_JIT_UNSUPPORTED if JIT support is not compiled. -

    -

    +

    +

    Otherwise, the first argument must be a pointer that was returned by a successful call to pcre2_compile(), and the second must contain one or more of the following bits: @@ -53,8 +53,8 @@

    pcre2_jit_compile man page

    There is also an obsolete option called PCRE2_JIT_INVALID_UTF, which has been superseded by the pcre2_compile() option PCRE2_MATCH_INVALID_UTF. The old option is deprecated and may be removed in the future. -

    -

    +

    +

    The yield of the function when called with any of the three options above is 0 for success, or a negative error code otherwise. In particular, PCRE2_ERROR_JIT_BADOPTION is returned if JIT is not supported or if an unknown @@ -62,8 +62,8 @@

    pcre2_jit_compile man page

    if JIT is unable to allocate executable memory for the compiler, even if it was because of a system security restriction. In a few cases, the function may return with PCRE2_ERROR_JIT_UNSUPPORTED for unsupported features. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_jit_free_unused_memory.html b/doc/html/pcre2_jit_free_unused_memory.html index 7f37e583a..530a8c39c 100644 --- a/doc/html/pcre2_jit_free_unused_memory.html +++ b/doc/html/pcre2_jit_free_unused_memory.html @@ -15,24 +15,24 @@

    pcre2_jit_free_unused_memory man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    void pcre2_jit_free_unused_memory(pcre2_general_context *gcontext); -

    +


    DESCRIPTION
    -

    +

    This function frees unused JIT executable memory. The argument is a general context, for custom memory management, or NULL for standard memory management. JIT memory allocation retains some memory in order to improve future JIT compilation speed. In low memory conditions, pcre2_jit_free_unused_memory() can be used to cause this memory to be freed. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_jit_match.html b/doc/html/pcre2_jit_match.html index 56144ff9a..418219c97 100644 --- a/doc/html/pcre2_jit_match.html +++ b/doc/html/pcre2_jit_match.html @@ -15,51 +15,51 @@

    pcre2_jit_match man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_jit_match(const pcre2_code *code, PCRE2_SPTR subject, PCRE2_SIZE length, PCRE2_SIZE startoffset, uint32_t options, pcre2_match_data *match_data, pcre2_match_context *mcontext); -

    +


    DESCRIPTION
    -

    +

    This function matches a compiled regular expression that has been successfully processed by the JIT compiler against a given subject string, using a matching algorithm that is similar to Perl's. It is a "fast path" interface to JIT, and it bypasses some of the sanity checks that pcre2_match() applies. -

    -

    +

    +

    In UTF mode, the subject string is not checked for UTF validity. Unless PCRE2_MATCH_INVALID_UTF was set when the pattern was compiled, passing an invalid UTF string results in undefined behaviour. Your program may crash or loop or give wrong results. In the absence of PCRE2_MATCH_INVALID_UTF you should only call pcre2_jit_match() in UTF mode if you are sure the subject is valid. -

    -

    +

    +

    The arguments for pcre2_jit_match() are exactly the same as for pcre2_match(), except that the subject string must be specified with a length; PCRE2_ZERO_TERMINATED is not supported. -

    -

    +

    +

    The supported options are PCRE2_NOTBOL, PCRE2_NOTEOL, PCRE2_NOTEMPTY, PCRE2_NOTEMPTY_ATSTART, PCRE2_PARTIAL_HARD, and PCRE2_PARTIAL_SOFT. Unsupported options are ignored. -

    -

    +

    +

    The return values are the same as for pcre2_match() plus PCRE2_ERROR_JIT_BADOPTION if a matching mode (partial or complete) is requested that was not compiled. For details of partial matching, see the pcre2partial page. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the JIT API in the diff --git a/doc/html/pcre2_jit_stack_assign.html b/doc/html/pcre2_jit_stack_assign.html index 4b3abb90a..cd260829d 100644 --- a/doc/html/pcre2_jit_stack_assign.html +++ b/doc/html/pcre2_jit_stack_assign.html @@ -15,17 +15,17 @@

    pcre2_jit_stack_assign man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    void pcre2_jit_stack_assign(pcre2_match_context *mcontext, pcre2_jit_callback callback_function, void *callback_data); -

    +


    DESCRIPTION
    -

    +

    This function provides control over the memory used by JIT as a run-time stack when pcre2_match() or pcre2_jit_match() is called with a pattern that has been successfully processed by the JIT compiler. The information that @@ -35,36 +35,36 @@

    pcre2_jit_stack_assign man page

    mcontext a pointer to a match context callback a callback function callback_data a JIT stack or a value to be passed to the callback - -

    -

    + +

    +

    If mcontext is NULL, the function returns immediately, without doing anything. -

    -

    +

    +

    If callback is NULL and callback_data is NULL, an internal 32KiB block on the machine stack is used. -

    -

    +

    +

    If callback is NULL and callback_data is not NULL, callback_data must be a valid JIT stack, the result of calling pcre2_jit_stack_create(). -

    -

    +

    +

    If callback not NULL, it is called with callback_data as an argument at the start of matching, in order to set up a JIT stack. If the result is NULL, the internal 32KiB stack is used; otherwise the return value must be a valid JIT stack, the result of calling pcre2_jit_stack_create(). -

    -

    +

    +

    You may safely use the same JIT stack for multiple patterns, as long as they are all matched in the same thread. In a multithread application, each thread must use its own JIT stack. For more details, see the pcre2jit page. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_jit_stack_create.html b/doc/html/pcre2_jit_stack_create.html index b9dc59d66..ec235f2b5 100644 --- a/doc/html/pcre2_jit_stack_create.html +++ b/doc/html/pcre2_jit_stack_create.html @@ -15,17 +15,17 @@

    pcre2_jit_stack_create man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_jit_stack *pcre2_jit_stack_create(size_t startsize, size_t maxsize, pcre2_general_context *gcontext); -

    +


    DESCRIPTION
    -

    +

    This function is used to create a stack for use by the code compiled by the JIT compiler. The first two arguments are a starting size for the stack, and a maximum size to which it is allowed to grow. The final argument is a general @@ -38,8 +38,8 @@

    pcre2_jit_stack_create man page

    reasonable, NULL will be returned. For more details, see the pcre2jit page. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_jit_stack_free.html b/doc/html/pcre2_jit_stack_free.html index 1d078d74e..b80246f97 100644 --- a/doc/html/pcre2_jit_stack_free.html +++ b/doc/html/pcre2_jit_stack_free.html @@ -15,24 +15,24 @@

    pcre2_jit_stack_free man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    void pcre2_jit_stack_free(pcre2_jit_stack *jit_stack); -

    +


    DESCRIPTION
    -

    +

    This function is used to free a JIT stack that was created by pcre2_jit_stack_create() when it is no longer needed. If the argument is NULL, the function returns immediately without doing anything. For more details, see the pcre2jit page. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_maketables.html b/doc/html/pcre2_maketables.html index 196365453..a4750d49a 100644 --- a/doc/html/pcre2_maketables.html +++ b/doc/html/pcre2_maketables.html @@ -15,29 +15,29 @@

    pcre2_maketables man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    const uint8_t *pcre2_maketables(pcre2_general_context *gcontext); -

    +


    DESCRIPTION
    -

    +

    This function builds a set of character tables for character code points that are less than 256. These can be passed to pcre2_compile() in a compile context in order to override the internal, built-in tables (which were either defaulted or made by pcre2_maketables() when PCRE2 was compiled). See the pcre2_set_character_tables() page. You might want to do this if you are using a non-standard locale. -

    -

    +

    +

    If the argument is NULL, malloc() is used to get memory for the tables. Otherwise it must point to a general context, which can supply pointers to a custom memory manager. The function yields a pointer to the tables. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_maketables_free.html b/doc/html/pcre2_maketables_free.html index 7316ab25b..7f6f777eb 100644 --- a/doc/html/pcre2_maketables_free.html +++ b/doc/html/pcre2_maketables_free.html @@ -15,27 +15,27 @@

    pcre2_maketables_free man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    void pcre2_maketables_free(pcre2_general_context *gcontext, const uint8_t *tables); -

    +


    DESCRIPTION
    -

    +

    This function discards a set of character tables that were created by a call to pcre2_maketables(). -

    -

    +

    +

    The gcontext parameter should match what was used in that call to account for any custom allocators that might be in use; if it is NULL the system free() is used. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page. diff --git a/doc/html/pcre2_match.html b/doc/html/pcre2_match.html index 5584ae3d0..e10354d65 100644 --- a/doc/html/pcre2_match.html +++ b/doc/html/pcre2_match.html @@ -15,19 +15,19 @@

    pcre2_match man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_match(const pcre2_code *code, PCRE2_SPTR subject, PCRE2_SIZE length, PCRE2_SIZE startoffset, uint32_t options, pcre2_match_data *match_data, pcre2_match_context *mcontext); -

    +


    DESCRIPTION
    -

    +

    This function matches a compiled regular expression against a given subject string, using a matching algorithm that is similar to Perl's. It returns offsets to what it has matched and to captured substrings via the diff --git a/doc/html/pcre2_match_context_copy.html b/doc/html/pcre2_match_context_copy.html index 4a719d691..97524c2d5 100644 --- a/doc/html/pcre2_match_context_copy.html +++ b/doc/html/pcre2_match_context_copy.html @@ -15,22 +15,22 @@

    pcre2_match_context_copy man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_match_context *pcre2_match_context_copy( pcre2_match_context *mcontext); -

    +


    DESCRIPTION
    -

    +

    This function makes a new copy of a match context, using the memory allocation function that was used for the original context. The result is NULL if the memory cannot be obtained. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_match_context_create.html b/doc/html/pcre2_match_context_create.html index f7f273513..24a53723e 100644 --- a/doc/html/pcre2_match_context_create.html +++ b/doc/html/pcre2_match_context_create.html @@ -15,23 +15,23 @@

    pcre2_match_context_create man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_match_context *pcre2_match_context_create( pcre2_general_context *gcontext); -

    +


    DESCRIPTION
    -

    +

    This function creates and initializes a new match context. If its argument is NULL, malloc() is used to get the necessary memory; otherwise the memory allocation function within the general context is used. The result is NULL if the memory could not be obtained. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_match_context_free.html b/doc/html/pcre2_match_context_free.html index 7f00ea9b2..ffea8455e 100644 --- a/doc/html/pcre2_match_context_free.html +++ b/doc/html/pcre2_match_context_free.html @@ -15,22 +15,22 @@

    pcre2_match_context_free man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    void pcre2_match_context_free(pcre2_match_context *mcontext); -

    +


    DESCRIPTION
    -

    +

    This function frees the memory occupied by a match context, using the memory freeing function from the general context with which it was created, or free() if that was not set. If the argument is NULL, the function returns immediately without doing anything. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_match_data_create.html b/doc/html/pcre2_match_data_create.html index c26c3b324..e950a8ab7 100644 --- a/doc/html/pcre2_match_data_create.html +++ b/doc/html/pcre2_match_data_create.html @@ -15,17 +15,17 @@

    pcre2_match_data_create man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_match_data *pcre2_match_data_create(uint32_t ovecsize, pcre2_general_context *gcontext); -

    +


    DESCRIPTION
    -

    +

    This function creates a new match data block, which is used for holding the result of a match. The first argument specifies the number of pairs of offsets that are required. These form the "output vector" (ovector) within the match @@ -33,13 +33,13 @@

    pcre2_match_data_create man page

    substrings when matching with pcre2_match(), or a number of different matches at the same point when used with pcre2_dfa_match(). There is always one pair of offsets; if ovecsize is zero, it is treated as one. -

    -

    +

    +

    The second argument points to a general context, for custom memory management, or is NULL for system memory management. The result of the function is NULL if the memory for the block could not be obtained. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_match_data_create_from_pattern.html b/doc/html/pcre2_match_data_create_from_pattern.html index db58ab914..fb7592601 100644 --- a/doc/html/pcre2_match_data_create_from_pattern.html +++ b/doc/html/pcre2_match_data_create_from_pattern.html @@ -15,17 +15,17 @@

    pcre2_match_data_create_from_pattern man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    pcre2_match_data *pcre2_match_data_create_from_pattern( const pcre2_code *code, pcre2_general_context *gcontext); -

    +


    DESCRIPTION
    -

    +

    This function creates a new match data block for holding the result of a match. The first argument points to a compiled pattern. The number of capturing parentheses within the pattern is used to compute the number of pairs of @@ -35,14 +35,14 @@

    pcre2_match_data_create_from_pattern man page

    pcre2_match(). If you are using pcre2_dfa_match(), which uses the output vector in a different way, you should use pcre2_match_data_create() instead of this function. -

    -

    +

    +

    The second argument points to a general context, for custom memory management, or is NULL to use the same memory allocator as was used for the compiled pattern. The result of the function is NULL if the memory for the block could not be obtained. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_match_data_free.html b/doc/html/pcre2_match_data_free.html index 1c2520b9d..422a5b97b 100644 --- a/doc/html/pcre2_match_data_free.html +++ b/doc/html/pcre2_match_data_free.html @@ -15,29 +15,29 @@

    pcre2_match_data_free man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    void pcre2_match_data_free(pcre2_match_data *match_data); -

    +


    DESCRIPTION
    -

    +

    If match_data is NULL, this function does nothing. Otherwise, match_data must point to a match data block, which this function frees, using the memory freeing function from the general context or compiled pattern with which it was created, or free() if that was not set. If the match data block was previously passed to pcre2_match(), it will have an attached heapframe vector; this is also freed. -

    -

    +

    +

    If the PCRE2_COPY_MATCHED_SUBJECT was used for a successful match using this match data block, the copy of the subject that was referenced within the block is also freed. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_pattern_convert.html b/doc/html/pcre2_pattern_convert.html index 2fcd7cc08..3f18ff1fe 100644 --- a/doc/html/pcre2_pattern_convert.html +++ b/doc/html/pcre2_pattern_convert.html @@ -15,18 +15,18 @@

    pcre2_pattern_convert man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_pattern_convert(PCRE2_SPTR pattern, PCRE2_SIZE length, uint32_t options, PCRE2_UCHAR **buffer, PCRE2_SIZE *blength, pcre2_convert_context *cvcontext); -

    +


    DESCRIPTION
    -

    +

    This function is part of an experimental set of pattern conversion functions. It converts a foreign pattern (for example, a glob) into a PCRE2 regular expression pattern. Its arguments are: @@ -46,8 +46,8 @@

    pcre2_pattern_convert man page

    updated. If buffer points to a non-NULL field, that must point to a buffer whose size is in the variable pointed to by blength. This value is updated. -

    -

    +

    +

    The option bits are: 

       PCRE2_CONVERT_UTF                     Input is UTF
@@ -60,8 +60,8 @@ 
    pcre2_pattern_convert man page
    The return value from pcre2_pattern_convert() is zero on success or a non-zero PCRE2 error code. -

    -

    +

    +

    The pattern conversion functions are described in the pcre2convert documentation. diff --git a/doc/html/pcre2_pattern_info.html b/doc/html/pcre2_pattern_info.html index eaaac6c0d..b17dadc3e 100644 --- a/doc/html/pcre2_pattern_info.html +++ b/doc/html/pcre2_pattern_info.html @@ -15,17 +15,17 @@

    pcre2_pattern_info man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_pattern_info(const pcre2_code *code, uint32_t what, void *where); -

    +


    DESCRIPTION
    -

    +

    This function returns information about a compiled pattern. Its arguments are: 

       code     Pointer to a compiled regular expression pattern
@@ -96,9 +96,9 @@ 
    pcre2_pattern_info man page
    
   PCRE2_ERROR_BADOPTION      the value of what is invalid
   PCRE2_ERROR_BADMODE        the pattern was compiled in the wrong mode
   PCRE2_ERROR_UNSET          the requested information is not set
-
    -

    -

    + +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_serialize_decode.html b/doc/html/pcre2_serialize_decode.html index 618ffa929..5af795f3e 100644 --- a/doc/html/pcre2_serialize_decode.html +++ b/doc/html/pcre2_serialize_decode.html @@ -15,18 +15,18 @@

    pcre2_serialize_decode man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int32_t pcre2_serialize_decode(pcre2_code **codes, int32_t number_of_codes, const uint8_t *bytes, pcre2_general_context *gcontext); -

    +


    DESCRIPTION
    -

    +

    This function decodes a serialized set of compiled patterns back into a list of individual patterns. This is possible only on a host that is running the same version of PCRE2, with the same code unit width, and the host must also have @@ -53,8 +53,8 @@

    pcre2_serialize_decode man page

    PCRE2_ERROR_BADMAGIC may mean that the data is corrupt, or that it was compiled on a system with different endianness. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the serialization functions in the diff --git a/doc/html/pcre2_serialize_encode.html b/doc/html/pcre2_serialize_encode.html index f1532700d..c4ea1dfc8 100644 --- a/doc/html/pcre2_serialize_encode.html +++ b/doc/html/pcre2_serialize_encode.html @@ -15,18 +15,18 @@

    pcre2_serialize_encode man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int32_t pcre2_serialize_encode(const pcre2_code **codes, int32_t number_of_codes, uint8_t **serialized_bytes, PCRE2_SIZE *serialized_size, pcre2_general_context *gcontext); -

    +


    DESCRIPTION
    -

    +

    This function encodes a list of compiled patterns into a byte stream that can be saved on disc or elsewhere. Note that this is not an abstract format like Java or .NET. Conversion of the byte stream back into usable compiled patterns @@ -54,8 +54,8 @@

    pcre2_serialize_encode man page

    PCRE2_ERROR_BADMAGIC means either that a pattern's code has been corrupted, or that a slot in the vector does not point to a compiled pattern. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the serialization functions in the diff --git a/doc/html/pcre2_serialize_free.html b/doc/html/pcre2_serialize_free.html index 26b435bc7..d17cc0204 100644 --- a/doc/html/pcre2_serialize_free.html +++ b/doc/html/pcre2_serialize_free.html @@ -15,22 +15,22 @@

    pcre2_serialize_free man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    void pcre2_serialize_free(uint8_t *bytes); -

    +


    DESCRIPTION
    -

    +

    This function frees the memory that was obtained by pcre2_serialize_encode() to hold a serialized byte stream. The argument must point to such a byte stream or be NULL, in which case the function returns without doing anything. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the serialization functions in the diff --git a/doc/html/pcre2_serialize_get_number_of_codes.html b/doc/html/pcre2_serialize_get_number_of_codes.html index fdd242946..40c4bb6d8 100644 --- a/doc/html/pcre2_serialize_get_number_of_codes.html +++ b/doc/html/pcre2_serialize_get_number_of_codes.html @@ -15,16 +15,16 @@

    pcre2_serialize_get_number_of_codes man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int32_t pcre2_serialize_get_number_of_codes(const uint8_t *bytes); -

    +


    DESCRIPTION
    -

    +

    The bytes argument must point to a serialized byte stream that was originally created by pcre2_serialize_encode() (though it may have been saved on disc or elsewhere in the meantime). The function returns the number of @@ -37,8 +37,8 @@

    pcre2_serialize_get_number_of_codes man page

    PCRE2_ERROR_BADMAGIC may mean that the data is corrupt, or that it was compiled on a system with different endianness. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the serialization functions in the diff --git a/doc/html/pcre2_set_bsr.html b/doc/html/pcre2_set_bsr.html index 8a62f18a6..f7a2387e5 100644 --- a/doc/html/pcre2_set_bsr.html +++ b/doc/html/pcre2_set_bsr.html @@ -15,23 +15,23 @@

    pcre2_set_bsr man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_bsr(pcre2_compile_context *ccontext, uint32_t value); -

    +


    DESCRIPTION
    -

    +

    This function sets the convention for processing \R within a compile context. The second argument must be one of PCRE2_BSR_ANYCRLF or PCRE2_BSR_UNICODE. The result is zero for success or PCRE2_ERROR_BADDATA if the second argument is invalid. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_set_callout.html b/doc/html/pcre2_set_callout.html index 4e7aca6c4..6550b84b9 100644 --- a/doc/html/pcre2_set_callout.html +++ b/doc/html/pcre2_set_callout.html @@ -15,24 +15,24 @@

    pcre2_set_callout man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_callout(pcre2_match_context *mcontext, int (*callout_function)(pcre2_callout_block *), void *callout_data); -

    +


    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 item that is passed to it. The result of this function 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 diff --git a/doc/html/pcre2_set_character_tables.html b/doc/html/pcre2_set_character_tables.html index 8564eea69..062853d56 100644 --- a/doc/html/pcre2_set_character_tables.html +++ b/doc/html/pcre2_set_character_tables.html @@ -15,17 +15,17 @@

    pcre2_set_character_tables man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_character_tables(pcre2_compile_context *ccontext, const uint8_t *tables); -

    +


    DESCRIPTION
    -

    +

    This function sets a pointer to custom character tables within a compile context. The second argument must point to a set of PCRE2 character tables or be NULL to request the default tables. The result is always zero. Character @@ -33,8 +33,8 @@

    pcre2_set_character_tables man page

    pcre2_dftables maintenance command in binary mode (see the pcre2build documentation). -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_set_compile_extra_options.html b/doc/html/pcre2_set_compile_extra_options.html index cb62022a2..5672813d0 100644 --- a/doc/html/pcre2_set_compile_extra_options.html +++ b/doc/html/pcre2_set_compile_extra_options.html @@ -15,17 +15,17 @@

    pcre2_set_compile_extra_options man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_compile_extra_options(pcre2_compile_context *ccontext, uint32_t extra_options); -

    +


    DESCRIPTION
    -

    +

    This function sets additional option bits for pcre2_compile() that are housed in a compile context. It completely replaces all the bits. The extra options are: diff --git a/doc/html/pcre2_set_compile_recursion_guard.html b/doc/html/pcre2_set_compile_recursion_guard.html index c09942ce2..bcae05615 100644 --- a/doc/html/pcre2_set_compile_recursion_guard.html +++ b/doc/html/pcre2_set_compile_recursion_guard.html @@ -15,17 +15,17 @@

    pcre2_set_compile_recursion_guard man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_compile_recursion_guard(pcre2_compile_context *ccontext, int (*guard_function)(uint32_t, void *), void *user_data); -

    +


    DESCRIPTION
    -

    +

    This function defines, within a compile context, a function that is called whenever pcre2_compile() starts to compile a parenthesized part of a pattern. The first argument to the function gives the current depth of @@ -34,8 +34,8 @@

    pcre2_set_compile_recursion_guard man page

    non-zero to force an error. This feature is provided so that applications can check the available system stack space, in order to avoid running out. The result of pcre2_set_compile_recursion_guard() 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 diff --git a/doc/html/pcre2_set_depth_limit.html b/doc/html/pcre2_set_depth_limit.html index a1cf7062c..b77d0073e 100644 --- a/doc/html/pcre2_set_depth_limit.html +++ b/doc/html/pcre2_set_depth_limit.html @@ -15,21 +15,21 @@

    pcre2_set_depth_limit man page


    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 diff --git a/doc/html/pcre2_set_glob_escape.html b/doc/html/pcre2_set_glob_escape.html index 2b5562711..b12b0195e 100644 --- a/doc/html/pcre2_set_glob_escape.html +++ b/doc/html/pcre2_set_glob_escape.html @@ -15,17 +15,17 @@

    pcre2_set_glob_escape man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_glob_escape(pcre2_convert_context *cvcontext, uint32_t escape_char); -

    +


    DESCRIPTION
    -

    +

    This function is part of an experimental set of pattern conversion functions. It sets the escape character that is used when converting globs. The second argument must either be zero (meaning there is no escape character) or a @@ -33,8 +33,8 @@

    pcre2_set_glob_escape man page

    accent if running under Windows, otherwise backslash. The result of the function is zero for success or PCRE2_ERROR_BADDATA if the second argument is invalid. -

    -

    +

    +

    The pattern conversion functions are described in the pcre2convert documentation. diff --git a/doc/html/pcre2_set_glob_separator.html b/doc/html/pcre2_set_glob_separator.html index 283648ea1..5be701e45 100644 --- a/doc/html/pcre2_set_glob_separator.html +++ b/doc/html/pcre2_set_glob_separator.html @@ -15,25 +15,25 @@

    pcre2_set_glob_separator man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_glob_separator(pcre2_convert_context *cvcontext, uint32_t separator_char); -

    +


    DESCRIPTION
    -

    +

    This function is part of an experimental set of pattern conversion functions. It sets the component separator character that is used when converting globs. The second argument must be one of the characters forward slash, backslash, or dot. The default is backslash when running under Windows, otherwise forward slash. The result of the function is zero for success or PCRE2_ERROR_BADDATA if the second argument is invalid. -

    -

    +

    +

    The pattern conversion functions are described in the pcre2convert documentation. diff --git a/doc/html/pcre2_set_heap_limit.html b/doc/html/pcre2_set_heap_limit.html index 3631ef6fd..aa16c2604 100644 --- a/doc/html/pcre2_set_heap_limit.html +++ b/doc/html/pcre2_set_heap_limit.html @@ -15,21 +15,21 @@

    pcre2_set_heap_limit man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_heap_limit(pcre2_match_context *mcontext, uint32_t value); -

    +


    DESCRIPTION
    -

    +

    This function sets the backtracking heap 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 diff --git a/doc/html/pcre2_set_match_limit.html b/doc/html/pcre2_set_match_limit.html index e840c744e..5afdfa11c 100644 --- a/doc/html/pcre2_set_match_limit.html +++ b/doc/html/pcre2_set_match_limit.html @@ -15,21 +15,21 @@

    pcre2_set_match_limit man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_match_limit(pcre2_match_context *mcontext, uint32_t value); -

    +


    DESCRIPTION
    -

    +

    This function sets the match 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 diff --git a/doc/html/pcre2_set_max_pattern_compiled_length.html b/doc/html/pcre2_set_max_pattern_compiled_length.html index a40f41e45..2fc2e86bb 100644 --- a/doc/html/pcre2_set_max_pattern_compiled_length.html +++ b/doc/html/pcre2_set_max_pattern_compiled_length.html @@ -15,25 +15,25 @@

    pcre2_set_max_pattern_compiled_length man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_max_pattern_compiled_length( pcre2_compile_context *ccontext, PCRE2_SIZE value); -

    +


    DESCRIPTION
    -

    +

    This function sets, in a compile context, the maximum size (in bytes) for the memory needed to hold the compiled version of a pattern that is using this context. The result is always zero. If a pattern that is passed to pcre2_compile() referencing this context needs more memory, an error is generated. The default is the largest number that a PCRE2_SIZE variable can hold, which is effectively unlimited. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_set_max_pattern_length.html b/doc/html/pcre2_set_max_pattern_length.html index f6e422aa5..c4941fde8 100644 --- a/doc/html/pcre2_set_max_pattern_length.html +++ b/doc/html/pcre2_set_max_pattern_length.html @@ -15,24 +15,24 @@

    pcre2_set_max_pattern_length man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_max_pattern_length(pcre2_compile_context *ccontext, PCRE2_SIZE value); -

    +


    DESCRIPTION
    -

    +

    This function sets, in a compile context, the maximum text length (in code units) of the pattern that can be compiled. The result is always zero. If a longer pattern is passed to pcre2_compile() there is an immediate error return. The default is effectively unlimited, being the largest value a PCRE2_SIZE variable can hold. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_set_max_varlookbehind.html b/doc/html/pcre2_set_max_varlookbehind.html index 1c03def22..987e547a8 100644 --- a/doc/html/pcre2_set_max_varlookbehind.html +++ b/doc/html/pcre2_set_max_varlookbehind.html @@ -15,23 +15,23 @@

    pcre2_set_max_varlookbehind man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_max_varlookbehind(pcre2_compile_context *ccontext, uint32_t value); -

    +


    DESCRIPTION
    -

    +

    This sets a maximum length for the number of characters matched by a variable-length lookbehind assertion. The default is set when PCRE2 is built, with the ultimate default being 255, the same as Perl. Lookbehind assertions without a bounding length are not supported. 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 diff --git a/doc/html/pcre2_set_newline.html b/doc/html/pcre2_set_newline.html index ba8130014..70e18a871 100644 --- a/doc/html/pcre2_set_newline.html +++ b/doc/html/pcre2_set_newline.html @@ -15,17 +15,17 @@

    pcre2_set_newline man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_newline(pcre2_compile_context *ccontext, uint32_t value); -

    +


    DESCRIPTION
    -

    +

    This function sets the newline convention within a compile context. This specifies which character(s) are recognized as newlines when compiling and matching patterns. The second argument must be one of: @@ -39,8 +39,8 @@

    pcre2_set_newline man page

    The result is zero for success or PCRE2_ERROR_BADDATA if the second argument is invalid. -

    -

    +

    +

    There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the diff --git a/doc/html/pcre2_set_offset_limit.html b/doc/html/pcre2_set_offset_limit.html index 6d9a85c64..71d4000e7 100644 --- a/doc/html/pcre2_set_offset_limit.html +++ b/doc/html/pcre2_set_offset_limit.html @@ -15,21 +15,21 @@

    pcre2_set_offset_limit man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_offset_limit(pcre2_match_context *mcontext, PCRE2_SIZE value); -

    +


    DESCRIPTION
    -

    +

    This function sets the offset 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 diff --git a/doc/html/pcre2_set_optimize.html b/doc/html/pcre2_set_optimize.html index 47caeb267..ae9cdae50 100644 --- a/doc/html/pcre2_set_optimize.html +++ b/doc/html/pcre2_set_optimize.html @@ -15,28 +15,28 @@

    pcre2_set_optimize man page


    SYNOPSIS
    -

    +

    #include <pcre2.h> -

    -

    +

    +

    int pcre2_set_optimize(pcre2_compile_context *ccontext, uint32_t directive); -

    +


    DESCRIPTION
    -

    +

    This function controls which performance optimizations will be applied by pcre2_compile(). It can be called multiple times with the same compile context; the effects are cumulative, with the effects of later calls taking precedence over earlier ones. -

    -

    +

    +

    The result is zero for success, PCRE2_ERROR_NULL if ccontext is NULL, or PCRE2_ERROR_BADOPTION if directive is unknown. The latter could be useful to detect if a certain optimization is available. -

    -

    +

    +

    The list of possible values for the directive parameter are: 

       PCRE2_OPTIMIZATION_FULL   Enable all optimizations (default)
diff --git a/doc/html/pcre2_set_parens_nest_limit.html b/doc/html/pcre2_set_parens_nest_limit.html
index 95fd31c33..d3aff6b14 100644
--- a/doc/html/pcre2_set_parens_nest_limit.html
+++ b/doc/html/pcre2_set_parens_nest_limit.html
@@ -15,21 +15,21 @@ 
    pcre2_set_parens_nest_limit man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_set_parens_nest_limit(pcre2_compile_context *ccontext,
   uint32_t value);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This function sets, in a compile context, the maximum depth of nested
 parentheses in a pattern. 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
diff --git a/doc/html/pcre2_set_recursion_limit.html b/doc/html/pcre2_set_recursion_limit.html
index 9ff68c2f0..6d1b73542 100644
--- a/doc/html/pcre2_set_recursion_limit.html
+++ b/doc/html/pcre2_set_recursion_limit.html
@@ -15,21 +15,21 @@ 
    pcre2_set_recursion_limit man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_set_recursion_limit(pcre2_match_context *mcontext,
   uint32_t value);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 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
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2_set_recursion_memory_management.html b/doc/html/pcre2_set_recursion_memory_management.html
index 37af73ca3..31b0f82ca 100644
--- a/doc/html/pcre2_set_recursion_memory_management.html
+++ b/doc/html/pcre2_set_recursion_memory_management.html
@@ -15,23 +15,23 @@ 
    pcre2_set_recursion_memory_management man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_set_recursion_memory_management(
   pcre2_match_context *mcontext,
   void *(*private_malloc)(size_t, void *),
   void (*private_free)(void *, void *), void *memory_data);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 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
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2_set_substitute_callout.html b/doc/html/pcre2_set_substitute_callout.html
index 8640728fd..0a4b136b3 100644
--- a/doc/html/pcre2_set_substitute_callout.html
+++ b/doc/html/pcre2_set_substitute_callout.html
@@ -15,24 +15,24 @@ 
    pcre2_set_substitute_callout man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_set_substitute_callout(pcre2_match_context *mcontext,
   int (*callout_function)(pcre2_substitute_callout_block *, void *),
   void *callout_data);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This function sets the substitute callout fields in a match context (the first
 argument). The second argument specifies a callout function, and the third
 argument is an opaque data item that is passed to it. The result of this
 function 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
diff --git a/doc/html/pcre2_set_substitute_case_callout.html b/doc/html/pcre2_set_substitute_case_callout.html
index ab506879f..83ac54ecc 100644
--- a/doc/html/pcre2_set_substitute_case_callout.html
+++ b/doc/html/pcre2_set_substitute_case_callout.html
@@ -15,26 +15,26 @@ 
    pcre2_set_substitute_case_callout man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_set_substitute_case_callout(pcre2_match_context *mcontext,
   PCRE2_SIZE (*callout_function)(PCRE2_SPTR, PCRE2_SIZE,
                                  PCRE2_UCHAR *, PCRE2_SIZE,
                                  int, void *),
   void *callout_data);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This function sets the substitute case callout fields in a match context (the
 first argument). The second argument specifies a callout function, and the third
 argument is an opaque data item that is passed to it. The result of this
 function 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
diff --git a/doc/html/pcre2_substitute.html b/doc/html/pcre2_substitute.html
index abf0a7030..b6f06d9c0 100644
--- a/doc/html/pcre2_substitute.html
+++ b/doc/html/pcre2_substitute.html
@@ -15,21 +15,21 @@ 
    pcre2_substitute man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_substitute(const pcre2_code *code, PCRE2_SPTR subject,
   PCRE2_SIZE length, PCRE2_SIZE startoffset,
   uint32_t options, pcre2_match_data *match_data,
   pcre2_match_context *mcontext, PCRE2_SPTR replacement,
   PCRE2_SIZE rlength, PCRE2_UCHAR *outputbuffer,
   PCRE2_SIZE *outlengthptr);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This function matches a compiled regular expression against a given subject
 string, using a matching algorithm that is similar to Perl's. It then makes a
 copy of the subject, substituting a replacement string for what was matched.
@@ -63,8 +63,8 @@ 
    pcre2_substitute man page
    
 when the function is called. If the function is successful, the value is
 changed to the length of the new string, excluding the trailing zero that is
 automatically added.
-
    
-
    
+
    
+
    
 The subject and replacement lengths can be given as PCRE2_ZERO_TERMINATED for
 zero-terminated strings. The options are:
 
    @@ -88,19 +88,19 @@ 
    pcre2_substitute man page
    
 
    
 If PCRE2_SUBSTITUTE_LITERAL is set, PCRE2_SUBSTITUTE_EXTENDED,
 PCRE2_SUBSTITUTE_UNKNOWN_UNSET, and PCRE2_SUBSTITUTE_UNSET_EMPTY are ignored.
-
    
-
    
+
    
+
    
 If PCRE2_SUBSTITUTE_MATCHED is set, match_data must be non-NULL; its
 contents must be the result of a call to pcre2_match() using the same
 pattern and subject.
-
    
-
    
+
    
+
    
 The function returns the number of substitutions, which may be zero if there
 are no matches. The result may be greater than one only when
 PCRE2_SUBSTITUTE_GLOBAL is set. In the event of an error, a negative error code
 is returned.
-
    
-
    
+
    
+
    
 There is a complete description of the PCRE2 native API in the
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2_substring_copy_byname.html b/doc/html/pcre2_substring_copy_byname.html
index fd01805e8..7f4c3c97d 100644
--- a/doc/html/pcre2_substring_copy_byname.html
+++ b/doc/html/pcre2_substring_copy_byname.html
@@ -15,17 +15,17 @@ 
    pcre2_substring_copy_byname man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_substring_copy_byname(pcre2_match_data *match_data,
   PCRE2_SPTR name, PCRE2_UCHAR *buffer, PCRE2_SIZE *bufflen);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This is a convenience function for extracting a captured substring, identified
 by name, into a given buffer. The arguments are:
 
    @@ -46,8 +46,8 @@ 
    pcre2_substring_copy_byname man page
    
 If there is more than one group with the given name, the first one that is set
 is returned. In this situation PCRE2_ERROR_UNSET means that no group with the
 given name was set.
-
    
-
    
+
    
+
    
 There is a complete description of the PCRE2 native API in the
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2_substring_copy_bynumber.html b/doc/html/pcre2_substring_copy_bynumber.html
index 83e1a2720..64bb73e95 100644
--- a/doc/html/pcre2_substring_copy_bynumber.html
+++ b/doc/html/pcre2_substring_copy_bynumber.html
@@ -15,18 +15,18 @@ 
    pcre2_substring_copy_bynumber man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_substring_copy_bynumber(pcre2_match_data *match_data,
   uint32_t number, PCRE2_UCHAR *buffer,
   PCRE2_SIZE *bufflen);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This is a convenience function for extracting a captured substring into a given
 buffer. The arguments are:
 
    @@ -44,9 +44,9 @@ 
    pcre2_substring_copy_bynumber man page
    
   PCRE2_ERROR_UNSET         the group did not participate in the match
   PCRE2_ERROR_NOMEMORY      the buffer is too small
 
-
    
-
    
-
    
+
    
+
    
+
    
 There is a complete description of the PCRE2 native API in the
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2_substring_free.html b/doc/html/pcre2_substring_free.html
index e0d0fbda4..7a3c87b1f 100644
--- a/doc/html/pcre2_substring_free.html
+++ b/doc/html/pcre2_substring_free.html
@@ -15,22 +15,22 @@ 
    pcre2_substring_free man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 void pcre2_substring_free(PCRE2_UCHAR *buffer);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This is a convenience function for freeing the memory obtained by a previous
 call to pcre2_substring_get_byname() or
 pcre2_substring_get_bynumber(). Its only argument is a pointer to the
 string. If the argument is NULL, the function does nothing.
-
    
-
    
+
    
+
    
 There is a complete description of the PCRE2 native API in the
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2_substring_get_byname.html b/doc/html/pcre2_substring_get_byname.html
index a4b8771de..4ac9252bd 100644
--- a/doc/html/pcre2_substring_get_byname.html
+++ b/doc/html/pcre2_substring_get_byname.html
@@ -15,17 +15,17 @@ 
    pcre2_substring_get_byname man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_substring_get_byname(pcre2_match_data *match_data,
   PCRE2_SPTR name, PCRE2_UCHAR **bufferptr, PCRE2_SIZE *bufflen);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This is a convenience function for extracting a captured substring by name into
 newly acquired memory. The arguments are:
 
    @@ -48,8 +48,8 @@ 
    pcre2_substring_get_byname man page
    
 If there is more than one group with the given name, the first one that is set
 is returned. In this situation PCRE2_ERROR_UNSET means that no group with the
 given name was set.
-
    
-
    
+
    
+
    
 There is a complete description of the PCRE2 native API in the
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2_substring_get_bynumber.html b/doc/html/pcre2_substring_get_bynumber.html
index 391bc82b0..be05f7883 100644
--- a/doc/html/pcre2_substring_get_bynumber.html
+++ b/doc/html/pcre2_substring_get_bynumber.html
@@ -15,17 +15,17 @@ 
    pcre2_substring_get_bynumber man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_substring_get_bynumber(pcre2_match_data *match_data,
   uint32_t number, PCRE2_UCHAR **bufferptr, PCRE2_SIZE *bufflen);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This is a convenience function for extracting a captured substring by number
 into newly acquired memory. The arguments are:
 
    @@ -45,9 +45,9 @@ 
    pcre2_substring_get_bynumber man page
    
   PCRE2_ERROR_UNSET         the group did not participate in the match
   PCRE2_ERROR_NOMEMORY      memory could not be obtained
 
-
    
-
    
-
    
+
    
+
    
+
    
 There is a complete description of the PCRE2 native API in the
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2_substring_length_byname.html b/doc/html/pcre2_substring_length_byname.html
index 213bc949d..c734792c8 100644
--- a/doc/html/pcre2_substring_length_byname.html
+++ b/doc/html/pcre2_substring_length_byname.html
@@ -15,17 +15,17 @@ 
    pcre2_substring_length_byname man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_substring_length_byname(pcre2_match_data *match_data,
   PCRE2_SPTR name, PCRE2_SIZE *length);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This function returns the length of a matched substring, identified by name.
 The arguments are:
 
    @@ -34,8 +34,8 @@ 
    pcre2_substring_length_byname man page
    
   length       Where to return the length
 
    
 The yield is zero on success, or an error code if the substring is not found.
-
    
-
    
+
    
+
    
 There is a complete description of the PCRE2 native API in the
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2_substring_length_bynumber.html b/doc/html/pcre2_substring_length_bynumber.html
index db01cca41..11b0fbb0a 100644
--- a/doc/html/pcre2_substring_length_bynumber.html
+++ b/doc/html/pcre2_substring_length_bynumber.html
@@ -15,17 +15,17 @@ 
    pcre2_substring_length_bynumber man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_substring_length_bynumber(pcre2_match_data *match_data,
   uint32_t number, PCRE2_SIZE *length);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This function returns the length of a matched substring, identified by number.
 The arguments are:
 
    @@ -36,8 +36,8 @@ 
    pcre2_substring_length_bynumber man page
    
 The third argument may be NULL if all you want to know is whether or not a
 substring is set. The yield is zero on success, or a negative error code
 otherwise. After a partial match, only substring 0 is available.
-
    
-
    
+
    
+
    
 There is a complete description of the PCRE2 native API in the
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2_substring_list_free.html b/doc/html/pcre2_substring_list_free.html
index dea8bc588..1762b2ee7 100644
--- a/doc/html/pcre2_substring_list_free.html
+++ b/doc/html/pcre2_substring_list_free.html
@@ -15,22 +15,22 @@ 
    pcre2_substring_list_free man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 void pcre2_substring_list_free(PCRE2_UCHAR **list);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This is a convenience function for freeing the store obtained by a previous
 call to pcre2substring_list_get(). Its only argument is a pointer to
 the list of string pointers. If the argument is NULL, the function returns
 immediately, without doing anything.
-
    
-
    
+
    
+
    
 There is a complete description of the PCRE2 native API in the
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2_substring_list_get.html b/doc/html/pcre2_substring_list_get.html
index fd4362740..e2722f684 100644
--- a/doc/html/pcre2_substring_list_get.html
+++ b/doc/html/pcre2_substring_list_get.html
@@ -15,17 +15,17 @@ 
    pcre2_substring_list_get man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_substring_list_get(pcre2_match_data *match_data,
 "  PCRE2_UCHAR ***listptr, PCRE2_SIZE **lengthsptr);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This is a convenience function for extracting all the captured substrings after
 a pattern match. It builds a list of pointers to the strings, and (optionally)
 a second list that contains their lengths (in code units), excluding a
@@ -44,8 +44,8 @@ 
    pcre2_substring_list_get man page
    
 not NULL, a matching list of lengths is created, and its address is placed in
 lengthsptr. The yield of the function is zero on success or
 PCRE2_ERROR_NOMEMORY if sufficient memory could not be obtained.
-
    
-
    
+
    
+
    
 There is a complete description of the PCRE2 native API in the
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2_substring_nametable_scan.html b/doc/html/pcre2_substring_nametable_scan.html
index 277affae0..cf3041adf 100644
--- a/doc/html/pcre2_substring_nametable_scan.html
+++ b/doc/html/pcre2_substring_nametable_scan.html
@@ -15,17 +15,17 @@ 
    pcre2_substring_nametable_scan man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_substring_nametable_scan(const pcre2_code *code,
   PCRE2_SPTR name, PCRE2_SPTR *first, PCRE2_SPTR *last);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This convenience function finds, for a compiled pattern, the first and last
 entries for a given name in the table that translates capture group names into
 numbers.
@@ -40,8 +40,8 @@ 
    pcre2_substring_nametable_scan man page
    
 defined which one. Otherwise, when both pointers have been set, the yield of
 the function is the length of each entry in code units. If the name is not
 found, PCRE2_ERROR_NOSUBSTRING is returned.
-
    
-
    
+
    
+
    
 There is a complete description of the PCRE2 native API, including the format of
 the table entries, in the
 pcre2api
diff --git a/doc/html/pcre2_substring_number_from_name.html b/doc/html/pcre2_substring_number_from_name.html
index 160fbda66..47019b8bf 100644
--- a/doc/html/pcre2_substring_number_from_name.html
+++ b/doc/html/pcre2_substring_number_from_name.html
@@ -15,17 +15,17 @@ 
    pcre2_substring_number_from_name man page
    
 
    
 SYNOPSIS
 
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int pcre2_substring_number_from_name(const pcre2_code *code,
   PCRE2_SPTR name);
-
    
+
    
 
    
 DESCRIPTION
 
    
-
    
+
    
 This convenience function finds the number of a named substring capturing
 parenthesis in a compiled pattern, provided that it is a unique name. The
 function arguments are:
@@ -38,8 +38,8 @@ 
    pcre2_substring_number_from_name man page
    
 allowed (PCRE2_DUPNAMES is set), if the name is not unique,
 PCRE2_ERROR_NOUNIQUESUBSTRING is returned. You can obtain the list of numbers
 with the same name by calling pcre2_substring_nametable_scan().
-
    
-
    
+
    
+
    
 There is a complete description of the PCRE2 native API in the
 pcre2api
 page and a description of the POSIX API in the
diff --git a/doc/html/pcre2api.html b/doc/html/pcre2api.html
index 079cf176d..df7996e0d 100644
--- a/doc/html/pcre2api.html
+++ b/doc/html/pcre2api.html
@@ -57,7 +57,7 @@ 
    pcre2api man page
    
 
  • AUTHOR
 
  • REVISION
 
-
    
+
    
 #include <pcre2.h>
 
    
 
    
@@ -65,9 +65,9 @@ 
    pcre2api man page
    
 description of all its native functions. See the
 pcre2
 document for an overview of all the PCRE2 documentation.
-
    
+
    
 
    PCRE2 NATIVE API BASIC FUNCTIONS
    
-
    
+
    
 pcre2_code *pcre2_compile(PCRE2_SPTR pattern, PCRE2_SIZE length,
   uint32_t options, int *errorcode, PCRE2_SIZE *erroroffset,
   pcre2_compile_context *ccontext);
@@ -98,9 +98,9 @@ 
    pcre2api man page
    
 
    
 
    
 void pcre2_match_data_free(pcre2_match_data *match_data);
-
    
+
    
 
    PCRE2 NATIVE API AUXILIARY MATCH FUNCTIONS
    
-
    
+
    
 PCRE2_SPTR pcre2_get_mark(pcre2_match_data *match_data);
 
    
 
    
@@ -118,9 +118,9 @@ 
    pcre2api man page
    
 
    
 
    
 PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *match_data);
-
    
+
    
 
    PCRE2 NATIVE API GENERAL CONTEXT FUNCTIONS
    
-
    
+
    
 pcre2_general_context *pcre2_general_context_create(
   void *(*private_malloc)(PCRE2_SIZE, void *),
   void (*private_free)(void *, void *), void *memory_data);
@@ -131,9 +131,9 @@ 
    pcre2api man page
    
 
    
 
    
 void pcre2_general_context_free(pcre2_general_context *gcontext);
-
    
+
    
 
    PCRE2 NATIVE API COMPILE CONTEXT FUNCTIONS
    
-
    
+
    
 pcre2_compile_context *pcre2_compile_context_create(
   pcre2_general_context *gcontext);
 
    
@@ -183,9 +183,9 @@ 
    pcre2api man page
    
 
    
 int pcre2_set_optimize(pcre2_compile_context *ccontext,
   uint32_t directive);
-
    
+
    
 
    PCRE2 NATIVE API MATCH CONTEXT FUNCTIONS
    
-
    
+
    
 pcre2_match_context *pcre2_match_context_create(
   pcre2_general_context *gcontext);
 
    
@@ -228,9 +228,9 @@ 
    pcre2api man page
    
 
    
 int pcre2_set_depth_limit(pcre2_match_context *mcontext,
   uint32_t value);
-
    
+
    
 
    PCRE2 NATIVE API STRING EXTRACTION FUNCTIONS
    
-
    
+
    
 int pcre2_substring_copy_byname(pcre2_match_data *match_data,
   PCRE2_SPTR name, PCRE2_UCHAR *buffer, PCRE2_SIZE *bufflen);
 
    
@@ -273,18 +273,18 @@ 
    pcre2api man page
    
 
    
 int pcre2_substring_list_get(pcre2_match_data *match_data,
 "  PCRE2_UCHAR ***listptr, PCRE2_SIZE **lengthsptr);
-
    
+
    
 
    PCRE2 NATIVE API STRING SUBSTITUTION FUNCTION
    
-
    
+
    
 int pcre2_substitute(const pcre2_code *code, PCRE2_SPTR subject,
   PCRE2_SIZE length, PCRE2_SIZE startoffset,
   uint32_t options, pcre2_match_data *match_data,
   pcre2_match_context *mcontext, PCRE2_SPTR replacementz,
   PCRE2_SIZE rlength, PCRE2_UCHAR *outputbuffer,
   PCRE2_SIZE *outlengthptr);
-
    
+
    
 
    PCRE2 NATIVE API JIT FUNCTIONS
    
-
    
+
    
 int pcre2_jit_compile(pcre2_code *code, uint32_t options);
 
    
 
    
@@ -306,9 +306,9 @@ 
    pcre2api man page
    
 
    
 
    
 void pcre2_jit_stack_free(pcre2_jit_stack *jit_stack);
-
    
+
    
 
    PCRE2 NATIVE API SERIALIZATION FUNCTIONS
    
-
    
+
    
 int32_t pcre2_serialize_decode(pcre2_code **codes,
   int32_t number_of_codes, const uint8_t *bytes,
   pcre2_general_context *gcontext);
@@ -323,9 +323,9 @@ 
    pcre2api man page
    
 
    
 
    
 int32_t pcre2_serialize_get_number_of_codes(const uint8_t *bytes);
-
    
+
    
 
    PCRE2 NATIVE API AUXILIARY FUNCTIONS
    
-
    
+
    
 pcre2_code *pcre2_code_copy(const pcre2_code *code);
 
    
 
    
@@ -353,9 +353,9 @@ 
    pcre2api man page
    
 
    
 
    
 int pcre2_config(uint32_t what, void *where);
-
    
+
    
 
    PCRE2 NATIVE API OBSOLETE FUNCTIONS
    
-
    
+
    
 int pcre2_set_recursion_limit(pcre2_match_context *mcontext,
   uint32_t value);
 
    
@@ -370,9 +370,9 @@ 
    pcre2api man page
    
 backward compatibility. They should not be used in new code. The first is
 replaced by pcre2_set_depth_limit(); the second is no longer needed and
 has no effect (it always returns zero).
-
    
+
    
 
    PCRE2 EXPERIMENTAL PATTERN CONVERSION FUNCTIONS
    
-
    
+
    
 pcre2_convert_context *pcre2_convert_context_create(
   pcre2_general_context *gcontext);
 
    
@@ -406,9 +406,9 @@ 
    pcre2api man page
    
 POSIX basic and extended patterns can be converted. Details are given in the
 pcre2convert
 documentation.
-
    
+
    
 
    PCRE2 8-BIT, 16-BIT, AND 32-BIT LIBRARIES
    
-
    
+
    
 There are three PCRE2 libraries, supporting 8-bit, 16-bit, and 32-bit code
 units, respectively. However, there is just one header file, pcre2.h.
 This contains the function prototypes and other definitions for all three
@@ -431,14 +431,14 @@ 
    pcre2api man page
    
 For example, PCRE2_UCHAR16 is usually defined as `uint16_t'.
 The SPTR types are pointers to constants of the equivalent UCHAR types,
 that is, they are pointers to vectors of unsigned code units.
-
    
-
    
+
    
+
    
 Character strings are passed to a PCRE2 library as sequences of unsigned
 integers in code units of the appropriate width. The length of a string may
 be given as a number of code units, or the string may be specified as
 zero-terminated.
-
    
-
    
+
    
+
    
 Many applications use only one code unit width. For their convenience, macros
 are defined whose names are the generic forms such as pcre2_compile() and
 PCRE2_SPTR. These macros use the value of the macro PCRE2_CODE_UNIT_WIDTH to
@@ -446,53 +446,53 @@ 
    pcre2api man page
    
 PCRE2_CODE_UNIT_WIDTH is not defined by default. An application must define it
 to be 8, 16, or 32 before including pcre2.h in order to make use of the
 generic names.
-
    
-
    
+
    
+
    
 Applications that use more than one code unit width can be linked with more
 than one PCRE2 library, but must define PCRE2_CODE_UNIT_WIDTH to be 0 before
 including pcre2.h, and then use the real function names. Any code that is
 to be included in an environment where the value of PCRE2_CODE_UNIT_WIDTH is
 unknown should also use the real function names. (Unfortunately, it is not
 possible in C code to save and restore the value of a macro.)
-
    
-
    
+
    
+
    
 If PCRE2_CODE_UNIT_WIDTH is not defined before including pcre2.h, a
 compiler error occurs.
-
    
-
    
+
    
+
    
 When using multiple libraries in an application, you must take care when
 processing any particular pattern to use only functions from a single library.
 For example, if you want to run a match using a pattern that was compiled with
 pcre2_compile_16(), you must do so with pcre2_match_16(), not
 pcre2_match_8() or pcre2_match_32().
-
    
-
    
+
    
+
    
 In the function summaries above, and in the rest of this document and other
 PCRE2 documents, functions and data types are described using their generic
 names, without the _8, _16, or _32 suffix.
-
    
+
    
 
    PCRE2 API OVERVIEW
    
-
    
+
    
 PCRE2 has its own native API, which is described in this document. There are
 also some wrapper functions for the 8-bit library that correspond to the
 POSIX regular expression API, but they do not give access to all the
 functionality of PCRE2 and they are not thread-safe. They are described in the
 pcre2posix
 documentation. Both these APIs define a set of C function calls.
-
    
-
    
+
    
+
    
 The native API C data types, function prototypes, option values, and error
 codes are defined in the header file pcre2.h, which also contains
 definitions of PCRE2_MAJOR and PCRE2_MINOR, the major and minor release numbers
 for the library. Applications can use these to include support for different
 releases of PCRE2.
-
    
-
    
+
    
+
    
 In a Windows environment, if you want to statically link an application program
 against a non-dll PCRE2 library, you must define PCRE2_STATIC before including
 pcre2.h.
-
    
-
    
+
    
+
    
 The functions pcre2_compile() and pcre2_match() are used for
 compiling and matching regular expressions in a Perl-compatible manner. A
 sample program that demonstrates the simplest way of using them is provided in
@@ -502,36 +502,36 @@ 
    pcre2api man page
    
 documentation, and the
 pcre2sample
 documentation describes how to compile and run it.
-
    
-
    
+
    
+
    
 The compiling and matching functions recognize various options that are passed
 as bits in an options argument. There are also some more complicated parameters
 such as custom memory management functions and resource limits that are passed
 in "contexts" (which are just memory blocks, described below). Simple
 applications do not need to make use of contexts.
-
    
-
    
+
    
+
    
 Just-in-time (JIT) compiler support is an optional feature of PCRE2 that can be
 built in appropriate hardware environments. It greatly speeds up the matching
 performance of many patterns. Programs can request that it be used if
 available by calling pcre2_jit_compile() after a pattern has been
 successfully compiled by pcre2_compile(). This does nothing if JIT
 support is not available.
-
    
-
    
+
    
+
    
 More complicated programs might need to make use of the specialist functions
 pcre2_jit_stack_create(), pcre2_jit_stack_free(), and
 pcre2_jit_stack_assign() in order to control the JIT code's memory usage.
-
    
-
    
+
    
+
    
 JIT matching is automatically used by pcre2_match() if it is available,
 unless the PCRE2_NO_JIT option is set. There is also a direct interface for JIT
 matching, which gives improved performance at the expense of less sanity
 checking. The JIT-specific functions are discussed in the
 pcre2jit
 documentation.
-
    
-
    
+
    
+
    
 A second matching function, pcre2_dfa_match(), which is not
 Perl-compatible, is also provided. This uses a different algorithm for the
 matching. The alternative algorithm finds all possible matches (at a given
@@ -541,8 +541,8 @@ 
    pcre2api man page
    
 and disadvantages is given in the
 pcre2matching
 documentation. There is no JIT support for pcre2_dfa_match().
-
    
-
    
+
    
+
    
 In addition to the main compiling and matching functions, there are convenience
 functions for extracting captured substrings from a subject string that has
 been matched by pcre2_match(). They are:
@@ -561,28 +561,28 @@ 
    pcre2api man page
    
 provided, to free memory used for extracted strings. If either of these
 functions is called with a NULL argument, the function returns immediately
 without doing anything.
-
    
-
    
+
    
+
    
 The function pcre2_substitute() can be called to match a pattern and
 return a copy of the subject string with substitutions for parts that were
 matched.
-
    
-
    
+
    
+
    
 Functions whose names begin with pcre2_serialize_ are used for saving
 compiled patterns on disc or elsewhere, and reloading them later.
-
    
-
    
+
    
+
    
 Finally, there are functions for finding out information about a compiled
 pattern (pcre2_pattern_info()) and about the configuration with which
 PCRE2 was built (pcre2_config()).
-
    
-
    
+
    
+
    
 Functions with names ending with _free() are used for freeing memory
 blocks of various sorts. In all cases, if one of these functions is called with
 a NULL argument, it does nothing.
-
    
+
    
 
    STRING LENGTHS AND OFFSETS
    
-
    
+
    
 The PCRE2 API uses string lengths and offsets into strings of code units in
 several places. These values are always of type PCRE2_SIZE, which is an
 unsigned integer type, currently always defined as size_t. The largest
@@ -591,9 +591,9 @@ 
    pcre2api man page
    
 Therefore, the longest string that can be handled is one less than this
 maximum. Note that string lengths are always given in code units. Only in the
 8-bit library is such a length the same as the number of bytes in the string.
-
    
+
    
 
    NEWLINES
    
-
    
+
    
 PCRE2 supports five different conventions for indicating line breaks in
 strings: a single CR (carriage return) character, a single LF (linefeed)
 character, the two-character sequence CRLF, any of the three preceding, or any
@@ -601,8 +601,8 @@ 
    pcre2api man page
    
 mentioned, plus the single characters VT (vertical tab, U+000B), FF (form feed,
 U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS
 (paragraph separator, U+2029).
-
    
-
    
+
    
+
    
 Each of the first three conventions is used by at least one operating system as
 its standard newline sequence. When PCRE2 is built, a default can be specified.
 If it is not, the default is set to LF, which is the Unix standard. However,
@@ -611,8 +611,8 @@ 
    pcre2api man page
    
 the pattern itself; this overrides any other settings. See the
 pcre2pattern
 page for details of the special character sequences.
-
    
-
    
+
    
+
    
 In the PCRE2 documentation the word "newline" is used to mean "the character or
 pair of characters that indicate a line break". The choice of newline
 convention affects the handling of the dot, circumflex, and dollar
@@ -621,28 +621,28 @@ 
    pcre2api man page
    
 non-anchored pattern. There is more detail about this in the
 section on pcre2_match() options
 below.
-
    
-
    
+
    
+
    
 The choice of newline convention does not affect the interpretation of
 the \n or \r escape sequences, nor does it affect what \R matches; this has
 its own separate convention.
-
    
+
    
 
    MULTITHREADING
    
-
    
+
    
 In a multithreaded application it is important to keep thread-specific data
 separate from data that can be shared between threads. The PCRE2 library code
 itself is thread-safe: it contains no static or global variables. The API is
 designed to be fairly simple for non-threaded applications while at the same
 time ensuring that multithreaded applications can use it.
-
    
-
    
+
    
+
    
 There are several different blocks of data that are used to pass information
 between the application and the PCRE2 libraries.
-
    
+
    
 
    
 The compiled pattern
 
    
-
    
+
    
 A pointer to the compiled form of a pattern is returned to the user when
 pcre2_compile() is successful. The data in the compiled pattern is fixed,
 and does not change when the pattern is matched. Therefore, it is thread-safe,
@@ -653,8 +653,8 @@ 
    pcre2api man page
    
 stack areas for each thread. See the
 pcre2jit
 documentation for more details.
-
    
-
    
+
    
+
    
 In a more complicated situation, where patterns are compiled only when they are
 first needed, but are still shared between threads, pointers to compiled
 patterns must be protected from simultaneous writing by multiple threads. This
@@ -671,8 +671,8 @@ 
    pcre2api man page
    
   Use pointer in pcre2_match()
 
    • 
 Of course, testing for compilation errors should also be included in the code.
-
    
-
    
+
    
+
    
 The reason for checking the pointer a second time is as follows: Several
 threads may have acquired the shared lock and tested the pointer for being
 NULL, but only one of them will be given the write lock, with the rest kept
@@ -681,8 +681,8 @@ 
    pcre2api man page
    
 it does not retest pointer for being NULL, will recompile the pattern and
 overwrite the pointer, creating a memory leak and possibly causing other
 issues.
-
    
-
    
+
    
+
    
 In an environment where writing to a pointer may not be atomic, the above logic
 is not sufficient. The thread that is doing the compiling may be descheduled
 after writing only part of the pointer, which could cause other threads to use
@@ -709,11 +709,11 @@ 
    pcre2api man page
    
 pcre2_jit_compile(). Alternatively, pcre2_code_copy() or
 pcre2_code_copy_with_tables() can be used to obtain a private copy of the
 compiled code before calling the JIT compiler.
-
    
+
    
 
    
 Context blocks
 
    
-
    
+
    
 The next main section below introduces the idea of "contexts" in which PCRE2
 functions are called. A context is nothing more than a collection of parameters
 that control the way PCRE2 operates. Grouping a number of parameters together
@@ -721,24 +721,24 @@ 
    pcre2api man page
    
 using lots of arguments. The parameters that are stored in contexts are in some
 sense "advanced features" of the API. Many straightforward applications will
 not need to use contexts.
-
    
-
    
+
    
+
    
 In a multithreaded application, if the parameters in a context are values that
 are never changed, the same context can be used by all the threads. However, if
 any thread needs to change any value in a context, it must make its own
 thread-specific copy.
-
    
+
    
 
    
 Match blocks
 
    
-
    
+
    
 The matching functions need a block of memory for storing the results of a
 match. This includes details of what was matched, as well as additional
 information such as the name of a (*MARK) setting. Each thread must provide its
 own copy of this memory.
-
    
+
    
 
    PCRE2 CONTEXTS
    
-
    
+
    
 Some PCRE2 functions have a lot of parameters, many of which are used only by
 specialist applications, for example, those that use custom memory management
 or non-standard character tables. To keep function argument lists at a
@@ -747,15 +747,15 @@ 
    pcre2api man page
    
 directly. A context is just a block of memory that holds the parameter values.
 Applications that do not need to adjust any of the context parameters can pass
 NULL when a context pointer is required.
-
    
-
    
+
    
+
    
 There are three different types of context: a general context that is relevant
 for several PCRE2 operations, a compile-time context, and a match-time context.
-
    
+
    
 
    
 The general context
 
    
-
    
+
    
 At present, this context just contains pointers to (and data for) external
 memory management functions that are called from several places in the PCRE2
 library. The context is named `general' rather than specifically `memory'
@@ -782,13 +782,13 @@ 
    pcre2api man page
    
 there are no other fields in a general context, but in future there might be.)
 The private_malloc() function is used (if supplied) to obtain memory for
 storing the context, and all three values are saved as part of the context.
-
    
-
    
+
    
+
    
 Whenever PCRE2 creates a data block of any kind, the block contains a pointer
 to the free() function that matches the malloc() function that was
 used. When the time comes to free the block, this function is called.
-
    
-
    
+
    
+
    
 A general context can be copied by calling:
 
    
 
    
@@ -804,11 +804,11 @@ 
    pcre2api man page
    
 
    
 If this function is passed a NULL argument, it returns immediately without
 doing anything.
-
    
+
    
 
    
 The compile context
 
    
-
    
+
    
 A compile context is required if you want to provide an external function for
 stack checking during compilation or to change the default values of any of the
 following compile-time parameters:
@@ -824,8 +824,8 @@ 
    pcre2api man page
    
 A compile context is also required if you are using custom memory management.
 If none of these apply, just pass NULL as the context argument of
 pcre2_compile().
-
    
-
    
+
    
+
    
 A compile context is created, copied, and freed by the following functions:
 
    
 
    
@@ -922,14 +922,14 @@ 
    pcre2api man page
    
 sequence CR followed by LF), PCRE2_NEWLINE_ANYCRLF (any of the above),
 PCRE2_NEWLINE_ANY (any Unicode newline sequence), or PCRE2_NEWLINE_NUL (the
 NUL character, that is a binary zero).
-
    
-
    
+
    
+
    
 A pattern can override the value set in the compile context by starting with a
 sequence such as (*CRLF). See the
 pcre2pattern
 page for details.
-
    
-
    
+
    
+
    
 When a pattern is compiled with the PCRE2_EXTENDED or PCRE2_EXTENDED_MORE
 option, the newline convention affects the recognition of the end of internal
 comments starting with #. The value is saved with the compiled pattern for
@@ -958,8 +958,8 @@ 
    pcre2api man page
    
 that is called whenever pcre2_compile() starts to compile a parenthesized
 part of a pattern. This function can check the actual stack size (or anything
 else that it wants to, of course).
-
    
-
    
+
    
+
    
 The first argument to the callout function gives the current depth of
 nesting, and the second is user data that is set up by the last argument of
 pcre2_set_compile_recursion_guard(). The callout function should return
@@ -977,8 +977,8 @@ 
    pcre2api man page
    
 cases, one might wish to disable specific optimizations. For example, if it is
 known that some optimizations cannot benefit a certain regex, it might be
 desirable to disable them, in order to speed up compilation.
-
    
-
    
+
    
+
    
 The permitted values of directive are as follows:
 
       PCRE2_OPTIMIZATION_FULL
@@ -1009,8 +1009,8 @@ 
    pcre2api man page
    
 ^ items. Otherwise, the fact that any match must start either at the start of
 the subject or following a newline is remembered. Like other optimizations,
 this can cause callouts to be skipped.
-
    
-
    
+
    
+
    
 Dotstar anchor optimization is automatically disabled for .* if it is inside an
 atomic group or a capture group that is the subject of a backreference, or if
 the pattern contains (*PRUNE) or (*SKIP).
@@ -1029,13 +1029,13 @@ 
    pcre2api man page
    
 can cause them to be skipped if the pattern is never actually used. The start-up
 optimizations are in effect a pre-scan of the subject that takes place before
 the pattern is run.
-
    
-
    
+
    
+
    
 Disabling start-up optimizations ensures that in cases where the result is "no
 match", the callouts do occur, and that items such as (*COMMIT) and (*MARK) are
 considered at every possible starting position in the subject string.
-
    
-
    
+
    
+
    
 Disabling start-up optimizations may change the outcome of a matching operation.
 Consider the pattern
 
    @@ -1050,8 +1050,8 @@ 
    pcre2api man page
    
 string does not happen. The first match attempt is run starting from "D" and
 when this fails, (*COMMIT) prevents any further matches being tried, so the
 overall result is "no match".
-
    
-
    
+
    
+
    
 Another start-up optimization makes use of a minimum length for a matching
 subject, which is recorded when possible. Consider the pattern
 
    @@ -1068,11 +1068,11 @@ 
    pcre2api man page
    
 that is returned is "1". In this case, the optimizations do not affect the
 overall match result, which is still "no match", but they do affect the
 auxiliary information that is returned.
-
    
+
    
 
    
 The match context
 
    
-
    
+
    
 A match context is required if you want to:
 
       Set up a callout function
@@ -1084,8 +1084,8 @@ 
    pcre2api man page
    
 
    
 If none of these apply, just pass NULL as the context argument of
 pcre2_match(), pcre2_dfa_match(), or pcre2_jit_match().
-
    
-
    
+
    
+
    
 A match context is created, copied, and freed by the following functions:
 
    
 
    
@@ -1150,21 +1150,21 @@ 
    pcre2api man page
    
 PCRE2_ERROR_NOMATCH if a match with a starting point before or at the given
 offset is not found. The pcre2_substitute() function makes no more
 substitutions.
-
    
-
    
+
    
+
    
 For example, if the pattern /abc/ is matched against "123abc" with an offset
 limit less than 3, the result is PCRE2_ERROR_NOMATCH. A match can never be
 found if the startoffset argument of pcre2_match(),
 pcre2_dfa_match(), or pcre2_substitute() is greater than the offset
 limit set in the match context.
-
    
-
    
+
    
+
    
 When using this facility, you must set the PCRE2_USE_OFFSET_LIMIT option when
 calling pcre2_compile() so that when JIT is in use, different code can be
 compiled. If a match is started with a non-default match limit when
 PCRE2_USE_OFFSET_LIMIT is not set, an error is generated.
-
    
-
    
+
    
+
    
 The offset limit facility can be used to track progress when searching large
 subject strings or to limit the extent of global substitutions. See also the
 PCRE2_FIRSTLINE option, which requires a match to start before or at the first
@@ -1189,8 +1189,8 @@ 
    pcre2api man page
    
 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.
-
    
-
    
+
    
+
    
 A value for the heap limit may also be supplied by an item at the start of a
 pattern of the form
 
    @@ -1199,15 +1199,15 @@ 
    pcre2api man page
    
 where ddd is a decimal number. However, such a setting is ignored unless ddd is
 less than the limit set by the caller of pcre2_match() or, if no such
 limit is set, less than the default.
-
    
-
    
+
    
+
    
 The pcre2_match() function always needs some heap memory, so setting a
 value of zero guarantees a "heap limit exceeded" error. Details of how
 pcre2_match() uses the heap are given in the
 pcre2perform
 documentation.
-
    
-
    
+
    
+
    
 For pcre2_dfa_match(), 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
@@ -1222,8 +1222,8 @@ 
    pcre2api man page
    
 up too many computing resources 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.
-
    
-
    
+
    
+
    
 There is an internal counter in pcre2_match() that is incremented each
 time round its main matching loop. If this value reaches the match limit,
 pcre2_match() returns the negative value PCRE2_ERROR_MATCHLIMIT. This has
@@ -1231,16 +1231,16 @@ 
    pcre2api man page
    
 patterns that are not anchored, the count restarts from zero for each position
 in the subject string. This limit also applies to pcre2_dfa_match(),
 though the counting is done in a different way.
-
    
-
    
+
    
+
    
 When pcre2_match() is called with a pattern that was successfully
 processed by pcre2_jit_compile(), the way in which matching is executed
 is entirely different. However, there is still the possibility of runaway
 matching that goes on for a very long time, and so the match_limit value
 is also used in this case (but in a different way) to limit how long the
 matching can continue.
-
    
-
    
+
    
+
    
 The default value for the limit can be set when PCRE2 is built; the default is
 10 million, which handles all but the most extreme cases. A value for the match
 limit may also be supplied by an item at the start of a pattern of the form
@@ -1264,8 +1264,8 @@ 
    pcre2api man page
    
 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.
-
    
-
    
+
    
+
    
 The depth limit is not relevant, and is ignored, when matching is done using
 JIT compiled code. However, it is supported by pcre2_dfa_match(), which
 uses it to limit the depth of nested internal recursive function calls that
@@ -1275,8 +1275,8 @@ 
    pcre2api man page
    
 vectors for recursive function calls. From version 10.32, only local variables
 are allocated on the stack and as each call uses only a few hundred bytes, even
 a small stack can support quite a lot of recursion.
-
    
-
    
+
    
+
    
 If the depth of internal recursive function calls is great enough, local
 workspace vectors are allocated on the heap from version 10.32 onwards, so the
 depth limit also indirectly limits the amount of heap memory that is used. A
@@ -1284,8 +1284,8 @@ 
    pcre2api man page
    
 using pcre2_dfa_match(), can use a great deal of memory. However, it is
 probably better to limit heap usage directly by calling
 pcre2_set_heap_limit().
-
    
-
    
+
    
+
    
 The default value for the depth limit can be set when PCRE2 is built; if it is
 not, the default is set to the same value as the default for the match limit.
 If the limit is exceeded, pcre2_match() or pcre2_dfa_match()
@@ -1297,19 +1297,19 @@ 
    pcre2api man page
    
 where ddd is a decimal number. However, such a setting is ignored unless ddd is
 less than the limit set by the caller of pcre2_match() or
 pcre2_dfa_match() or, if no such limit is set, less than the default.
-
    
+
    
 
    CHECKING BUILD-TIME OPTIONS
    
-
    
+
    
 int pcre2_config(uint32_t what, void *where);
-
    
-
    
+
    
+
    
 The function pcre2_config() makes it possible for a PCRE2 client to find
 the value of certain configuration parameters and to discover which optional
 features have been compiled into the PCRE2 library. The
 pcre2build
 documentation has more details about these features.
-
    
-
    
+
    
+
    
 The first argument for pcre2_config() specifies which information is
 required. The second argument is a pointer to memory into which the information
 is placed. If NULL is passed, the function returns the amount of memory that is
@@ -1317,8 +1317,8 @@ 
    pcre2api man page
    
 the value is in bytes; when requesting these values, where should point
 to appropriately aligned memory. For calls that return strings, the required
 length is given in code units, not counting the terminating zero.
-
    
-
    
+
    
+
    
 When requesting information, the returned value from pcre2_config() is
 non-negative on success, or the negative error code PCRE2_ERROR_BADOPTION if
 the value in the first argument is not recognized. The following information is
@@ -1384,8 +1384,8 @@ 
    pcre2api man page
    
 compiled, a value of 3 is rounded up to 4, and when the 32-bit library is
 compiled, internal linkages always use 4 bytes, so the configured value is not
 relevant.
-
    
-
    
+
    
+
    
 The default value of 2 for the 8-bit and 16-bit libraries is sufficient for all
 but the most massive patterns, since it allows the size of the compiled pattern
 to be up to 65535 code units. Larger values allow larger regular expressions to
@@ -1461,9 +1461,9 @@ 
    pcre2api man page
    
 the PCRE2 version string, zero-terminated. The number of code units used is
 returned. This is the length of the string plus one unit for the terminating
 zero.
-
    
+
    
 
    COMPILING A PATTERN
    
-
    
+
    
 pcre2_code *pcre2_compile(PCRE2_SPTR pattern, PCRE2_SIZE length,
   uint32_t options, int *errorcode, PCRE2_SIZE *erroroffset,
   pcre2_compile_context *ccontext);
@@ -1476,8 +1476,8 @@ 
    pcre2api man page
    
 
    
 
    
 pcre2_code *pcre2_code_copy_with_tables(const pcre2_code *code);
-
    
-
    
+
    
+
    
 The pcre2_compile() function compiles a pattern into an internal form.
 The pattern is defined by a pointer to a string of code units and a length in
 code units. If the pattern is zero-terminated, the length can be specified as
@@ -1485,16 +1485,16 @@ 
    pcre2api man page
    
 as an empty string (NULL with a non-zero length causes an error return). The
 function returns a pointer to a block of memory that contains the compiled
 pattern and related data, or NULL if an error occurred.
-
    
-
    
+
    
+
    
 If the compile context argument ccontext is NULL, memory for the compiled
 pattern is obtained by calling malloc(). Otherwise, it is obtained from
 the same memory function that was used for the compile context. The caller must
 free the memory by calling pcre2_code_free() when it is no longer needed.
 If pcre2_code_free() is called with a NULL argument, it returns
 immediately, without doing anything.
-
    
-
    
+
    
+
    
 The function pcre2_code_copy() makes a copy of the compiled code in new
 memory, using the same memory allocator as was used for the original. However,
 if the code has been processed by the JIT compiler (see
@@ -1503,8 +1503,8 @@ 
    pcre2api man page
    
 The new copy can initially be used only for non-JIT matching, though it can be
 passed to pcre2_jit_compile() if required. If pcre2_code_copy() is
 called with a NULL argument, it returns NULL.
-
    
-
    
+
    
+
    
 The pcre2_code_copy() function provides a way for individual threads in a
 multithreaded application to acquire a private copy of shared compiled code.
 However, it does not make a copy of the character tables used by the compiled
@@ -1520,8 +1520,8 @@ 
    pcre2api man page
    
 pcre2_code_free() is called for the new copy of the compiled code. If
 pcre2_code_copy_with_tables() is called with a NULL argument, it returns
 NULL.
-
    
-
    
+
    
+
    
 NOTE: When one of the matching functions is called, pointers to the compiled
 pattern and the subject string are set in the match data block so that they can
 be referenced by the substring extraction functions after a successful match.
@@ -1532,8 +1532,8 @@ 
    pcre2api man page
    
 PCRE2_COPY_MATCHED_SUBJECT option, which is described in the section entitled
 "Option bits for pcre2_match()"
 below.
-
    
-
    
+
    
+
    
 The options argument for pcre2_compile() contains various bit
 settings that affect the compilation. It should be zero if none of them are
 required. The available options are described below. Some of them (in
@@ -1542,27 +1542,27 @@ 
    pcre2api man page
    
 the
 pcre2pattern
 documentation).
-
    
-
    
+
    
+
    
 For those options that can be different in different parts of the pattern, the
 contents of the options argument specifies their settings at the start of
 compilation. The PCRE2_ANCHORED, PCRE2_ENDANCHORED, and PCRE2_NO_UTF_CHECK
 options can be set at the time of matching as well as at compile time.
-
    
-
    
+
    
+
    
 Some additional options and less frequently required compile-time parameters
 (for example, the newline setting) can be provided in a compile context (as
 described
 above).
-
    
-
    
+
    
+
    
 If errorcode or erroroffset is NULL, pcre2_compile() 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 pcre2_compile() returns NULL because a compilation
 error has occurred.
-
    
-
    
+
    
+
    
 There are over 100 positive error codes that pcre2_compile() may return
 if it finds an error in the pattern. There are also some negative error codes
 that are used for invalid UTF strings when validity checking is in force. These
@@ -1578,8 +1578,8 @@ 
    pcre2api man page
    
 for both positive and negative error codes in pcre2.h. When compilation
 is successful errorcode is set to a value that returns the message "no
 error" if passed to pcre2_get_error_message().
-
    
-
    
+
    
+
    
 The value returned in erroroffset is an indication of where in the
 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
@@ -1587,14 +1587,14 @@ 
    pcre2api man page
    
 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.
-
    
-
    
+
    
+
    
 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
 offset is in code units, not characters, even in a UTF mode. It may sometimes
 point into the middle of a UTF-8 or UTF-16 character.
-
    
-
    
+
    
+
    
 This code fragment shows a typical straightforward call to
 pcre2_compile():
 
    @@ -1609,12 +1609,12 @@ 
    pcre2api man page
    
     &erroffset,             /* for error offset */
     NULL);                  /* no compile context */
 
-
    
-
    
+
    
+
    
 
    
 Main compile options
 
    
-
    
+
    
 The following names for option bits are defined in the pcre2.h header
 file:
 
    @@ -1637,25 +1637,25 @@ 
    pcre2api man page
    
 
    
 This option request alternative handling of three escape sequences, which
 makes PCRE2's behaviour more like ECMAscript (aka JavaScript). When it is set:
-
    
-
    
+
    
+
    
 (1) \U matches an upper case "U" character; by default \U causes a compile
 time error (Perl uses \U to upper case subsequent characters).
-
    
-
    
+
    
+
    
 (2) \u matches a lower case "u" character unless it is followed by four
 hexadecimal digits, in which case the hexadecimal number defines the code point
 to match. By default, \u causes a compile time error (Perl uses it to upper
 case the following character).
-
    
-
    
+
    
+
    
 (3) \x matches a lower case "x" character unless it is followed by two
 hexadecimal digits, in which case the hexadecimal number defines the code point
 to match. By default, as in Perl, a hexadecimal number is always expected after
 \x, but it may have zero, one, or two digits (so, for example, \xz matches a
 binary zero character followed by z).
-
    
-
    
+
    
+
    
 ECMAscript 6 added additional functionality to \u. This can be accessed using
 the PCRE2_EXTRA_ALT_BSUX extra option (see "Extra compile options"
 below).
@@ -1712,26 +1712,26 @@ 
    pcre2api man page
    
 PCRE2_UCP is set, Unicode properties are used for all characters with more than
 one other case, and for all characters whose code points are greater than
 U+007F.
-
    
-
    
+
    
+
    
 Note that there are two ASCII characters, K and S, that, in addition to
 their lower case ASCII equivalents, are case-equivalent with U+212A (Kelvin
 sign) and U+017F (long S) respectively. If you do not want this case
 equivalence, you can suppress it by setting PCRE2_EXTRA_CASELESS_RESTRICT.
-
    
-
    
+
    
+
    
 One language family, Turkish and Azeri, has its own case-insensitivity rules,
 which can be selected by setting PCRE2_EXTRA_TURKISH_CASING. This alters the
 behaviour of the 'i', 'I', U+0130 (capital I with dot above), and U+0131
 (small dotless i) characters.
-
    
-
    
+
    
+
    
 For lower valued characters with only one other case, a lookup table is used
 for speed. When neither PCRE2_UTF nor PCRE2_UCP is set, a lookup table is used
 for all code points less than 256, and higher code points (available only in
 16-bit or 32-bit mode) are treated as not having another case.
-
    
-
    
+
    
+
    
 From release 10.45 PCRE2_CASELESS also affects what some of the letter-related
 Unicode property escapes (\p and \P) match. The properties Lu (upper case
 letter), Ll (lower case letter), and Lt (title case letter) are all treated as
@@ -1783,8 +1783,8 @@ 
    pcre2api man page
    
 whereas the second matches "bc". The effect of PCRE2_ENDANCHORED can also be
 achieved by appropriate constructs in the pattern itself, which is the only way
 to do it in Perl.
-
    
-
    
+
    
+
    
 For DFA matching with pcre2_dfa_match(), PCRE2_ENDANCHORED applies only
 to the first (that is, the longest) matched string. Other parallel matches,
 which are necessarily substrings of the first one, must obviously end before
@@ -1800,8 +1800,8 @@ 
    pcre2api man page
    
 quantifier and between a quantifier and a following + that indicates
 possessiveness. PCRE2_EXTENDED is equivalent to Perl's /x option, and it can be
 changed within a pattern by a (?x) option setting.
-
    
-
    
+
    
+
    
 When PCRE2 is compiled without Unicode support, PCRE2_EXTENDED recognizes as
 white space only those characters with code points less than 256 that are
 flagged as white space in its low-character table. The table is normally
@@ -1811,8 +1811,8 @@ 
    pcre2api man page
    
 ASCII environments, the relevant characters are those with code points 0x0009
 (tab), 0x000A (linefeed), 0x000B (vertical tab), 0x000C (formfeed), 0x000D
 (carriage return), and 0x0020 (space).
-
    
-
    
+
    
+
    
 When PCRE2 is compiled with Unicode support, in addition to these characters,
 five more Unicode "Pattern White Space" characters are recognized by
 PCRE2_EXTENDED. These are U+0085 (next line), U+200E (left-to-right mark),
@@ -1820,16 +1820,16 @@ 
    pcre2api man page
    
 separator). This set of characters is the same as recognized by Perl's /x
 option. Note that the horizontal and vertical space characters that are matched
 by the \h and \v escapes in patterns are a much bigger set.
-
    
-
    
+
    
+
    
 As well as ignoring most white space, PCRE2_EXTENDED also causes characters
 between an unescaped # outside a character class and the next newline,
 inclusive, to be ignored, which makes it possible to include comments inside
 complicated patterns. Note that the end of this type of comment is a literal
 newline sequence in the pattern; escape sequences that happen to represent a
 newline do not count.
-
    
-
    
+
    
+
    
 Which characters are interpreted as newlines can be specified by a setting in
 the compile context that is passed to pcre2_compile() or by a special
 sequence at the start of the pattern, as described in the section entitled
@@ -1904,8 +1904,8 @@ 
    pcre2api man page
    
 (except when PCRE2_DOLLAR_ENDONLY is set). Note, however, that unless
 PCRE2_DOTALL is set, the "any character" metacharacter (.) does not match at a
 newline. This behaviour (for ^, $, and dot) is the same as Perl.
-
    
-
    
+
    
+
    
 When PCRE2_MULTILINE it is set, the "start of line" and "end of line"
 constructs match immediately following or immediately before internal newlines
 in the subject string, respectively, as well as at the very start and end. This
@@ -1962,8 +1962,8 @@ 
    pcre2api man page
    
 set this option if you want the matching functions to do a full unoptimized
 search and run all the callouts, but it is mainly provided for testing
 purposes.
-
    
-
    
+
    
+
    
 If a compile context is available, it is recommended to use
 pcre2_set_optimize() with the directive PCRE2_AUTO_POSSESS_OFF rather
 than the compile option PCRE2_NO_AUTO_POSSESS. Note that PCRE2_NO_AUTO_POSSESS
@@ -1992,16 +1992,16 @@ 
    pcre2api man page
    
 what pcre2_compile() generates, but it does affect the output of the JIT
 compiler. Setting this option is equivalent to calling pcre2_set_optimize()
 with the directive parameter set to PCRE2_START_OPTIMIZE_OFF.
-
    
-
    
+
    
+
    
 There are a number of optimizations that may occur at the start of a match, in
 order to speed up the process. For example, if it is known that an unanchored
 match must start with a specific code unit value, the matching code searches
 the subject for that value, and fails immediately if it cannot find it, without
 actually running the main matching function. The start-up optimizations are
 in effect a pre-scan of the subject that takes place before the pattern is run.
-
    
-
    
+
    
+
    
 Disabling the start-up optimizations may cause performance to suffer. However,
 this may be desirable for patterns which contain callouts or items such as
 (*COMMIT) and (*MARK). See the above description of PCRE2_START_OPTIMIZE_OFF
@@ -2019,19 +2019,19 @@ 
    pcre2api man page
    
 pcre2unicode
 document. If an invalid UTF sequence is found, pcre2_compile() returns a
 negative error code.
-
    
-
    
+
    
+
    
 If you know that your pattern is a valid UTF string, and you want to skip this
 check for performance reasons, you can set the PCRE2_NO_UTF_CHECK option. When
 it is set, the effect of passing an invalid UTF string as a pattern is
 undefined. It may cause your program to crash or loop.
-
    
-
    
+
    
+
    
 Note that this option can also be passed to pcre2_match() and
 pcre2_dfa_match(), to suppress UTF validity checking of the subject
 string.
-
    
-
    
+
    
+
    
 Note also that setting PCRE2_NO_UTF_CHECK at compile time does not disable the
 error that is given if an escape sequence for an invalid Unicode code point is
 encountered in the pattern. In particular, the so-called "surrogate" code
@@ -2054,14 +2054,14 @@ 
    pcre2api man page
    
 in the
 pcre2pattern
 page.
-
    
-
    
+
    
+
    
 The second effect of PCRE2_UCP is to force the use of Unicode properties for
 upper/lower casing operations, even when PCRE2_UTF is not set. This makes it
 possible to process strings in the 16-bit UCS-2 code. This option is available
 only if PCRE2 has been compiled with Unicode support (which is the default).
-
    
-
    
+
    
+
    
 The PCRE2_EXTRA_CASELESS_RESTRICT option (see above) restricts caseless
 matching such that ASCII characters match only ASCII characters and non-ASCII
 characters match only non-ASCII characters. The PCRE2_EXTRA_TURKISH_CASING option
@@ -2098,11 +2098,11 @@ 
    pcre2api man page
    
 behaviour of PCRE2 are given in the
 pcre2unicode
 page. In particular, note that it changes the way PCRE2_CASELESS works.
-
    
+
    
 
    
 Extra compile options
 
    
-
    
+
    
 The option bits that can be set in a compile context by calling the
 pcre2_set_compile_extra_options() function are as follows:
 
    @@ -2122,16 +2122,16 @@ 
    pcre2api man page
    
 therefore be represented in UTF-16. They can be represented in UTF-8 and
 UTF-32, but are defined as invalid code points, and cause errors if encountered
 in a UTF-8 or UTF-32 string that is being checked for validity by PCRE2.
-
    
-
    
+
    
+
    
 These values also cause errors if encountered in escape sequences such as
 \x{d912} within a pattern. However, it seems that some applications, when
 using PCRE2 to check for unwanted characters in UTF-8 strings, explicitly test
 for the surrogates using escape sequences. The PCRE2_NO_UTF_CHECK option does
 not disable the error that occurs, because it applies only to the testing of
 input strings for UTF validity.
-
    
-
    
+
    
+
    
 If the extra option PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES is set, surrogate code
 point values in UTF-8 and UTF-32 patterns no longer provoke errors and are
 incorporated in the compiled pattern. However, they can only match subject
@@ -2185,8 +2185,8 @@ 
    pcre2api man page
    
 digits in \x{} are just ignored, though warnings are given in both cases if
 Perl's warning switch is enabled. However, a malformed octal number after \o{
 always causes an error in Perl.
-
    
-
    
+
    
+
    
 If the PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL extra option is passed to
 pcre2_compile(), all unrecognized or malformed escape sequences are
 treated as single-character escapes. For example, \j is a literal "j" and
@@ -2262,9 +2262,9 @@ 
    pcre2api man page
    
 a pattern by the (*TURKISH_CASING) start-of-pattern setting. Either the UTF or
 UCP options must be set. In the 8-bit library, UTF must be set. This option
 cannot be combined with PCRE2_EXTRA_CASELESS_RESTRICT.
-
    
+
    
 
    JUST-IN-TIME (JIT) COMPILATION
    
-
    
+
    
 int pcre2_jit_compile(pcre2_code *code, uint32_t options);
 
    
 
    
@@ -2286,37 +2286,37 @@ 
    pcre2api man page
    
 
    
 
    
 void pcre2_jit_stack_free(pcre2_jit_stack *jit_stack);
-
    
-
    
+
    
+
    
 These functions provide support for JIT compilation, which, if the just-in-time
 compiler is available, further processes a compiled pattern into machine code
 that executes much faster than the pcre2_match() interpretive matching
 function. Full details are given in the
 pcre2jit
 documentation.
-
    
-
    
+
    
+
    
 JIT compilation is a heavyweight optimization. It can take some time for
 patterns to be analyzed, and for one-off matches and simple patterns the
 benefit of faster execution might be offset by a much slower compilation time.
 Most (but not all) patterns can be optimized by the JIT compiler.
-
    
+
    
 
    LOCALE SUPPORT
    
-
    
+
    
 const uint8_t *pcre2_maketables(pcre2_general_context *gcontext);
 
    
 
    
 void pcre2_maketables_free(pcre2_general_context *gcontext,
   const uint8_t *tables);
-
    
-
    
+
    
+
    
 PCRE2 handles caseless matching, and determines whether characters are letters,
 digits, or whatever, by reference to a set of tables, indexed by character code
 point. However, this applies only to characters whose code points are less than
 256. By default, higher-valued code points never match escapes such as \w or
 \d.
-
    
-
    
+
    
+
    
 When PCRE2 is built with Unicode support (the default), certain Unicode
 character properties can be tested with \p and \P, or, alternatively, the
 PCRE2_UCP option can be set when a pattern is compiled; this causes \w and
@@ -2325,34 +2325,34 @@ 
    pcre2api man page
    
 points greater than 127 to use Unicode properties. These effects apply even
 when PCRE2_UTF is not set. There are, however, some PCRE2_EXTRA options (see
 above) that can be used to modify or suppress them.
-
    
-
    
+
    
+
    
 The use of locales with Unicode is discouraged. If you are handling characters
 with code points greater than 127, you should either use Unicode support, or
 use locales, but not try to mix the two.
-
    
-
    
+
    
+
    
 PCRE2 contains a built-in set of character tables that are used by default.
 These are sufficient for many applications. Normally, the internal tables
 recognize only ASCII characters. However, when PCRE2 is built, it is possible
 to cause the internal tables to be rebuilt in the default "C" locale of the
 local system, which may cause them to be different.
-
    
-
    
-The built-in tables can be overridden by tables supplied by the application
+
    
+
    
+The built-in tables can be overridden by tables supplied by the application
 that calls PCRE2. These may be created in a different locale from the default.
 As more and more applications change to using Unicode, the need for this locale
 support is expected to die away.
-
    
-
    
+
    
+
    
 External tables are built by calling the pcre2_maketables() function, in
 the relevant locale. The only argument to this function is a general context,
 which can be used to pass a custom memory allocator. If the argument is NULL,
 the system malloc() is used. The result can be passed to
 pcre2_compile() as often as necessary, by creating a compile context and
 calling pcre2_set_character_tables() to set the tables pointer therein.
-
    
-
    
+
    
+
    
 For example, to build and use tables that are appropriate for the French locale
 (where accented characters with values greater than 127 are treated as
 letters), the following code could be used:
@@ -2365,25 +2365,25 @@ 
    pcre2api man page
    
 
    
 The locale name "fr_FR" is used on Linux and other Unix-like systems; if you
 are using Windows, the name for the French locale is "french".
-
    
-
    
+
    
+
    
 The pointer that is passed (via the compile context) to pcre2_compile()
 is saved with the compiled pattern, and the same tables are used by the
 matching functions. Thus, for any single pattern, compilation and matching both
 happen in the same locale, but different patterns can be processed in different
 locales.
-
    
-
    
+
    
+
    
 It is the caller's responsibility to ensure that the memory containing the
 tables remains available while they are still in use. When they are no longer
 needed, you can discard them using pcre2_maketables_free(), which should
 pass as its first parameter the same global context that was used to create the
 tables.
-
    
+
    
 
    
 Saving locale tables
 
    
-
    
+
    
 The tables described above are just a sequence of binary bytes, which makes
 them independent of hardware characteristics such as endianness or whether the
 processor is 32-bit or 64-bit. A copy of the result of pcre2_maketables()
@@ -2396,12 +2396,12 @@ 
    pcre2api man page
    
 a set of binary tables. See the
 pcre2build
 documentation for details.
-
    
+
    
 
    INFORMATION ABOUT A COMPILED PATTERN
    
-
    
+
    
 int pcre2_pattern_info(const pcre2 *code, uint32_t what, void *where);
-
    
-
    
+
    
+
    
 The pcre2_pattern_info() function returns general information about a
 compiled pattern. For information about callouts, see the
 next section.
@@ -2443,15 +2443,15 @@ 
    pcre2api man page
    
 (*UTF) at the start of the pattern itself. PCRE2_INFO_EXTRAOPTIONS returns the
 extra options that were set in the compile context by calling the
 pcre2_set_compile_extra_options() function.
-
    
-
    
+
    
+
    
 For example, if the pattern /(*UTF)abc/ is compiled with the PCRE2_EXTENDED
 option, the result for PCRE2_INFO_ALLOPTIONS is PCRE2_EXTENDED and PCRE2_UTF.
 Option settings such as (?i) that can change within a pattern do not affect the
 result of PCRE2_INFO_ALLOPTIONS, even if they appear right at the start of the
 pattern. (This was different in some earlier releases.)
-
    
-
    
+
    
+
    
 A pattern compiled without PCRE2_ANCHORED is automatically anchored by PCRE2 if
 the first significant item in every top-level branch is one of the following:
 
    @@ -2621,8 +2621,8 @@ 
    pcre2api man page
    
 and cause PCRE2_INFO_MAXLOOKBEHIND to return 1 in the absence of anything
 longer. \A also registers a one-character lookbehind, though it does not
 actually inspect the previous character.
-
    
-
    
+
    
+
    
 Note that this information is useful for multi-segment matching only
 if the pattern contains no nested lookbehinds. For example, the pattern
 (?<=a(?<=ba)c) returns a maximum lookbehind of 2, but when it is processed, the
@@ -2656,14 +2656,14 @@ 
    pcre2api man page
    
 output vector (described with pcre2_match() below). To do the conversion,
 you need to use the name-to-number map, which is described by these three
 values.
-
    
-
    
+
    
+
    
 The map consists of a number of fixed-size entries. PCRE2_INFO_NAMECOUNT gives
 the number of entries, and PCRE2_INFO_NAMEENTRYSIZE gives the size of each
 entry in code units; both of these return a uint32_t value. The entry
 size depends on the length of the longest name.
-
    
-
    
+
    
+
    
 PCRE2_INFO_NAMETABLE returns a pointer to the first entry of the table. This is
 a PCRE2_SPTR pointer to a block of code units. In the 8-bit library, the first
 two bytes of each entry are the number of the capturing parenthesis, most
@@ -2672,8 +2672,8 @@ 
    pcre2api man page
    
 library, the pointer points to 32-bit code units, the first of which contains
 the parenthesis number. The rest of the entry is the corresponding name, zero
 terminated.
-
    
-
    
+
    
+
    
 The names are in alphabetical order. If (?| is used to create multiple capture
 groups with the same number, as described in the
 section on duplicate group numbers
@@ -2681,15 +2681,15 @@ 
    pcre2api man page
    
 pcre2pattern
 page, the groups may be given the same name, but there is only one entry in the
 table. Different names for groups of the same number are not permitted.
-
    
-
    
+
    
+
    
 Duplicate names for capture groups with different numbers are permitted, but
 only if PCRE2_DUPNAMES is set. They appear in the table in the order in which
 they were found in the pattern. In the absence of (?| this is the order of
 increasing number; when (?| is used this is not necessarily the case because
 later capture groups may have lower numbers.
-
    
-
    
+
    
+
    
 As a simple example of the name/number table, consider the following pattern
 after compilation by the 8-bit library (assume PCRE2_EXTENDED is set, so white
 space - including newlines - is ignored):
@@ -2733,9 +2733,9 @@ 
    pcre2api man page
    
 value returned by this option, because there are cases where the code that
 calculates the size has to over-estimate. Processing a pattern with the JIT
 compiler does not alter the value returned by this option.
-
    
+
    
 
    INFORMATION ABOUT A PATTERN'S CALLOUTS
    
-
    
+
    
 int pcre2_callout_enumerate(const pcre2_code *code,
   int (*callback)(pcre2_callout_enumerate_block *, void *),
   void *user_data);
@@ -2752,9 +2752,9 @@ 
    pcre2api man page
    
 contents of the callout enumeration block are described in the
 pcre2callout
 documentation, which also gives further details about callouts.
-
    
+
    
 
    SERIALIZATION AND PRECOMPILING
    
-
    
+
    
 It is possible to save compiled patterns on disc or elsewhere, and reload them
 later, subject to a number of restrictions. The host on which the patterns are
 reloaded must be running the same version of PCRE2, with the same code unit
@@ -2766,9 +2766,9 @@ 
    pcre2api man page
    
 pcre2serialize
 documentation. Note that PCRE2 serialization does not convert compiled patterns
 to an abstract format like Java or .NET serialization.
-
    
+
    
 
    THE MATCH DATA BLOCK
    
-
    
+
    
 pcre2_match_data *pcre2_match_data_create(uint32_t ovecsize,
   pcre2_general_context *gcontext);
 
    
@@ -2778,46 +2778,46 @@ 
    pcre2api man page
    
 
    
 
    
 void pcre2_match_data_free(pcre2_match_data *match_data);
-
    
-
    
+
    
+
    
 Information about a successful or unsuccessful match is placed in a match
 data block, which is an opaque structure that is accessed by function calls. In
 particular, the match data block contains a vector of offsets into the subject
 string that define the matched parts of the subject. This is known as the
 ovector.
-
    
-
    
+
    
+
    
 Before calling pcre2_match(), pcre2_dfa_match(), or
 pcre2_jit_match() you must create a match data block by calling one of
 the creation functions above. For pcre2_match_data_create(), the first
 argument is the number of pairs of offsets in the ovector.
-
    
-
    
+
    
+
    
 When using pcre2_match(), one pair of offsets is required to identify the
 string that matched the whole pattern, with an additional pair for each
 captured substring. For example, a value of 4 creates enough space to record
 the matched portion of the subject plus three captured substrings.
-
    
-
    
+
    
+
    
 When using pcre2_dfa_match() there may be multiple matched substrings of
 different lengths at the same point in the subject. The ovector should be made
 large enough to hold as many as are expected.
-
    
-
    
+
    
+
    
 A minimum of at least 1 pair is imposed by pcre2_match_data_create(), so
 it is always possible to return the overall matched string in the case of
 pcre2_match() or the longest match in the case of
 pcre2_dfa_match(). The maximum number of pairs is 65535; if the first
 argument of pcre2_match_data_create() is greater than this, 65535 is
 used.
-
    
-
    
+
    
+
    
 The second argument of pcre2_match_data_create() is a pointer to a
 general context, which can specify custom memory management for obtaining the
 memory for the match data block. If you are not using custom memory management,
 pass NULL, which causes malloc() to be used.
-
    
-
    
+
    
+
    
 For pcre2_match_data_create_from_pattern(), the first argument is a
 pointer to a compiled pattern. The ovector is created to be exactly the right
 size to hold all the substrings a pattern might capture when matched using
@@ -2825,8 +2825,8 @@ 
    pcre2api man page
    
 pcre2_dfa_match(). The second argument is again a pointer to a general
 context, but in this case if NULL is passed, the memory is obtained using the
 same allocator that was used for the compiled pattern (custom or default).
-
    
-
    
+
    
+
    
 A match data block can be used many times, with the same or different compiled
 patterns. You can extract information from a match data block after a match
 operation has finished, using functions that are described in the sections on
@@ -2834,14 +2834,14 @@ 
    pcre2api man page
    
 and
 other match data
 below.
-
    
-
    
+
    
+
    
 When a call of pcre2_match() fails, valid data is available in the match
 block only when the error is PCRE2_ERROR_NOMATCH, PCRE2_ERROR_PARTIAL, or one
 of the error codes for an invalid UTF string. Exactly what is available depends
 on the error, and is detailed below.
-
    
-
    
+
    
+
    
 When one of the matching functions is called, pointers to the compiled pattern
 and the subject string are set in the match data block so that they can be
 referenced by the extraction functions after a successful match. After running
@@ -2851,26 +2851,26 @@ 
    pcre2api man page
    
 PCRE2_COPY_MATCHED_SUBJECT option, which is described in the section entitled
 "Option bits for pcre2_match()"
 below.
-
    
-
    
+
    
+
    
 When a match data block itself is no longer needed, it should be freed by
 calling pcre2_match_data_free(). If this function is called with a NULL
 argument, it returns immediately, without doing anything.
-
    
+
    
 
    MEMORY USE FOR MATCH DATA BLOCKS
    
-
    
+
    
 PCRE2_SIZE pcre2_get_match_data_size(pcre2_match_data *match_data);
 
    
 
    
 PCRE2_SIZE pcre2_get_match_data_heapframes_size(
   pcre2_match_data *match_data);
-
    
-
    
+
    
+
    
 The size of a match data block depends on the size of the ovector that it
 contains. The function pcre2_get_match_data_size() returns the size, in
 bytes, of the block that is its argument.
-
    
-
    
+
    
+
    
 When pcre2_match() runs interpretively (that is, without using JIT), it
 makes use of a vector of data frames for remembering backtracking positions.
 The size of each individual frame depends on the number of capturing
@@ -2878,44 +2878,44 @@ 
    pcre2api man page
    
 pcre2_pattern_info() with the PCRE2_INFO_FRAMESIZE option (see the
 section entitled "Information about a compiled pattern"
 above).
-
    
-
    
+
    
+
    
 Heap memory is used for the frames vector; if the initial memory block turns
 out to be too small during matching, it is automatically expanded. When
 pcre2_match() returns, the memory is not freed, but remains attached to
 the match data block, for use by any subsequent matches that use the same
 block. It is automatically freed when the match data block itself is freed.
-
    
-
    
+
    
+
    
 You can find the current size of the frames vector that a match data block owns
 by calling pcre2_get_match_data_heapframes_size(). For a newly created
 match data block the size will be zero. Some types of match may require a lot
 of frames and thus a large vector; applications that run in environments where
 memory is constrained can check this and free the match data block if the heap
 frames vector has become too big.
-
    
+
    
 
    MATCHING A PATTERN: THE TRADITIONAL FUNCTION
    
-
    
+
    
 int pcre2_match(const pcre2_code *code, PCRE2_SPTR subject,
   PCRE2_SIZE length, PCRE2_SIZE startoffset,
   uint32_t options, pcre2_match_data *match_data,
   pcre2_match_context *mcontext);
-
    
-
    
+
    
+
    
 The function pcre2_match() is called to match a subject string against a
 compiled pattern, which is passed in the code argument. You can call
 pcre2_match() with the same code argument as many times as you
 like, in order to find multiple matches in the subject string or to match
 different subject strings with the same pattern.
-
    
-
    
+
    
+
    
 This function is the main matching facility of the library, and it operates in
 a Perl-like manner. For specialist use there is also an alternative matching
 function, which is described
 below
 in the section about the pcre2_dfa_match() function.
-
    
-
    
+
    
+
    
 Here is an example of a simple call to pcre2_match():
 
       pcre2_match_data *md = pcre2_match_data_create(4, NULL);
@@ -2933,11 +2933,11 @@ 
    pcre2api man page
    
 matching parameters are to be changed. For details, see the section on
 the match context
 above.
-
    
+
    
 
    
 The string to be matched by pcre2_match()
 
    
-
    
+
    
 The subject string is passed to pcre2_match() as a pointer in
 subject, a length in length, and a starting offset in
 startoffset. The length and offset are in code units, not characters.
@@ -2946,8 +2946,8 @@ 
    pcre2api man page
    
 UTF processing is enabled. As a special case, if subject is NULL and
 length is zero, the subject is assumed to be an empty string. If
 length is non-zero, an error occurs if subject is NULL.
-
    
-
    
+
    
+
    
 If startoffset is greater than the length of the subject,
 pcre2_match() returns PCRE2_ERROR_BADOFFSET. When the starting offset is
 zero, the search for a match starts at the beginning of the subject, and this
@@ -2955,8 +2955,8 @@ 
    pcre2api man page
    
 must point to the start of a character, or to the end of the subject (in UTF-32
 mode, one code unit equals one character, so all offsets are valid). Like the
 pattern string, the subject may contain binary zeros.
-
    
-
    
+
    
+
    
 A non-zero starting offset is useful when searching for another match in the
 same subject by calling pcre2_match() again after a previous success.
 Setting startoffset differs from passing over a shortened string and
@@ -2975,8 +2975,8 @@ 
    pcre2api man page
    
 startoffset set to 4, it finds the second occurrence of "iss" because it
 is able to look behind the starting point to discover that it is preceded by a
 letter.
-
    
-
    
+
    
+
    
 Finding all the matches in a subject is tricky when the pattern can match an
 empty string. It is possible to emulate Perl's /g behaviour by first trying the
 match again at the same offset, with the PCRE2_NOTEMPTY_ATSTART and
@@ -2988,26 +2988,26 @@ 
    pcre2api man page
    
 newline convention recognizes CRLF as a newline, and if so, and the current
 character is CR followed by LF, advance the starting offset by two characters
 instead of one.
-
    
-
    
+
    
+
    
 If a non-zero starting offset is passed when the pattern is anchored, a single
 attempt to match at the given offset is made. This can only succeed if the
 pattern does not require the match to be at the start of the subject. In other
 words, the anchoring must be the result of setting the PCRE2_ANCHORED option or
 the use of .* with PCRE2_DOTALL, not by starting the pattern with ^ or \A.
-
    
+
    
 
    
 Option bits for pcre2_match()
 
    
-
    
+
    
 The unused bits of the options argument for pcre2_match() must be
 zero. The only bits that may be set are PCRE2_ANCHORED,
 PCRE2_COPY_MATCHED_SUBJECT, PCRE2_DISABLE_RECURSELOOP_CHECK, PCRE2_ENDANCHORED,
 PCRE2_NOTBOL, PCRE2_NOTEOL, PCRE2_NOTEMPTY, PCRE2_NOTEMPTY_ATSTART,
 PCRE2_NO_JIT, PCRE2_NO_UTF_CHECK, PCRE2_PARTIAL_HARD, and PCRE2_PARTIAL_SOFT.
 Their action is described below.
-
    
-
    
+
    
+
    
 Setting PCRE2_ANCHORED or PCRE2_ENDANCHORED at match time is not supported by
 the just-in-time (JIT) compiler. If it is set, JIT matching is disabled and the
 interpretive code in pcre2_match() is run.
@@ -3042,8 +3042,8 @@ 
    pcre2api man page
    
 
    
 This option is relevant only to pcre2_match() for interpretive matching.
 It is ignored when JIT is used, and is forbidden for pcre2_dfa_match().
-
    
-
    
+
    
+
    
 The use of recursion in patterns can lead to infinite loops. In the
 interpretive matcher these would be eventually caught by the match or heap
 limits, but this could take a long time and/or use a lot of memory if the
@@ -3051,8 +3051,8 @@ 
    pcre2api man page
    
 If the same group is still active from a previous call, and the current subject
 pointer is the same as it was at the start of that group, and the furthest
 inspected character of the subject has not changed, an error is generated.
-
    
-
    
+
    
+
    
 There are rare cases of matches that would complete, but nevertheless trigger
 this error. This option disables the check. It is provided mainly for testing
 when comparing JIT and interpretive behaviour.
@@ -3116,8 +3116,8 @@ 
    pcre2api man page
    
 case is discussed in detail in the
 pcre2unicode
 documentation.
-
    
-
    
+
    
+
    
 In the default case, if a non-zero starting offset is given, the check is
 applied only to that part of the subject that could be inspected during
 matching, and there is a check that the starting offset points to the first
@@ -3127,8 +3127,8 @@ 
    pcre2api man page
    
 starting offset, or at the start of the subject if there are not that many
 characters before the starting offset. Note that the sequences \b and \B are
 one-character lookbehinds.
-
    
-
    
+
    
+
    
 The check is carried out before any other processing takes place, and a
 negative error code is returned if the check fails. There are several UTF error
 codes for each code unit width, corresponding to different problems with the
@@ -3140,15 +3140,15 @@ 
    pcre2api man page
    
 in the
 pcre2unicode
 documentation.
-
    
-
    
+
    
+
    
 If you know that your subject is valid, and you want to skip this check for
 performance reasons, you can set the PCRE2_NO_UTF_CHECK option when calling
 pcre2_match(). You might want to do this for the second and subsequent
 calls to pcre2_match() if you are making repeated calls to find multiple
 matches in the same subject string.
-
    
-
    
+
    
+
    
 Warning: Unless PCRE2_MATCH_INVALID_UTF was set at compile time, when
 PCRE2_NO_UTF_CHECK is set at match time the effect of passing an invalid
 string as a subject, or an invalid value of startoffset, is undefined.
@@ -3162,30 +3162,30 @@ 
    pcre2api man page
    
 subject characters to complete the match. In addition, either at least one
 character must have been inspected or the pattern must contain a lookbehind, or
 the pattern must be one that could match an empty string.
-
    
-
    
+
    
+
    
 If this situation arises when PCRE2_PARTIAL_SOFT (but not PCRE2_PARTIAL_HARD)
 is set, matching continues by testing any remaining alternatives. Only if no
 complete match can be found is PCRE2_ERROR_PARTIAL returned instead of
 PCRE2_ERROR_NOMATCH. In other words, PCRE2_PARTIAL_SOFT specifies that the
 caller is prepared to handle a partial match, but only if no complete match can
 be found.
-
    
-
    
+
    
+
    
 If PCRE2_PARTIAL_HARD is set, it overrides PCRE2_PARTIAL_SOFT. In this case, if
 a partial match is found, pcre2_match() immediately returns
 PCRE2_ERROR_PARTIAL, without considering any other alternatives. In other
 words, when PCRE2_PARTIAL_HARD is set, a partial match is considered to be more
 important that an alternative complete match.
-
    
-
    
+
    
+
    
 There is a more detailed discussion of partial and multi-segment matching, with
 examples, in the
 pcre2partial
 documentation.
-
    
+
    
 
    NEWLINE HANDLING WHEN MATCHING
    
-
    
+
    
 When PCRE2 is built, a default newline convention is set; this is usually the
 standard convention for the operating system. The default can be overridden in
 a
@@ -3198,40 +3198,40 @@ 
    pcre2api man page
    
 page. During matching, the newline choice affects the behaviour of the dot,
 circumflex, and dollar metacharacters. It may also alter the way the match
 starting position is advanced after a match failure for an unanchored pattern.
-
    
-
    
+
    
+
    
 When PCRE2_NEWLINE_CRLF, PCRE2_NEWLINE_ANYCRLF, or PCRE2_NEWLINE_ANY is set as
 the newline convention, and a match attempt for an unanchored pattern fails
 when the current starting position is at a CRLF sequence, and the pattern
 contains no explicit matches for CR or LF characters, the match position is
 advanced by two characters instead of one, in other words, to after the CRLF.
-
    
-
    
+
    
+
    
 The above rule is a compromise that makes the most common cases work as
 expected. For example, if the pattern is .+A (and the PCRE2_DOTALL option is
 not set), it does not match the string "\r\nA" because, after failing at the
 start, it skips both the CR and the LF before retrying. However, the pattern
 [\r\n]A does match that string, because it contains an explicit CR or LF
 reference, and so advances only by one character after the first failure.
-
    
-
    
+
    
+
    
 An explicit match for CR of LF is either a literal appearance of one of those
 characters in the pattern, or one of the \r or \n or equivalent octal or
 hexadecimal escape sequences. Implicit matches such as [^X] do not count, nor
 does \s, even though it includes CR and LF in the characters that it matches.
-
    
-
    
+
    
+
    
 Notwithstanding the above, anomalous effects may still occur when CRLF is a
 valid newline sequence and explicit \r or \n escapes appear in the pattern.
-
    
+
    
 
    HOW PCRE2_MATCH() RETURNS A STRING AND CAPTURED SUBSTRINGS
    
-
    
+
    
 uint32_t pcre2_get_ovector_count(pcre2_match_data *match_data);
 
    
 
    
 PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *match_data);
-
    
-
    
+
    
+
    
 In general, a pattern matches a certain portion of the subject, and in
 addition, further substrings from the subject may be picked out by
 parenthesized parts of the pattern. Following the usage in Jeffrey Friedl's
@@ -3241,15 +3241,15 @@ 
    pcre2api man page
    
 not cause substrings to be captured. The pcre2_pattern_info() function
 can be used to find out how many capture groups there are in a compiled
 pattern.
-
    
-
    
+
    
+
    
 You can use auxiliary functions for accessing captured substrings
 by number
 or
 by name,
 as described in sections below.
-
    
-
    
+
    
+
    
 Alternatively, you can make direct use of the vector of PCRE2_SIZE values,
 called the ovector, which contains the offsets of captured strings. It is
 part of the
@@ -3257,23 +3257,23 @@ 
    pcre2api man page
    
 The function pcre2_get_ovector_pointer() returns the address of the
 ovector, and pcre2_get_ovector_count() returns the number of pairs of
 values it contains.
-
    
-
    
+
    
+
    
 Within the ovector, the first in each pair of values is set to the offset of
 the first code unit of a substring, and the second is set to the offset of the
 first code unit after the end of a substring. These values are always code unit
 offsets, not character offsets. That is, they are byte offsets in the 8-bit
 library, 16-bit offsets in the 16-bit library, and 32-bit offsets in the 32-bit
 library.
-
    
-
    
+
    
+
    
 After a partial match (error return PCRE2_ERROR_PARTIAL), only the first pair
 of offsets (that is, ovector[0] and ovector[1]) are set. They
 identify the part of the subject that was partially matched. See the
 pcre2partial
 documentation for details of partial matching.
-
    
-
    
+
    
+
    
 After a fully successful match, the first pair of offsets identifies the
 portion of the subject string that was matched by the entire pattern. The next
 pair is used for the first captured substring, and so on. The value returned by
@@ -3281,60 +3281,60 @@ 
    pcre2api man page
    
 set. For example, if two substrings have been captured, the returned value is
 3. If there are no captured substrings, the return value from a successful
 match is 1, indicating that just the first pair of offsets has been set.
-
    
-
    
+
    
+
    
 If a pattern uses the \K escape sequence within a positive assertion, the
 reported start of a successful match can be greater than the end of the match.
 For example, if the pattern (?=ab\K) is matched against "ab", the start and
 end offset values for the match are 2 and 0.
-
    
-
    
+
    
+
    
 If a capture group is matched repeatedly within a single match operation, it is
 the last portion of the subject that it matched that is returned.
-
    
-
    
+
    
+
    
 If the ovector is too small to hold all the captured substring offsets, as much
 as possible is filled in, and the function returns a value of zero. If captured
 substrings are not of interest, pcre2_match() may be called with a match
 data block whose ovector is of minimum length (that is, one pair).
-
    
-
    
+
    
+
    
 It is possible for capture group number n+1 to match some part of the
 subject when group n has not been used at all. For example, if the string
 "abc" is matched against the pattern (a|(z))(bc) the return from the function
 is 4, and groups 1 and 3 are matched, but 2 is not. When this happens, both
 values in the offset pairs corresponding to unused groups are set to
 PCRE2_UNSET.
-
    
-
    
+
    
+
    
 Offset values that correspond to unused groups at the end of the expression are
 also set to PCRE2_UNSET. For example, if the string "abc" is matched against
 the pattern (abc)(x(yz)?)? groups 2 and 3 are not matched. The return from the
 function is 2, because the highest used capture group number is 1. The offsets
 for the second and third capture groups (assuming the vector is large enough,
 of course) are set to PCRE2_UNSET.
-
    
-
    
+
    
+
    
 Elements in the ovector that do not correspond to capturing parentheses in the
 pattern are never changed. That is, if a pattern contains n capturing
 parentheses, no more than ovector[0] to ovector[2n+1] are set by
 pcre2_match(). The other elements retain whatever values they previously
 had. After a failed match attempt, the contents of the ovector are unchanged.
-
    
+
    
 
    OTHER INFORMATION ABOUT A MATCH
    
-
    
+
    
 PCRE2_SPTR pcre2_get_mark(pcre2_match_data *match_data);
 
    
 
    
 PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *match_data);
-
    
-
    
+
    
+
    
 As well as the offsets in the ovector, other information about a match is
 retained in the match data block and can be retrieved by the above functions in
 appropriate circumstances. If they are called at other times, the result is
 undefined.
-
    
-
    
+
    
+
    
 After a successful match, a partial match (PCRE2_ERROR_PARTIAL), or a failure
 to match (PCRE2_ERROR_NOMATCH), a mark name may be available. The function
 pcre2_get_mark() can be called to access this name, which can be
@@ -3345,8 +3345,8 @@ 
    pcre2api man page
    
 zero) is stored in the code unit that precedes the name. You should use this
 length instead of relying on the terminating zero if the name might contain a
 binary zero.
-
    
-
    
+
    
+
    
 After a successful match, the name that is returned is the last mark name
 encountered on the matching path through the pattern. Instances of backtracking
 verbs without names do not count. Thus, for example, if the matching path
@@ -3359,8 +3359,8 @@ 
    pcre2api man page
    
 When it matches "bc", the returned name is A. The B mark is "seen" in the first
 branch of the group, but it is not on the matching path. On the other hand,
 when this pattern fails to match "bx", the returned name is B.
-
    
-
    
+
    
+
    
 Warning: By default, certain start-of-match optimizations are used to
 give a fast "no match" result in some situations. For example, if the anchoring
 is removed from the pattern above, there is an initial check for the presence
@@ -3368,8 +3368,8 @@ 
    pcre2api man page
    
 "bx", causing a match failure without seeing any marks. You can disable the
 start-of-match optimizations by setting the PCRE2_NO_START_OPTIMIZE option for
 pcre2_compile() or by starting the pattern with (*NO_START_OPT).
-
    
-
    
+
    
+
    
 After a successful match, a partial match, or one of the invalid UTF errors
 (for example, PCRE2_ERROR_UTF8_ERR5), pcre2_get_startchar() can be
 called. After a successful or partial match it returns the code unit offset of
@@ -3377,15 +3377,15 @@ 
    pcre2api man page
    
 different to the value of ovector[0] if the pattern contains the \K
 escape sequence. After a partial match, however, this value is always the same
 as ovector[0] because \K does not affect the result of a partial match.
-
    
-
    
+
    
+
    
 After a UTF check failure, pcre2_get_startchar() can be used to obtain
 the code unit offset of the invalid UTF character. Details are given in the
 pcre2unicode
 page.
-
    
+
    
 
    ERROR RETURNS FROM pcre2_match()
    
-
    
+
    
 If pcre2_match() fails, it returns a negative number. This can be
 converted to a text string by calling the pcre2_get_error_message()
 function (see "Obtaining a textual error message"
@@ -3490,30 +3490,30 @@ 
    pcre2api man page
    
 detected and faulted at compile time, but more complicated cases, in particular
 mutual recursions between two different groups, cannot be detected until
 matching is attempted.
-
    
+
    
 
    OBTAINING A TEXTUAL ERROR MESSAGE
    
-
    
+
    
 int pcre2_get_error_message(int errorcode, PCRE2_UCHAR *buffer,
   PCRE2_SIZE bufflen);
-
    
-
    
+
    
+
    
 A text message for an error code from any PCRE2 function (compile, match, or
 auxiliary) can be obtained by calling pcre2_get_error_message(). The code
 is passed as the first argument, with the remaining two arguments specifying a
 code unit buffer and its length in code units, into which the text message is
 placed. The message is returned in code units of the appropriate width for the
 library that is being used.
-
    
-
    
+
    
+
    
 The returned message is terminated with a trailing zero, and the function
 returns the number of code units used, excluding the trailing zero. If the
 error number is unknown, the negative error code PCRE2_ERROR_BADDATA is
 returned. If the buffer is too small, the message is truncated (but still with
 a trailing zero), and the negative error code PCRE2_ERROR_NOMEMORY is returned.
 None of the messages are very long; a buffer size of 120 code units is ample.
-
    
+
    
 
    EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
    
-
    
+
    
 int pcre2_substring_length_bynumber(pcre2_match_data *match_data,
   uint32_t number, PCRE2_SIZE *length);
 
    
@@ -3529,59 +3529,59 @@ 
    pcre2api man page
    
 
    
 
    
 void pcre2_substring_free(PCRE2_UCHAR *buffer);
-
    
-
    
+
    
+
    
 Captured substrings can be accessed directly by using the ovector as described
 above.
 For convenience, auxiliary functions are provided for extracting captured
 substrings as new, separate, zero-terminated strings. A substring that contains
 a binary zero is correctly extracted and has a further zero added on the end,
 but the result is not, of course, a C string.
-
    
-
    
+
    
+
    
 The functions in this section identify substrings by number. The number zero
 refers to the entire matched substring, with higher numbers referring to
 substrings captured by parenthesized groups. After a partial match, only
 substring zero is available. An attempt to extract any other substring gives
 the error PCRE2_ERROR_PARTIAL. The next section describes similar functions for
 extracting captured substrings by name.
-
    
-
    
+
    
+
    
 If a pattern uses the \K escape sequence within a positive assertion, the
 reported start of a successful match can be greater than the end of the match.
 For example, if the pattern (?=ab\K) is matched against "ab", the start and
 end offset values for the match are 2 and 0. In this situation, calling these
 functions with a zero substring number extracts a zero-length empty string.
-
    
-
    
+
    
+
    
 You can find the length in code units of a captured substring without
 extracting it by calling pcre2_substring_length_bynumber(). The first
 argument is a pointer to the match data block, the second is the group number,
 and the third is a pointer to a variable into which the length is placed. If
 you just want to know whether or not the substring has been captured, you can
 pass the third argument as NULL.
-
    
-
    
+
    
+
    
 The pcre2_substring_copy_bynumber() function copies a captured substring
 into a supplied buffer, whereas pcre2_substring_get_bynumber() copies it
 into new memory, obtained using the same memory allocation function that was
 used for the match data block. The first two arguments of these functions are a
 pointer to the match data block and a capture group number.
-
    
-
    
+
    
+
    
 The final arguments of pcre2_substring_copy_bynumber() are a pointer to
 the buffer and a pointer to a variable that contains its length in code units.
 This is updated to contain the actual number of code units used for the
 extracted substring, excluding the terminating zero.
-
    
-
    
+
    
+
    
 For pcre2_substring_get_bynumber() the third and fourth arguments point
 to variables that are updated with a pointer to the new memory and the number
 of code units that comprise the substring, again excluding the terminating
 zero. When the substring is no longer needed, the memory should be freed by
 calling pcre2_substring_free().
-
    
-
    
+
    
+
    
 The return value from all these functions is zero for success, or a negative
 error code. If the pattern match failed, the match failure code is returned.
 If a substring number greater than zero is used after a partial match,
@@ -3608,28 +3608,28 @@ 
    pcre2api man page
    
 The substring did not participate in the match. For example, if the pattern is
 (abc)|(def) and the subject is "def", and the ovector contains at least two
 capturing slots, substring number 1 is unset.
-
    
+
    
 
    EXTRACTING A LIST OF ALL CAPTURED SUBSTRINGS
    
-
    
+
    
 int pcre2_substring_list_get(pcre2_match_data *match_data,
 "  PCRE2_UCHAR ***listptr, PCRE2_SIZE **lengthsptr);
 
    
 
    
 void pcre2_substring_list_free(PCRE2_UCHAR **list);
-
    
-
    
+
    
+
    
 The pcre2_substring_list_get() function extracts all available substrings
 and builds a list of pointers to them. It also (optionally) builds a second
 list that contains their lengths (in code units), excluding a terminating zero
 that is added to each of them. All this is done in a single block of memory
 that is obtained using the same memory allocation function that was used to get
 the match data block.
-
    
-
    
+
    
+
    
 This function must be called only after a successful match. If called after a
 partial match, the error code PCRE2_ERROR_PARTIAL is returned.
-
    
-
    
+
    
+
    
 The address of the memory block is returned via listptr, which is also
 the start of the list of string pointers. The end of the list is marked by a
 NULL pointer. The address of the list of lengths is returned via
@@ -3639,17 +3639,17 @@ 
    pcre2api man page
    
 function is zero if all went well, or PCRE2_ERROR_NOMEMORY if the memory block
 could not be obtained. When the list is no longer needed, it should be freed by
 calling pcre2_substring_list_free().
-
    
-
    
+
    
+
    
 If this function encounters a substring that is unset, which can happen when
 capture group number n+1 matches some part of the subject, but group
 n has not been used at all, it returns an empty string. This can be
 distinguished from a genuine zero-length substring by inspecting the
 appropriate offset in the ovector, which contain PCRE2_UNSET for unset
 substrings, or by calling pcre2_substring_length_bynumber().
-
    
+
    
 
    EXTRACTING CAPTURED SUBSTRINGS BY NAME
    
-
    
+
    
 int pcre2_substring_number_from_name(const pcre2_code *code,
   PCRE2_SPTR name);
 
    
@@ -3667,8 +3667,8 @@ 
    pcre2api man page
    
 
    
 
    
 void pcre2_substring_free(PCRE2_UCHAR *buffer);
-
    
-
    
+
    
+
    
 To extract a substring by name, you first have to find associated number.
 For example, for this pattern:
 
    @@ -3682,22 +3682,22 @@ 
    pcre2api man page
    
 PCRE2_ERROR_NOUNIQUESUBSTRING if there is more than one group with that name.
 Given the number, you can extract the substring directly from the ovector, or
 use one of the "bynumber" functions described above.
-
    
-
    
+
    
+
    
 For convenience, there are also "byname" functions that correspond to the
 "bynumber" functions, the only difference being that the second argument is a
 name instead of a number. If PCRE2_DUPNAMES is set and there are duplicate
 names, these functions scan all the groups with the given name, and return the
 captured substring from the first named group that is set.
-
    
-
    
+
    
+
    
 If there are no groups with the given name, PCRE2_ERROR_NOSUBSTRING is
 returned. If all groups with the name have numbers that are greater than the
 number of slots in the ovector, PCRE2_ERROR_UNAVAILABLE is returned. If there
 is at least one group with a slot in the ovector, but no group is found to be
 set, PCRE2_ERROR_UNSET is returned.
-
    
-
    
+
    
+
    
 Warning: If the pattern uses the (?| feature to set up multiple
 capture groups with the same number, as described in the
 section on duplicate group numbers
@@ -3707,17 +3707,17 @@ 
    pcre2api man page
    
 names are not included in the compiled code. The matching process uses only
 numbers. For this reason, the use of different names for groups with the
 same number causes an error at compile time.
-
    
+
    
 
    CREATING A NEW STRING WITH SUBSTITUTIONS
    
-
    
+
    
 int pcre2_substitute(const pcre2_code *code, PCRE2_SPTR subject,
   PCRE2_SIZE length, PCRE2_SIZE startoffset,
   uint32_t options, pcre2_match_data *match_data,
   pcre2_match_context *mcontext, PCRE2_SPTR replacement,
   PCRE2_SIZE rlength, PCRE2_UCHAR *outputbuffer,
   PCRE2_SIZE *outlengthptr);
-
    
-
    
+
    
+
    
 This function optionally calls pcre2_match() and then makes a copy of the
 subject string in outputbuffer, replacing parts that were matched with
 the replacement string, whose length is supplied in rlength, which
@@ -3725,42 +3725,42 @@ 
    pcre2api man page
    
 special case, if replacement is NULL and rlength is zero, the
 replacement is assumed to be an empty string. If rlength is non-zero, an
 error occurs if replacement is NULL.
-
    
-
    
+
    
+
    
 There is an option (see PCRE2_SUBSTITUTE_REPLACEMENT_ONLY below) to return just
 the replacement string(s). The default action is to perform just one
 replacement if the pattern matches, but there is an option that requests
 multiple replacements (see PCRE2_SUBSTITUTE_GLOBAL below).
-
    
-
    
+
    
+
    
 If successful, pcre2_substitute() returns the number of substitutions
 that were carried out. This may be zero if no match was found, and is never
 greater than one unless PCRE2_SUBSTITUTE_GLOBAL is set. A negative value is
 returned if an error is detected.
-
    
-
    
+
    
+
    
 Matches in which a \K item in a lookahead in the pattern causes the match to
 end before it starts are not supported, and give rise to an error return. For
 global replacements, matches in which \K in a lookbehind causes the match to
 start earlier than the point that was reached in the previous iteration are
 also not supported.
-
    
-
    
+
    
+
    
 The first seven arguments of pcre2_substitute() are the same as for
 pcre2_match(), except that the partial matching options are not
 permitted, and match_data may be passed as NULL, in which case a match
 data block is obtained and freed within this function, using memory management
 functions from the match context, if provided, or else those that were used to
 allocate memory for the compiled code.
-
    
-
    
+
    
+
    
 If match_data is not NULL and PCRE2_SUBSTITUTE_MATCHED is not set, the
 provided block is used for all calls to pcre2_match(), and its contents
 afterwards are the result of the final call. For global changes, this will
 always be a no-match error. The contents of the ovector within the match data
 block may or may not have been changed.
-
    
-
    
+
    
+
    
 As well as the usual options for pcre2_match(), a number of additional
 options can be set in the options argument of pcre2_substitute().
 One such option is PCRE2_SUBSTITUTE_MATCHED. When this is set, an external
@@ -3770,21 +3770,21 @@ 
    pcre2api man page
    
 is then used for the first substitution instead of calling pcre2_match()
 from within pcre2_substitute(). This allows an application to check for a
 match before choosing to substitute, without having to repeat the match.
-
    
-
    
+
    
+
    
 The contents of the externally supplied match data block are not changed when
 PCRE2_SUBSTITUTE_MATCHED is set. If PCRE2_SUBSTITUTE_GLOBAL is also set,
 pcre2_match() is called after the first substitution to check for further
 matches, but this is done using an internally obtained match data block, thus
 always leaving the external block unchanged.
-
    
-
    
+
    
+
    
 The code argument is not used for matching before the first substitution
 when PCRE2_SUBSTITUTE_MATCHED is set, but it must be provided, even when
 PCRE2_SUBSTITUTE_GLOBAL is not set, because it contains information such as the
 UTF setting and the number of capturing parentheses in the pattern.
-
    
-
    
+
    
+
    
 The default action of pcre2_substitute() is to return a copy of the
 subject string with matched substrings replaced. However, if
 PCRE2_SUBSTITUTE_REPLACEMENT_ONLY is set, only the replacement substrings are
@@ -3792,22 +3792,22 @@ 
    pcre2api man page
    
 output buffer. Substitution callouts (see
 below)
 can be used to separate them if necessary.
-
    
-
    
+
    
+
    
 The outlengthptr argument of pcre2_substitute() must point to a
 variable that contains the length, in code units, of the output buffer. If the
 function is successful, the value is updated to contain the length in code
 units of the new string, excluding the trailing zero that is automatically
 added.
-
    
-
    
+
    
+
    
 If the function is not successful, the value set via outlengthptr depends
 on the type of error. For syntax errors in the replacement string, the value is
 the offset in the replacement string where the error was detected. For other
 errors, the value is PCRE2_UNSET by default. This includes the case of the
 output buffer being too small, unless PCRE2_SUBSTITUTE_OVERFLOW_LENGTH is set.
-
    
-
    
+
    
+
    
 PCRE2_SUBSTITUTE_OVERFLOW_LENGTH changes what happens when the output buffer is
 too small. The default action is to return PCRE2_ERROR_NOMEMORY immediately. If
 this option is set, however, pcre2_substitute() continues to go through
@@ -3816,20 +3816,20 @@ 
    pcre2api man page
    
 extra space for the terminating NUL. This value is passed back via the
 outlengthptr variable, with the result of the function still being
 PCRE2_ERROR_NOMEMORY.
-
    
-
    
+
    
+
    
 Passing a buffer size of zero is a permitted way of finding out how much memory
 is needed for given substitution. However, this does mean that the entire
 operation is carried out twice. Depending on the application, it may be more
 efficient to allocate a large buffer and free the excess afterwards, instead of
 using PCRE2_SUBSTITUTE_OVERFLOW_LENGTH.
-
    
-
    
+
    
+
    
 The replacement string, which is interpreted as a UTF string in UTF mode, is
 checked for UTF validity unless PCRE2_NO_UTF_CHECK is set. An invalid UTF
 replacement string causes an immediate return with the relevant UTF error code.
-
    
-
    
+
    
+
    
 If PCRE2_SUBSTITUTE_LITERAL is set, the replacement string is not interpreted
 in any way. By default, however, a dollar character is an escape character that
 can specify the insertion of characters from capture groups and names from
@@ -3850,12 +3850,12 @@ 
    pcre2api man page
    
 interpreted as part of the number or name. The number may be zero to include
 the entire matched string. For example, if the pattern a(b)c is matched with
 "=abc=" and the replacement string "+$1$0$1+", the result is "=+babcb+=".
-
    
-
    
+
    
+
    
 The JavaScript form $<name>, where the angle brackets are part of the syntax,
 is also recognized for group names, but not for group numbers or *MARK.
-
    
-
    
+
    
+
    
 $*MARK inserts the name from the last encountered backtracking control verb on
 the matching path that has a name. (*MARK) must always include a name, but the
 other verbs need not. For example, in the case of (*MARK:A)(*PRUNE) the name
@@ -3874,8 +3874,8 @@ 
    pcre2api man page
    
 Iteration is implemented by advancing the startoffset value for each
 search, which is always passed the entire subject string. If an offset limit is
 set in the match context, searching stops when that limit is reached.
-
    
-
    
+
    
+
    
 You can restrict the effect of a global substitution to a portion of the
 subject string by setting either or both of startoffset and an offset
 limit. Here is a pcre2test example:
@@ -3889,46 +3889,46 @@ 
    pcre2api man page
    
 If this is not successful, the offset is advanced by one character except when
 CRLF is a valid newline sequence and the next two characters are CR, LF. In
 this case, the offset is advanced by two characters.
-
    
-
    
+
    
+
    
 PCRE2_SUBSTITUTE_UNKNOWN_UNSET causes references to capture groups that do
 not appear in the pattern to be treated as unset groups. This option should be
 used with care, because it means that a typo in a group name or number no
 longer causes the PCRE2_ERROR_NOSUBSTRING error.
-
    
-
    
+
    
+
    
 PCRE2_SUBSTITUTE_UNSET_EMPTY causes unset capture groups (including unknown
 groups when PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set) to be treated as empty
 strings when inserted as described above. If this option is not set, an attempt
 to insert an unset group causes the PCRE2_ERROR_UNSET error. This option does
 not influence the extended substitution syntax described below.
-
    
-
    
+
    
+
    
 PCRE2_SUBSTITUTE_EXTENDED causes extra processing to be applied to the
 replacement string. Without this option, only the dollar character is special,
 and only the group insertion forms listed above are valid. When
 PCRE2_SUBSTITUTE_EXTENDED is set, several things change:
-
    
-
    
+
    
+
    
 Firstly, backslash in a replacement string is interpreted as an escape
 character. The usual forms such as \x{ddd} can be used to specify particular
 character codes, and backslash followed by any non-alphanumeric character
 quotes that character. Extended quoting can be coded using \Q...\E, exactly
 as in pattern strings. The escapes \b and \v are interpreted as the
 characters backspace and vertical tab, respectively.
-
    
-
    
+
    
+
    
 The interpretation of backslash followed by one or more digits is the same as
 in a pattern, which in Perl has some ambiguities. Details are given in the
 pcre2pattern
 page.
-
    
-
    
+
    
+
    
 The Python form \g<n>, where the angle brackets are part of the syntax and n
 is either a group name or number, is recognized as an altertive way of
 inserting the contents of a group, for example \g<3>.
-
    
-
    
+
    
+
    
 There are also four escape sequences for forcing the case of inserted letters.
 Case forcing applies to all inserted characters, including those from capture
 groups and letters within \Q...\E quoted sequences. The insertion mechanism
@@ -3938,15 +3938,15 @@ 
    pcre2api man page
    
 sequence) reverts to no case forcing. The sequences \u and \l force the next
 character (if it is a letter) to upper or lower case, respectively, and then
 the state automatically reverts to no case forcing.
-
    
-
    
+
    
+
    
 However, if \u is immediately followed by \L or \l is immediately followed
 by \U, the next character's case is forced by the first escape sequence, and
 subsequent characters by the second. This provides a "title casing" facility
 that can be applied to group captures. For example, if group 1 has captured
 "heLLo", the replacement string "\u\L$1" becomes "Hello".
-
    
-
    
+
    
+
    
 If either PCRE2_UTF or PCRE2_UCP was set when the pattern was compiled, Unicode
 properties are used for case forcing characters whose code points are greater
 than 127. However, only simple case folding, as determined by the Unicode file
@@ -3954,14 +3954,14 @@ 
    pcre2api man page
    
 special casing rules such as using different lower case Greek sigmas in the
 middle and ends of words (as defined in the Unicode file
 SpecialCasing.txt).
-
    
-
    
+
    
+
    
 Note that case forcing sequences such as \U...\E do not nest. For example,
 the result of processing "\Uaa\LBB\Ecc\E" is "AAbbcc"; the final \E has no
 effect. Note also that the PCRE2_ALT_BSUX and PCRE2_EXTRA_ALT_BSUX options do
 not apply to replacement strings.
-
    
-
    
+
    
+
    
 The final effect of setting PCRE2_SUBSTITUTE_EXTENDED is to add more
 flexibility to capture group substitution. The syntax is similar to that used
 by Bash:
@@ -3990,42 +3990,42 @@ 
    pcre2api man page
    
 The PCRE2_SUBSTITUTE_UNSET_EMPTY option does not affect these extended
 substitutions. However, PCRE2_SUBSTITUTE_UNKNOWN_UNSET does cause unknown
 groups in the extended syntax forms to be treated as unset.
-
    
-
    
+
    
+
    
 If PCRE2_SUBSTITUTE_LITERAL is set, PCRE2_SUBSTITUTE_UNKNOWN_UNSET,
 PCRE2_SUBSTITUTE_UNSET_EMPTY, and PCRE2_SUBSTITUTE_EXTENDED are irrelevant and
 are ignored.
-
    
+
    
 
    
 Substitution errors
 
    
-
    
+
    
 In the event of an error, pcre2_substitute() returns a negative error
 code. Except for PCRE2_ERROR_NOMATCH (which is never returned), errors from
 pcre2_match() are passed straight back.
-
    
-
    
+
    
+
    
 PCRE2_ERROR_NOSUBSTRING is returned for a non-existent substring insertion,
 unless PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set.
-
    
-
    
+
    
+
    
 PCRE2_ERROR_UNSET is returned for an unset substring insertion (including an
 unknown substring when PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set) when the simple
 (non-extended) syntax is used and PCRE2_SUBSTITUTE_UNSET_EMPTY is not set.
-
    
-
    
+
    
+
    
 PCRE2_ERROR_NOMEMORY is returned if the output buffer is not big enough. If the
 PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option is set, the size of buffer that is
 needed is returned via outlengthptr. Note that this does not happen by
 default.
-
    
-
    
+
    
+
    
 PCRE2_ERROR_NULL is returned if PCRE2_SUBSTITUTE_MATCHED is set but the
 match_data argument is NULL or if the subject or replacement
 arguments are NULL. For backward compatibility reasons an exception is made for
 the replacement argument if the rlength argument is also 0.
-
    
-
    
+
    
+
    
 PCRE2_ERROR_BADREPLACEMENT is used for miscellaneous syntax errors in the
 replacement string, with more particular errors being PCRE2_ERROR_BADREPESCAPE
 (invalid escape sequence), PCRE2_ERROR_REPMISSINGBRACE (closing curly bracket
@@ -4033,17 +4033,17 @@ 
    pcre2api man page
    
 substitution), and PCRE2_ERROR_BADSUBSPATTERN (the pattern match ended before
 it started or the match started earlier than the current position in the
 subject, which can happen if \K is used in an assertion).
-
    
-
    
+
    
+
    
 As for all PCRE2 errors, a text message that describes the error can be
 obtained by calling the pcre2_get_error_message() function (see
 "Obtaining a textual error message"
 above).
-
    
+
    
 
    
 Substitution callouts
 
    
-
    
+
    
 int pcre2_set_substitute_callout(pcre2_match_context *mcontext,
   int (*callout_function)(pcre2_substitute_callout_block *, void *),
   void *callout_data);
@@ -4053,8 +4053,8 @@ 
    pcre2api man page
    
 callout function for pcre2_substitute(). This information is passed in
 a match context. The callout function is called after each substitution has
 been processed, but it can cause the replacement not to happen.
-
    
-
    
+
    
+
    
 The callout function is not called for simulated substitutions that happen as a
 result of the PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option. In this mode, when
 substitution processing exceeds the buffer space provided by the caller,
@@ -4064,8 +4064,8 @@ 
    pcre2api man page
    
 is reported as the required size. Therefore, the returned buffer length may be
 an overestimate (without a substitution callout, it is normally an exact
 measurement).
-
    
-
    
+
    
+
    
 The first argument of the callout function is a pointer to a substitute callout
 block structure, which contains the following fields, not necessarily in this
 order:
@@ -4081,28 +4081,28 @@ 
    pcre2api man page
    
 The version field contains the version number of the block format. The
 current version is 0. The version number will increase in future if more fields
 are added, but the intention is never to remove any of the existing fields.
-
    
-
    
+
    
+
    
 The subscount field is the number of the current match. It is 1 for the
 first callout, 2 for the second, and so on. The input and output
 pointers are copies of the values passed to pcre2_substitute().
-
    
-
    
+
    
+
    
 The ovector field points to the ovector, which contains the result of the
 most recent match. The oveccount field contains the number of pairs that
 are set in the ovector, and is always greater than zero.
-
    
-
    
+
    
+
    
 The output_offsets vector contains the offsets of the replacement in the
 output string. This has already been processed for dollar and (if requested)
 backslash substitutions as described above.
-
    
-
    
+
    
+
    
 The second argument of the callout function is the value passed as
 callout_data when the function was registered. The value returned by the
 callout function is interpreted as follows:
-
    
-
    
+
    
+
    
 If the value is zero, the replacement is accepted, and, if
 PCRE2_SUBSTITUTE_GLOBAL is set, processing continues with a search for the next
 match. If the value is not zero, the current replacement is not accepted. If
@@ -4111,11 +4111,11 @@ 
    pcre2api man page
    
 PCRE2_SUBSTITUTE_GLOBAL is not set), the rest of the input is copied to the
 output and the call to pcre2_substitute() exits, returning the number of
 matches so far.
-
    
+
    
 
    
 Substitution case callouts
 
    
-
    
+
    
 int pcre2_set_substitute_case_callout(pcre2_match_context *mcontext,
   PCRE2_SIZE (*callout_function)(PCRE2_SPTR, PCRE2_SIZE,
                                  PCRE2_UCHAR *, PCRE2_SIZE,
@@ -4130,17 +4130,17 @@ 
    pcre2api man page
    
 processing a substitution such as:
 
         pcre2_substitute(..., "\\U$1", ...)
-
    
-
    
-
    
+
    
+
    
+
    
 The default case transformations applied by PCRE2 are reasonably complete, and,
 in UTF or UCP mode, perform the simple locale-invariant case transformations as
 specified by Unicode. This is suitable for the internal (invisible)
 case-equivalence procedures used during pattern matching, but an application
 may wish to use more sophisticated locale-aware processing for the user-visible
 substitution transformations.
-
    
-
    
+
    
+
    
 One example implementation of the callout_function using the ICU
 library would be:
 
    
@@ -4162,16 +4162,16 @@ 
    pcre2api man page
    
       if (U_FAILURE(err)) return (~(PCRE2_SIZE)0);
       return r;
     }
-
    
-
    
-
    
+
    
+
    
+
    
 The first and second arguments of the case callout function are the Unicode
 string to transform.
-
    
-
    
+
    
+
    
 The third and fourth arguments are the output buffer and its capacity.
-
    
-
    
+
    
+
    
 The fifth is one of the constants PCRE2_SUBSTITUTE_CASE_LOWER,
 PCRE2_SUBSTITUTE_CASE_UPPER, or PCRE2_SUBSTITUTE_CASE_TITLE_FIRST.
 PCRE2_SUBSTITUTE_CASE_LOWER and PCRE2_SUBSTITUTE_CASE_UPPER are passed to the
@@ -4181,12 +4181,12 @@ 
    pcre2api man page
    
 and the rest to Unicode lowercase (note that titlecasing sometimes uses Unicode
 properties to titlecase each word in a string; but PCRE2 is requesting that only
 the single leading character is to be titlecased).
-
    
-
    
+
    
+
    
 The sixth argument is the callout_data supplied to
 pcre2_set_substitute_case_callout().
-
    
-
    
+
    
+
    
 The resulting string in the destination buffer may be larger or smaller than the
 input, if the casing rules merge or split characters. The return value is the
 length required for the output string. If a buffer of sufficient size was
@@ -4195,13 +4195,13 @@ 
    pcre2api man page
    
 buffer, then the required capacity must be returned and PCRE2 will not make use
 of the output buffer. PCRE2 provides input and output buffers which overlap, so
 the callout must support this by suitable internal buffering.
-
    
-
    
+
    
+
    
 Alternatively, if the callout wishes to indicate an error, then it may return
 (~(PCRE2_SIZE)0). In this case pcre2_substitute() will immediately fail with
 error PCRE2_ERROR_REPLACECASE.
-
    
-
    
+
    
+
    
 When a case callout is combined with the PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
 option, there are situations when pcre2_substitute() will return an
 underestimate of the required buffer size. If you call pcre2_substitute() once
@@ -4212,55 +4212,55 @@ 
    pcre2api man page
    
 second call is not guaranteed to succeed either, if the case callout requires
 more buffer space than expected. The caller must make repeated attempts in a
 loop.
-
    
+
    
 
    DUPLICATE CAPTURE GROUP NAMES
    
-
    
+
    
 int pcre2_substring_nametable_scan(const pcre2_code *code,
   PCRE2_SPTR name, PCRE2_SPTR *first, PCRE2_SPTR *last);
-
    
-
    
+
    
+
    
 When a pattern is compiled with the PCRE2_DUPNAMES option, names for capture
 groups are not required to be unique. Duplicate names are always allowed for
 groups with the same number, created by using the (?| feature. Indeed, if such
 groups are named, they are required to use the same names.
-
    
-
    
+
    
+
    
 Normally, patterns that use duplicate names are such that in any one match,
 only one of each set of identically-named groups participates. An example is
 shown in the
 pcre2pattern
 documentation.
-
    
-
    
+
    
+
    
 When duplicates are present, pcre2_substring_copy_byname() and
 pcre2_substring_get_byname() return the first substring corresponding to
 the given name that is set. Only if none are set is PCRE2_ERROR_UNSET is
 returned. The pcre2_substring_number_from_name() function returns the
 error PCRE2_ERROR_NOUNIQUESUBSTRING when there are duplicate names.
-
    
-
    
+
    
+
    
 If you want to get full details of all captured substrings for a given name,
 you must use the pcre2_substring_nametable_scan() function. The first
 argument is the compiled pattern, and the second is the name. If the third and
 fourth arguments are NULL, the function returns a group number for a unique
 name, or PCRE2_ERROR_NOUNIQUESUBSTRING otherwise.
-
    
-
    
+
    
+
    
 When the third and fourth arguments are not NULL, they must be pointers to
 variables that are updated by the function. After it has run, they point to the
 first and last entries in the name-to-number table for the given name, and the
 function returns the length of each entry in code units. In both cases,
 PCRE2_ERROR_NOSUBSTRING is returned if there are no entries for the given name.
-
    
-
    
+
    
+
    
 The format of the name table is described
 above
 in the section entitled Information about a pattern. Given all the
 relevant entries for the name, you can extract each of their numbers, and hence
 the captured data.
-
    
+
    
 
    FINDING ALL POSSIBLE MATCHES AT ONE POSITION
    
-
    
+
    
 The traditional matching function uses a similar algorithm to Perl, which stops
 when it finds the first match at a given point in the subject. If you want to
 find all possible matches, or the longest possible match at a given position,
@@ -4269,23 +4269,23 @@ 
    pcre2api man page
    
 callout facility, which is described in the
 pcre2callout
 documentation.
-
    
-
    
+
    
+
    
 What you have to do is to insert a callout right at the end of the pattern.
 When your callout function is called, extract and save the current matched
 substring. Then return 1, which forces pcre2_match() to backtrack and try
 other alternatives. Ultimately, when it runs out of matches,
 pcre2_match() will yield PCRE2_ERROR_NOMATCH.
-
    
+
    
 
    MATCHING A PATTERN: THE ALTERNATIVE FUNCTION
    
-
    
+
    
 int pcre2_dfa_match(const pcre2_code *code, PCRE2_SPTR subject,
   PCRE2_SIZE length, PCRE2_SIZE startoffset,
   uint32_t options, pcre2_match_data *match_data,
   pcre2_match_context *mcontext,
   int *workspace, PCRE2_SIZE wscount);
-
    
-
    
+
    
+
    
 The function pcre2_dfa_match() is called to match a subject string
 against a compiled pattern, using a matching algorithm that scans the subject
 string just once (not counting lookaround assertions), and does not backtrack
@@ -4297,21 +4297,21 @@ 
    pcre2api man page
    
 not support, see the
 pcre2matching
 documentation.
-
    
-
    
+
    
+
    
 The arguments for the pcre2_dfa_match() function are the same as for
 pcre2_match(), plus two extras. The ovector within the match data block
 is used in a different way, and this is described below. The other common
 arguments are used in the same way as for pcre2_match(), so their
 description is not repeated here.
-
    
-
    
+
    
+
    
 The two additional arguments provide workspace for the function. The workspace
 vector should contain at least 20 elements. It is used for keeping track of
 multiple paths through the pattern tree. More workspace is needed for patterns
 and subjects where there are a lot of potential matches.
-
    
-
    
+
    
+
    
 Here is an example of a simple call to pcre2_dfa_match():
 
       int wspace[20];
@@ -4326,12 +4326,12 @@ 
    pcre2api man page
    
     NULL,           /* a match context; NULL means use defaults */
     wspace,         /* working space vector */
     20);            /* number of elements (NOT size in bytes) */
-
    
-
    
+
    
+
    
 
    
 Option bits for pcre2_dfa_match()
 
    
-
    
+
    
 The unused bits of the options argument for pcre2_dfa_match() must
 be zero. The only bits that may be set are PCRE2_ANCHORED,
 PCRE2_COPY_MATCHED_SUBJECT, PCRE2_ENDANCHORED, PCRE2_NOTBOL, PCRE2_NOTEOL,
@@ -4375,11 +4375,11 @@ 
    pcre2api man page
    
 match. There is more discussion of this facility in the
 pcre2partial
 documentation.
-
    
+
    
 
    
 Successful returns from pcre2_dfa_match()
 
    
-
    
+
    
 When pcre2_dfa_match() succeeds, it may have matched more than one
 substring in the subject. Note, however, that all the matches from one run of
 the function start at the same point in the subject. The shorter matches are
@@ -4402,31 +4402,31 @@ 
    pcre2api man page
    
 the ovector, and can be extracted by number in the same way as for
 pcre2_match(), but the numbers bear no relation to any capture groups
 that may exist in the pattern, because DFA matching does not support capturing.
-
    
-
    
+
    
+
    
 Calls to the convenience functions that extract substrings by name
 return the error PCRE2_ERROR_DFA_UFUNC (unsupported function) if used after a
 DFA match. The convenience functions that extract substrings by number never
 return PCRE2_ERROR_NOSUBSTRING.
-
    
-
    
+
    
+
    
 The matched strings are stored in the ovector in reverse order of length; that
 is, the longest matching string is first. If there were too many matches to fit
 into the ovector, the yield of the function is zero, and the vector is filled
 with the longest matches.
-
    
-
    
+
    
+
    
 NOTE: PCRE2's "auto-possessification" optimization usually applies to character
 repeats at the end of a pattern (as well as internally). For example, the
 pattern "a\d+" is compiled as if it were "a\d++". For DFA matching, this
 means that only one possible match is found. If you really do want multiple
 matches in such cases, either use an ungreedy repeat such as "a\d+?" or set
 the PCRE2_NO_AUTO_POSSESS option when compiling.
-
    
+
    
 
    
 Error returns from pcre2_dfa_match()
 
    
-
    
+
    
 The pcre2_dfa_match() function returns a negative number when it fails.
 Many of the errors are the same as for pcre2_match(), as described
 above.
@@ -4469,24 +4469,24 @@ 
    pcre2api man page
    
 some plausibility checks are made on the contents of the workspace, which
 should contain data about the previous partial match. If any of these checks
 fail, this error is given.
-
    
+
    
 
    SEE ALSO
    
-
    
+
    
 pcre2build(3), pcre2callout(3), pcre2demo(3),
 pcre2matching(3), pcre2partial(3), pcre2posix(3),
 pcre2sample(3), pcre2unicode(3).
-
    
+
    
 
    AUTHOR
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    REVISION
    
-
    
+
    
 Last updated: 26 December 2024
 
    
 Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/html/pcre2build.html b/doc/html/pcre2build.html
index f4e127f14..19d7509ad 100644
--- a/doc/html/pcre2build.html
+++ b/doc/html/pcre2build.html
@@ -42,7 +42,7 @@ 
    pcre2build man page
    
 
  • REVISION
 
 
    BUILDING PCRE2
    
-
    
+
    
 PCRE2 is distributed with a configure script that can be used to build
 the library in Unix-like environments using the applications known as
 Autotools. Also in the distribution are files to support building using
@@ -58,23 +58,23 @@ 
    pcre2build man page
    
 You should consult this file as well as the
 README
 file if you are building in a non-Unix-like environment.
-
    
+
    
 
    PCRE2 BUILD-TIME OPTIONS
    
-
    
+
    
 The rest of this document describes the optional features of PCRE2 that can be
 selected when the library is compiled. It assumes use of the configure
 script, where the optional features are selected or deselected by providing
 options to configure before running the make command. However, the
 same options can be selected in both Unix-like and non-Unix-like environments
 if you are using CMake instead of configure to build PCRE2.
-
    
-
    
+
    
+
    
 If you are not using Autotools or CMake, option selection can be done by
 editing the config.h file, or by passing parameter settings to the
 compiler, as described in
 NON-AUTOTOOLS-BUILD.
-
    
-
    
+
    
+
    
 The complete list of options for configure (which includes the standard
 ones such as the selection of the installation directory) can be obtained by
 running
@@ -87,9 +87,9 @@ 
    pcre2build man page
    
 always exists as well, but as it specifies the default, it is not described.
 Options that specify values have names that start with --with. At the end of a
 configure run, a summary of the configuration is output.
-
    
+
    
 
    BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES
    
-
    
+
    
 By default, a library called libpcre2-8 is built, containing functions
 that take string arguments contained in arrays of bytes, interpreted either as
 single-byte characters, or UTF-8 strings. You can also build two other
@@ -110,9 +110,9 @@ 
    pcre2build man page
    
 wrapper is for the 8-bit library only, and that pcre2grep is an 8-bit
 program. Neither of these are built if you select only the 16-bit or 32-bit
 libraries.
-
    
+
    
 
    BUILDING SHARED AND STATIC LIBRARIES
    
-
    
+
    
 The Autotools PCRE2 building process uses libtool to build both shared
 and static libraries by default. You can suppress an unwanted library by adding
 one of
@@ -133,9 +133,9 @@ 
    pcre2build man page
    
 
    
 Note the two hyphens in --static. Of course, this works only if static versions
 of all the relevant libraries are available for linking.
-
    
+
    
 
    UNICODE AND UTF SUPPORT
    
-
    
+
    
 By default, PCRE2 is built with support for Unicode and UTF character strings.
 To build it without Unicode support, add
 
    @@ -144,15 +144,15 @@ 
    pcre2build man page
    
 to the configure command. This setting applies to all three libraries. It
 is not possible to build one library with Unicode support and another without
 in the same configuration.
-
    
-
    
+
    
+
    
 Of itself, Unicode support does not make PCRE2 treat strings as UTF-8, UTF-16
 or UTF-32. To do that, applications that use the library can set the PCRE2_UTF
 option when they call pcre2_compile() to compile a pattern.
 Alternatively, patterns may be started with (*UTF) unless the application has
 locked this out by setting PCRE2_NEVER_UTF.
-
    
-
    
+
    
+
    
 UTF support allows the libraries to process character code points up to
 0x10ffff in the strings that they handle. Unicode support also gives access to
 the Unicode properties of characters, using pattern escapes such as \P, \p,
@@ -161,15 +161,15 @@ 
    pcre2build man page
    
 given in the
 pcre2pattern
 documentation.
-
    
-
    
+
    
+
    
 Pattern escapes such as \d and \w do not by default make use of Unicode
 properties. The application can request that they do by setting the PCRE2_UCP
 option. Unless the application has set PCRE2_NEVER_UCP, a pattern may also
 request this by starting with (*UCP).
-
    
+
    
 
    DISABLING THE USE OF \C
    
-
    
+
    
 The \C escape sequence, which matches a single code unit, even in a UTF mode,
 can cause unpredictable behaviour because it may leave the current matching
 point in the middle of a multi-code-unit character. The application can lock it
@@ -179,9 +179,9 @@ 
    pcre2build man page
    
   --enable-never-backslash-C
 
    
 (note the upper case C) which locks out the use of \C entirely.
-
    
+
    
 
    JUST-IN-TIME COMPILER SUPPORT
    
-
    
+
    
 Just-in-time (JIT) compiler support is included in the build by specifying
 
       --enable-jit
@@ -208,9 +208,9 @@ 
    pcre2build man page
    
   --disable-pcre2grep-jit
 
    
 to the configure command.
-
    
+
    
 
    NEWLINE RECOGNITION
    
-
    
+
    
 By default, PCRE2 interprets the linefeed (LF) character as indicating the end
 of a line. This is the normal newline character on Unix-like systems. You can
 compile PCRE2 to use carriage return (CR) instead, by adding
@@ -219,8 +219,8 @@ 
    pcre2build man page
    
 
    • 
 to the configure command. There is also an --enable-newline-is-lf option,
 which explicitly specifies linefeed as the newline character.
-
    
-
    
+
    
+
    
 Alternatively, you can specify that line endings are to be indicated by the
 two-character sequence CRLF (CR immediately followed by LF). If you want this,
 add
@@ -244,14 +244,14 @@ 
    pcre2build man page
    
   --enable-newline-is-nul
    which causes NUL (binary zero) to be set as the default line-ending character. -

    -

    +

    +

    Whatever default line ending convention is selected when PCRE2 is built can be overridden by applications that use the library. At build time it is recommended to use the standard for your operating system. -

    +


    WHAT \R MATCHES
    -

    +

    By default, the sequence \R in a pattern matches any Unicode newline sequence, independently of what has been selected as the line ending sequence. If you specify @@ -261,9 +261,9 @@

    pcre2build man page

    the default is changed so that \R matches only CR, LF, or CRLF. Whatever is selected when PCRE2 is built can be overridden by applications that use the library. -

    +


    HANDLING VERY LARGE PATTERNS
    -

    +

    Within a compiled pattern, offset values are used to point from one part to another (for example, from an opening parenthesis to an alternation metacharacter). By default, in the 8-bit and 16-bit libraries, two-byte values @@ -280,9 +280,9 @@

    pcre2build man page

    longer offsets slows down the operation of PCRE2 because it has to load additional data when handling them. For the 32-bit library the value is always 4 and cannot be overridden; the value of --with-link-size is ignored. -

    +


    LIMITING PCRE2 RESOURCE USAGE
    -

    +

    The pcre2_match() function increments a counter each time it goes round its main loop. Putting a limit on this counter controls the amount of computing resource used by a single call to pcre2_match(). The limit can be changed @@ -296,8 +296,8 @@

    pcre2build man page

    to the configure command. This setting also applies to the pcre2_dfa_match() matching function, and to JIT matching (though the counting is done differently). -

    -

    +

    +

    The pcre2_match() function uses heap memory to record backtracking points. The more nested backtracking points there are (that is, the deeper the search tree), the more memory is needed. There is an upper limit, specified in @@ -314,8 +314,8 @@

    pcre2build man page

    may also use the heap for internal workspace when processing complicated patterns. This limit does not apply when JIT (which has its own memory arrangements) is used. -

    -

    +

    +

    You can also explicitly limit the depth of nested backtracking in the pcre2_match() interpreter. This limit defaults to the value that is set for --with-match-limit. You can set a lower default limit by adding, for @@ -329,15 +329,15 @@

    pcre2build man page

    capturing parentheses in a pattern, the amount of heap that is used before the limit is reached varies from pattern to pattern. This limit was more useful in versions before 10.30, where function recursion was used for backtracking. -

    -

    +

    +

    As well as applying to pcre2_match(), the depth limit also controls the depth of recursive function calls in pcre2_dfa_match(). These are used for lookaround assertions, atomic groups, and recursion within patterns. The limit does not apply to JIT matching. -

    +


    LIMITING VARIABLE-LENGTH LOOKBEHIND ASSERTIONS
    -

    +

    Lookbehind assertions in which one or more branches can match a variable number of characters are supported only if there is a maximum matching length for each top-level branch. There is a limit to this maximum that defaults to 255 @@ -349,9 +349,9 @@

    pcre2build man page

    pcre2_set_max_varlookbehind(). Lookbehind assertions in which every branch matches a fixed number of characters (not necessarily all the same) are not constrained by this limit. -

    +


    CREATING CHARACTER TABLES AT BUILD TIME
    -

    +

    PCRE2 uses fixed tables for processing characters whose code points are less than 256. By default, PCRE2 is built with a set of tables that are distributed in the file src/pcre2_chartables.c.dist. These tables are for ASCII codes @@ -365,8 +365,8 @@

    pcre2build man page

    C run-time system. This method of replacing the tables does not work if you are cross compiling, because pcre2_dftables needs to be run on the local host and therefore not compiled with the cross compiler. -

    -

    +

    +

    If you need to create alternative tables when cross compiling, you will have to do so "by hand". There may also be other reasons for creating tables manually. To cause pcre2_dftables to be built on the local host, run a normal @@ -388,9 +388,9 @@

    pcre2build man page

    just a string of bytes, independent of hardware characteristics such as endianness. This means they can be bundled with an application that runs in different environments, to ensure consistent behaviour. -

    +


    USING EBCDIC CODE
    -

    +

    PCRE2 assumes by default that it will run in an environment where the character code is ASCII or Unicode, which is a superset of ASCII. This is the case for most computer operating systems. PCRE2 can, however, be compiled to run in an @@ -401,13 +401,13 @@

    pcre2build man page

    to the configure command. This setting implies --enable-rebuild-chartables. You should only use it if you know that you are in an EBCDIC environment (for example, an IBM mainframe operating system). -

    -

    +

    +

    It is not possible to support both EBCDIC and UTF-8 codes in the same version of the library. Consequently, --enable-unicode and --enable-ebcdic are mutually exclusive. -

    -

    +

    +

    The EBCDIC character that corresponds to an ASCII LF is assumed to have the value 0x15 by default. However, in some EBCDIC environments, 0x25 is used. In such an environment you should use @@ -418,14 +418,14 @@

    pcre2build man page

    same value as in ASCII, namely, 0x0d. Whichever of 0x15 and 0x25 is not chosen as LF is made to correspond to the Unicode NEL character (which, in Unicode, is 0x85). -

    -

    +

    +

    The options that select newline behaviour, such as --enable-newline-is-cr, and equivalent run-time options, refer to these character values in an EBCDIC environment. -

    +


    PCRE2GREP SUPPORT FOR EXTERNAL SCRIPTS
    -

    +

    By default pcre2grep supports the use of callouts with string arguments within the patterns it is matching. There are two kinds: one that generates output using local code, and another that calls an external program or script. @@ -435,9 +435,9 @@

    pcre2build man page

    callouts, see the pcre2grep documentation. -

    +


    PCRE2GREP OPTIONS FOR COMPRESSED FILE SUPPORT
    -

    +

    By default, pcre2grep reads all files as plain text. You can build it so that it recognizes files whose names end in .gz or .bz2, and reads them with libz or libbz2, respectively, by adding one or both of @@ -448,9 +448,9 @@

    pcre2build man page

    to the configure command. These options naturally require that the relevant libraries are installed on your system. Configuration will fail if they are not. -

    +


    PCRE2GREP BUFFER SIZE
    -

    +

    pcre2grep uses an internal buffer to hold a "window" on the file it is scanning, in order to be able to output "before" and "after" lines when it finds a match. The default starting size of the buffer is 20KiB. The buffer @@ -466,9 +466,9 @@

    pcre2build man page

    to the configure command. The caller of pcre2grep can override these values by using --buffer-size and --max-buffer-size on the command line. -

    +


    PCRE2TEST OPTION FOR LIBREADLINE SUPPORT
    -

    +

    If you add one of 

       --enable-pcre2test-libreadline
@@ -481,8 +481,8 @@ 
    pcre2build man page
    
 GPL-licensed, so if you distribute a binary of pcre2test linked in this
 way, there may be licensing issues. These can be avoided by linking instead
 with libedit, which has a BSD licence.
-
    
-
    
+
    
+
    
 Setting --enable-pcre2test-libreadline causes the -lreadline option to be
 added to the pcre2test build. In many operating environments with a
 system-installed readline library this is sufficient. However, in some
@@ -500,18 +500,18 @@ 
    pcre2build man page
    
   LIBS="-ncurses"
    immediately before the configure command. -

    +


    INCLUDING DEBUGGING CODE
    -

    +

    If you add 

       --enable-debug
    to the configure command, additional debugging code is included in the build. This feature is intended for use by the PCRE2 maintainers. -

    +


    DEBUGGING WITH VALGRIND SUPPORT
    -

    +

    If you add 

       --enable-valgrind
@@ -519,9 +519,9 @@ 
    pcre2build man page
    
 to the configure command, PCRE2 will use valgrind annotations to mark
 certain memory regions as unaddressable. This allows it to detect invalid
 memory accesses, and is mostly useful for debugging PCRE2 itself.
-
    
+
    
 
    CODE COVERAGE REPORTING
    
-
    
+
    
 If your C compiler is gcc, you can build a version of PCRE2 that can generate a
 code coverage report for its test suite. To enable this, you must install
 lcov version 1.6 or above. Then specify
@@ -529,8 +529,8 @@ 
    pcre2build man page
    
   --enable-coverage
    to the configure command and build PCRE2 in the usual way. -

    -

    +

    +

    Note that using ccache (a caching C compiler) is incompatible with code coverage reporting. If you have configured ccache to run automatically on your system, you must set the environment variable @@ -538,8 +538,8 @@

    pcre2build man page

    CCACHE_DISABLE=1 before running make to build PCRE2, so that ccache is not used. -

    -

    +

    +

    When --enable-coverage is used, the following addition targets are added to the Makefile: 

    @@ -576,9 +576,9 @@ 
    pcre2build man page
    
 This cleans all coverage data including the generated coverage report. For more
 information about code coverage, see the gcov and lcov
 documentation.
-
    
+
    
 
    DISABLING THE Z AND T FORMATTING MODIFIERS
    
-
    
+
    
 The C99 standard defines formatting modifiers z and t for size_t and
 ptrdiff_t values, respectively. By default, PCRE2 uses these modifiers in
 environments other than old versions of Microsoft Visual Studio when
@@ -591,9 +591,9 @@ 
    pcre2build man page
    is specified, no use is made of the z or t modifiers. Instead of %td or %zu, a suitable format is used depending in the size of long for the platform. -

    +


    SUPPORT FOR FUZZERS
    -

    +

    There is a special option for use by people who want to run fuzzing tests on PCRE2: 

    @@ -606,8 +606,8 @@ 
    pcre2build man page
    
 tries to compile the string as a pattern, and if that succeeds, to match it.
 This is done both with no options and with some random options bits that are
 generated from the string.
-
    
-
    
+
    
+
    
 Setting --enable-fuzz-support also causes a binary called pcre2fuzzcheck
 to be created. This is normally run under valgrind or used when PCRE2 is
 compiled with address sanitizing enabled. It calls the fuzzing function and
@@ -615,9 +615,9 @@ 
    pcre2build man page
    
 arguments: if an argument starts with "=" the rest of it is a literal input
 string. Otherwise, it is assumed to be a file name, and the contents of the
 file are the test string.
-
    
+
    
 
    OBSOLETE OPTION
    
-
    
+
    
 In versions of PCRE2 prior to 10.30, there were two ways of handling
 backtracking in the pcre2_match() function. The default was to use the
 system stack, but if
@@ -627,22 +627,22 @@ 
    pcre2build man page
    
 was set, memory on the heap was used. From release 10.30 onwards this has
 changed (the stack is no longer used) and this option now does nothing except
 give a warning.
-
    
+
    
 
    SEE ALSO
    
-
    
+
    
 pcre2api(3), pcre2-config(3).
-
    
+
    
 
    AUTHOR
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    REVISION
    
-
    
+
    
 Last updated: 16 April 2024
 
    
 Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/html/pcre2callout.html b/doc/html/pcre2callout.html
index cdb65ad63..d1cb75ae8 100644
--- a/doc/html/pcre2callout.html
+++ b/doc/html/pcre2callout.html
@@ -23,35 +23,35 @@ 
    pcre2callout man page
    
 
  • REVISION
 
 
    SYNOPSIS
    
-
    
+
    
 #include <pcre2.h>
-
    
-
    
+
    
+
    
 int (*pcre2_callout)(pcre2_callout_block *, void *);
 
    
 
    
 int pcre2_callout_enumerate(const pcre2_code *code,
   int (*callback)(pcre2_callout_enumerate_block *, void *),
   void *user_data);
-
    
+
    
 
    DESCRIPTION
    
-
    
+
    
 PCRE2 provides a feature called "callout", which is a means of temporarily
 passing control to the caller of PCRE2 in the middle of pattern matching. The
 caller of PCRE2 provides an external function by putting its entry point in
 a match context (see pcre2_set_callout() in the
 pcre2api
 documentation).
-
    
-
    
+
    
+
    
 When using the pcre2_substitute() function, an additional callout feature
 is available. This does a callout after each change to the subject string and
 is described in the
 pcre2api
 documentation; the rest of this document is concerned with callouts during
 pattern matching.
-
    
-
    
+
    
+
    
 Within a regular expression, (?C<arg>) indicates a point at which the external
 function is to be called. Different callout points can be identified by putting
 a number less than 256 after the letter C. The default value is zero.
@@ -91,25 +91,25 @@ 
    pcre2callout man page
    • This applies only to assertion conditions (because they are themselves independent groups). -

    -

    +

    +

    Callouts can be useful for tracking the progress of pattern matching. The pcre2test program has a pattern qualifier (/auto_callout) that sets automatic callouts. When any callouts are present, the output from pcre2test indicates how the pattern is being matched. This is useful information when you are trying to optimize the performance of a particular pattern. -

    +


    MISSING CALLOUTS
    -

    +

    You should be aware that, because of optimizations in the way PCRE2 compiles and matches patterns, callouts sometimes do not happen exactly as you might expect. -

    +


    Auto-possessification
    -

    +

    At compile time, PCRE2 "auto-possessifies" repeated items when it knows that what follows cannot be part of the repeat. For example, a+[bc] is compiled as if it were a++[bc]. The pcre2test output when this pattern is compiled @@ -137,25 +137,25 @@

    pcre2callout man page

    This time, when matching [bc] fails, the matcher backtracks into a+ and tries again, repeatedly, until a+ itself fails. -

    +


    Automatic .* anchoring
    -

    +

    By default, an optimization is applied when .* is the first significant item in a pattern. If PCRE2_DOTALL is set, so that the dot can match any character, the pattern is automatically anchored. If PCRE2_DOTALL is not set, a match can start only after an internal newline or at the beginning of the subject, and pcre2_compile() remembers this. If a pattern has more than one top-level branch, automatic anchoring occurs if all branches are anchorable. -

    -

    +

    +

    This optimization is disabled, however, if .* is in an atomic group or if there is a backreference to the capture group in which it appears. It is also disabled if the pattern contains (*PRUNE) or (*SKIP). However, the presence of callouts does not affect it. -

    -

    +

    +

    For example, if the pattern .*\d is compiled with PCRE2_AUTO_CALLOUT and applied to the string "aa", the pcre2test output is: 

    @@ -184,11 +184,11 @@ 
    pcre2callout man page
    
 This shows more match attempts, starting at the second subject character.
 Another optimization, described in the next section, means that there is no
 subsequent attempt to match with an empty subject.
-
    
+
    
 
    
 Other optimizations
 
    
-
    
+
    
 Other optimizations that provide fast "no match" results also affect callouts.
 For example, if the pattern is
 
    @@ -198,21 +198,21 @@ 
    pcre2callout man page
    
 subject string is "abyz", the lack of "d" means that matching doesn't ever
 start, and the callout is never reached. However, with "abyd", though the
 result is still no match, the callout is obeyed.
-
    
-
    
+
    
+
    
 For most patterns PCRE2 also knows the minimum length of a matching string, and
 will immediately give a "no match" return without actually running a match if
 the subject is not long enough, or, for unanchored patterns, if it has been
 scanned far enough.
-
    
-
    
+
    
+
    
 You can disable these optimizations by passing the PCRE2_NO_START_OPTIMIZE
 option to pcre2_compile(), or by starting the pattern with
 (*NO_START_OPT). This slows down the matching process, but does ensure that
 callouts such as the example above are obeyed.
-
    
+
    
 
    THE CALLOUT INTERFACE
    
-
    
+
    
 During matching, when PCRE2 reaches a callout point, if an external function is
 provided in the match context, it is called. This applies to both normal,
 DFA, and JIT matching. The first argument to the callout function is a pointer
@@ -247,20 +247,20 @@ 
    pcre2callout man page
    
 version number before accessing any of these fields. The version number will
 increase in future if more fields are added, but the intention is never to
 remove any of the existing fields.
-
    
+
    
 
    
 Fields for numerical callouts
 
    
-
    
+
    
 For a numerical callout, callout_string is NULL, and callout_number
 contains the number of the callout, in the range 0-255. This is the number
 that follows (?C for callouts that part of the pattern; it is 255 for
 automatically generated callouts.
-
    
+
    
 
    
 Fields for string callouts
 
    
-
    
+
    
 For callouts with string arguments, callout_number is always zero, and
 callout_string points to the string that is contained within the compiled
 pattern. Its length is given by callout_string_length. Duplicated ending
@@ -271,34 +271,34 @@ 
    pcre2callout man page
    
 the string is also stored within the pattern, immediately before the string
 itself. You can access this delimiter as callout_string[-1] if you need
 it.
-
    
-
    
+
    
+
    
 The callout_string_offset field is the code unit offset to the start of
 the callout argument string within the original pattern string. This is
 provided for the benefit of applications such as script languages that might
 need to report errors in the callout string within the pattern.
-
    
+
    
 
    
 Fields for all callouts
 
    
-
    
+
    
 The remaining fields in the callout block are the same for both kinds of
 callout.
-
    
-
    
+
    
+
    
 The offset_vector field is a pointer to a vector of capturing offsets
 (the "ovector"). You may read the elements in this vector, but you must not
 change any of them.
-
    
-
    
+
    
+
    
 For calls to pcre2_match(), the offset_vector field is not (since
 release 10.30) a pointer to the actual ovector that was passed to the matching
 function in the match data block. Instead it points to an internal ovector of a
 size large enough to hold all possible captured substrings in the pattern. Note
 that whenever a recursion or subroutine call within a pattern completes, the
 capturing state is reset to what it was before.
-
    
-
    
+
    
+
    
 The capture_last field contains the number of the most recently captured
 substring, and the capture_top field contains one more than the number of
 the highest numbered captured substring so far. If no substrings have yet been
@@ -306,8 +306,8 @@ 
    pcre2callout man page
    
 capture_top is 1. The values of these fields do not always differ by one;
 for example, when the callout in the pattern ((a)(b))(?C2) is taken,
 capture_last is 1 but capture_top is 4.
-
    
-
    
+
    
+
    
 The contents of ovector[2] to ovector[<capture_top>*2-1] can be inspected in
 order to extract substrings that have been matched so far, in the same way as
 extracting substrings after a match has completed. The values in ovector[0] and
@@ -315,8 +315,8 @@ 
    pcre2callout man page
    
 complete. Substrings that have not been captured but whose numbers are less
 than capture_top also have both of their ovector slots set to
 PCRE2_UNSET.
-
    
-
    
+
    
+
    
 For DFA matching, the offset_vector field points to the ovector that was
 passed to the matching function in the match data block for callouts at the top
 level, but to an internal ovector during the processing of pattern recursions,
@@ -324,28 +324,28 @@ 
    pcre2callout man page
    
 information because pcre2_dfa_match() does not support substring
 capturing. The value of capture_top is always 1 and the value of
 capture_last is always 0 for DFA matching.
-
    
-
    
+
    
+
    
 The subject and subject_length fields contain copies of the values
 that were passed to the matching function.
-
    
-
    
+
    
+
    
 The start_match field normally contains the offset within the subject at
 which the current match attempt started. However, if the escape sequence \K
 has been encountered, this value is changed to reflect the modified starting
 point. If the pattern is not anchored, the callout function may be called
 several times from the same point in the pattern for different starting points
 in the subject.
-
    
-
    
+
    
+
    
 The current_position field contains the offset within the subject of the
 current match pointer.
-
    
-
    
+
    
+
    
 The pattern_position field contains the offset in the pattern string to
 the next item to be matched.
-
    
-
    
+
    
+
    
 The next_item_length field contains the length of the next item to be
 processed in the pattern string. When the callout is at the end of the pattern,
 the length is zero. When the callout precedes an opening parenthesis, the
@@ -356,22 +356,22 @@ 
    pcre2callout man page
    
 changed in release 10.23. In earlier releases, before an opening parenthesis
 the length was that of the entire group, and before an alternation bar or a
 closing parenthesis the length was zero.)
-
    
-
    
+
    
+
    
 The pattern_position and next_item_length fields are intended to
 help in distinguishing between different automatic callouts, which all have the
 same callout number. However, they are set for all callouts, and are used by
 pcre2test to show the next item to be matched when displaying callout
 information.
-
    
-
    
+
    
+
    
 In callouts from pcre2_match() the mark field contains a pointer to
 the zero-terminated name of the most recently passed (*MARK), (*PRUNE), or
 (*THEN) item in the match, or NULL if no such items have been passed. Instances
 of (*PRUNE) or (*THEN) without a name do not obliterate a previous (*MARK). In
 callouts from the DFA matching function this field always contains NULL.
-
    
-
    
+
    
+
    
 The callout_flags field is always zero in callouts from
 pcre2_dfa_match() or when JIT is being used. When pcre2_match()
 without JIT is used, the following bits may be set:
@@ -386,13 +386,13 @@ 
    pcre2callout man page
    
 This is set if there has been a matching backtrack since the previous callout,
 or since the start of matching if this is the first callout from a
 pcre2_match() run.
-
    
-
    
+
    
+
    
 Both bits are set when a backtrack has caused a "bumpalong" to a new starting
 position in the subject. Output from pcre2test does not indicate the
 presence of these bits unless the callout_extra modifier is set.
-
    
-
    
+
    
+
    
 The information in the callout_flags field is provided so that
 applications can track and tell their users how matching with backtracking is
 done. This can be useful when trying to optimize patterns, or just to
@@ -400,24 +400,24 @@ 
    pcre2callout man page
    
 because there is no backtracking in DFA matching, and there is no support in
 JIT because JIT is all about maximimizing matching performance. In both these
 cases the callout_flags field is always zero.
-
    
+
    
 
    RETURN VALUES FROM CALLOUTS
    
-
    
+
    
 The external callout function returns an integer to PCRE2. If the value is
 zero, matching proceeds as normal. If the value is greater than zero, matching
 fails at the current point, but the testing of other matching possibilities
 goes ahead, just as if a lookahead assertion had failed. If the value is less
 than zero, the match is abandoned, and the matching function returns the
 negative value.
-
    
-
    
+
    
+
    
 Negative values should normally be chosen from the set of PCRE2_ERROR_xxx
 values. In particular, PCRE2_ERROR_NOMATCH forces a standard "no match"
 failure. The error number PCRE2_ERROR_CALLOUT is reserved for use by callout
 functions; it will never be used by PCRE2 itself.
-
    
+
    
 
    CALLOUT ENUMERATION
    
-
    
+
    
 int pcre2_callout_enumerate(const pcre2_code *code,
   int (*callback)(pcre2_callout_enumerate_block *, void *),
   void *user_data);
@@ -446,31 +446,31 @@ 
    pcre2callout man page
    
 pcre2_callout block that is used for callouts during matching, as
 described
 above.
-
    
-
    
+
    
+
    
 Note that the value of pattern_position is unique for each callout.
 However, if a callout occurs inside a group that is quantified with a non-zero
 minimum or a fixed maximum, the group is replicated inside the compiled
 pattern. For example, a pattern such as /(a){2}/ is compiled as if it were
 /(a)(a)/. This means that the callout will be enumerated more than once, but
 with the same value for pattern_position in each case.
-
    
-
    
+
    
+
    
 The callback function should normally return zero. If it returns a non-zero
 value, scanning the pattern stops, and that value is returned from
 pcre2_callout_enumerate().
-
    
+
    
 
    AUTHOR
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    REVISION
    
-
    
+
    
 Last updated: 19 January 2024
 
    
 Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/html/pcre2compat.html b/doc/html/pcre2compat.html
index 5f7e280d3..85a2e58fc 100644
--- a/doc/html/pcre2compat.html
+++ b/doc/html/pcre2compat.html
@@ -15,13 +15,13 @@ 
    pcre2compat man page
    
 
    
 DIFFERENCES BETWEEN PCRE2 AND PERL
 
    
-
    
+
    
 This document describes some of the known differences in the ways that PCRE2
 and Perl handle regular expressions. The differences described here are with
 respect to Perl version 5.38.0, but as both Perl and PCRE2 are continually
 changing, the information may at times be out of date.
-
    
-
    
+
    
+
    
 1. When PCRE2_DOTALL (equivalent to Perl's /s qualifier) is not set, the
 behaviour of the '.' metacharacter differs from Perl. In PCRE2, '.' matches the
 next character unless it is the start of a newline sequence. This means that,
@@ -29,14 +29,14 @@ 
    pcre2compat man page
    
 (0x0A) in ASCII/Unicode environments, and NL (either 0x15 or 0x25) when using
 EBCDIC. In Perl, '.' appears never to match LF, even when 0x0A is not a newline
 indicator.
-
    
-
    
+
    
+
    
 2. PCRE2 has only a subset of Perl's Unicode support. Details of what it does
 have are given in the
 pcre2unicode
 page.
-
    
-
    
+
    
+
    
 3. Like Perl, PCRE2 allows repeat quantifiers on parenthesized assertions, but
 they do not mean what you might think. For example, (?!a){3} does not assert
 that the next three characters are not "a". It just asserts that the next
@@ -44,19 +44,19 @@ 
    pcre2compat man page
    
 assertion just once). Perl allows some repeat quantifiers on other assertions,
 for example, \b* , but these do not seem to have any use. PCRE2 does not allow
 any kind of quantifier on non-lookaround assertions.
-
    
-
    
+
    
+
    
 4. If a braced quantifier such as {1,2} appears where there is nothing to
 repeat (for example, at the start of a branch), PCRE2 raises an error whereas
 Perl treats the quantifier characters as literal.
-
    
-
    
+
    
+
    
 5. Capture groups that occur inside negative lookaround assertions are counted,
 but their entries in the offsets vector are set only when a negative assertion
 is a condition that has a matching branch (that is, the condition is false).
 Perl may set such capture groups in other circumstances.
-
    
-
    
+
    
+
    
 6. The following Perl escape sequences are not supported: \F, \l, \L, \u,
 \U, and \N when followed by a character name. \N on its own, matching a
 non-newline character, and \N{U+dd..}, matching a Unicode code point, are
@@ -66,8 +66,8 @@ 
    pcre2compat man page
    
 generated by default. However, if either of the PCRE2_ALT_BSUX or
 PCRE2_EXTRA_ALT_BSUX options is set, \U and \u are interpreted as ECMAScript
 interprets them.
-
    
-
    
+
    
+
    
 7. The Perl escape sequences \p, \P, and \X are supported only if PCRE2 is
 built with Unicode support (the default). The properties that can be tested
 with \p and \P are limited to the general category properties such as Lu and
@@ -79,8 +79,8 @@ 
    pcre2compat man page
    
 documentation for details. The long synonyms for property names that Perl
 supports (such as \p{Letter}) are not supported by PCRE2, nor is it permitted
 to prefix any of these properties with "Is".
-
    
-
    
+
    
+
    
 8. PCRE2 supports the \Q...\E escape for quoting substrings. Characters
 in between are treated as literals. However, this is slightly different from
 Perl in that $ and @ are also handled as literals inside the quotes. In Perl,
@@ -105,20 +105,20 @@ 
    pcre2compat man page
    
 (redundantly) either of the numbers is inside \Q...\E, but not if the
 separating comma is. When not recognized as a quantifier a sequence such as
 {\Q1\E,2} is treated as the literal string "{1,2}".
-
    
-
    
+
    
+
    
 9. Fairly obviously, PCRE2 does not support the (?{code}) and (??{code})
 constructions. However, PCRE2 does have a "callout" feature, which allows an
 external function to be called during pattern matching. See the
 pcre2callout
 documentation for details.
-
    
-
    
+
    
+
    
 10. Subroutine calls (whether recursive or not) were treated as atomic groups
 up to PCRE2 release 10.23, but from release 10.30 this changed, and
 backtracking into subroutine calls is now supported, as in Perl.
-
    
-
    
+
    
+
    
 11. In PCRE2, if any of the backtracking control verbs are used in a group that
 is called as a subroutine (whether or not recursively), their effect is
 confined to that group; it does not extend to the surrounding pattern. This is
@@ -128,21 +128,21 @@ 
    pcre2compat man page
    
 processed as anchored at the point where they are tested. PCRE2 also confines
 all control verbs within atomic assertions, again including (*THEN) in
 assertions with only one branch.
-
    
-
    
+
    
+
    
 12. If a pattern contains more than one backtracking control verb, the first
 one that is backtracked onto acts. For example, in the pattern
 A(*COMMIT)B(*PRUNE)C a failure in B triggers (*COMMIT), but a failure in C
 triggers (*PRUNE). Perl's behaviour is more complex; in many cases it is the
 same as PCRE2, but there are cases where it differs.
-
    
-
    
+
    
+
    
 13. There are some differences that are concerned with the settings of captured
 strings when part of a pattern is repeated. For example, matching "aba" against
 the pattern /^(a(b)?)+$/ in Perl leaves $2 unset, but in PCRE2 it is set to
 "b".
-
    
-
    
+
    
+
    
 14. PCRE2's handling of duplicate capture group numbers and names is not as
 general as Perl's. This is a consequence of the fact the PCRE2 works internally
 just with numbers, using an external table to translate between numbers and
@@ -151,35 +151,35 @@ 
    pcre2compat man page
    
 causes an error at compile time. If it were allowed, it would not be possible
 to distinguish which group matched, because both names map to capture group
 number 1. To avoid this confusing situation, an error is given at compile time.
-
    
-
    
+
    
+
    
 15. Perl used to recognize comments in some places that PCRE2 does not, for
 example, between the ( and ? at the start of a group. If the /x modifier is
 set, Perl allowed white space between ( and ? though the latest Perls give an
 error (for a while it was just deprecated). There may still be some cases where
 Perl behaves differently.
-
    
-
    
+
    
+
    
 16. Perl, when in warning mode, gives warnings for character classes such as
 [A-\d] or [a-[:digit:]]. It then treats the hyphens as literals. PCRE2 has no
 warning features, so it gives an error in these cases because they are almost
 certainly user mistakes.
-
    
-
    
+
    
+
    
 17. In PCRE2, until release 10.45, the upper/lower case character properties Lu
 and Ll were not affected when case-independent matching was specified. Perl has
 changed in this respect, and PCRE2 has now changed to match. When caseless
 matching is in force, Lu, Ll, and Lt (title case) are all treated as Lc (cased
 letter).
-
    
-
    
+
    
+
    
 18. From release 5.32.0, Perl locks out the use of \K in lookaround
 assertions. From release 10.38 PCRE2 does the same by default. However, there
 is an option for re-enabling the previous behaviour. When this option is set,
 \K is acted on when it occurs in positive assertions, but is ignored in
 negative assertions.
-
    
-
    
+
    
+
    
 19. PCRE2 provides some extensions to the Perl regular expression facilities.
 Perl 5.10 included new features that were not in earlier versions of Perl, some
 of which (such as named parentheses) were in PCRE2 for some time before. This
@@ -242,54 +242,54 @@ 
    pcre2compat man page
    
 
    
 (m) The scan substring assertion (syntax (*scs:(n)...)) is a PCRE2 extension
 that is not available in Perl.
-
    
-
    
+
    
+
    
 20. Perl has different limits than PCRE2. See the
-pcre2limit
+pcre2limits
 documentation for details. Perl went with 5.10 from recursion to iteration
 keeping the intermediate matches on the heap, which is ~10% slower but does not
 fall into any stack-overflow limit. PCRE2 made a similar change at release
 10.30, and also has many build-time and run-time customizable limits.
-
    
-
    
+
    
+
    
 21. Unlike Perl, PCRE2 doesn't have character set modifiers and specially no way
 to set characters by context just like Perl's "/d". A regular expression using
 PCRE2_UTF and PCRE2_UCP will use similar rules to Perl's "/u"; something closer
 to "/a" could be selected by adding other PCRE2_EXTRA_ASCII* options on top.
-
    
-
    
+
    
+
    
 22. Some recursive patterns that Perl diagnoses as infinite recursions can be
 handled by PCRE2, either by the interpreter or the JIT. An example is
 /(?:|(?0)abcd)(?(R)|\z)/, which matches a sequence of any number of repeated
 "abcd" substrings at the end of the subject.
-
    
-
    
+
    
+
    
 23. Both PCRE2 and Perl error when \x{ escapes are invalid, but Perl tries to
 recover and prints a warning if the problem was that an invalid hexadecimal
 digit was found, since PCRE2 doesn't have warnings it returns an error instead.
 Additionally, Perl accepts \x{} and generates NUL unlike PCRE2.
-
    
-
    
+
    
+
    
 24. From release 10.45, PCRE2 gives an error if \x is not followed by a
 hexadecimal digit or a curly bracket. It used to interpret this as the NUL
 character. Perl still generates NUL, but warns when in warning mode in most
 cases.
-
    
+
    
 
    
 AUTHOR
 
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    
 REVISION
 
    
-
    
+
    
 Last updated: 02 October 2024
 
    
 Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/html/pcre2convert.html b/doc/html/pcre2convert.html
index 57e8989fb..1ac7f437e 100644
--- a/doc/html/pcre2convert.html
+++ b/doc/html/pcre2convert.html
@@ -22,14 +22,14 @@ 
    pcre2convert man page
    
 
  • REVISION
 
 
    EXPERIMENTAL PATTERN CONVERSION FUNCTIONS
    
-
    
+
    
 This document describes a set of functions that can be used to convert
 "foreign" patterns into PCRE2 regular expressions. This facility is currently
 experimental, and may be changed in future releases. Two kinds of pattern,
 globs and POSIX patterns, are supported.
-
    
+
    
 
    THE CONVERT CONTEXT
    
-
    
+
    
 pcre2_convert_context *pcre2_convert_context_create(
   pcre2_general_context *gcontext);
 
    
@@ -55,21 +55,21 @@ 
    pcre2convert man page
    
 functions. If custom memory management functions are set in a general context
 that is passed to pcre2_convert_context_create(), they are used for all
 memory management within the conversion functions.
-
    
-
    
+
    
+
    
 There are only two parameters in the convert context at present. Both apply
 only to glob conversions. The escape character defaults to grave accent under
 Windows, otherwise backslash. It can be set to zero, meaning no escape
 character, or to any punctuation character with a code point less than 256.
 The separator character defaults to backslash under Windows, otherwise forward
 slash. It can be set to forward slash, backslash, or dot.
-
    
-
    
+
    
+
    
 The two setting functions return zero on success, or PCRE2_ERROR_BADDATA if
 their second argument is invalid.
-
    
+
    
 
    THE CONVERSION FUNCTION
    
-
    
+
    
 int pcre2_pattern_convert(PCRE2_SPTR pattern, PCRE2_SIZE length,
   uint32_t options, PCRE2_UCHAR **buffer,
   PCRE2_SIZE *blength, pcre2_convert_context *cvcontext);
@@ -94,94 +94,94 @@ 
    pcre2convert man page
    
 
    • 
 Details of the conversions are given below. The buffer and blength
 arguments define how the output is handled:
-
    
-
    
+
    
+
    
 If buffer is NULL, the function just returns the length of the converted
 pattern via blength. This is one less than the length of buffer needed,
 because a terminating zero is always added to the output.
-
    
-
    
+
    
+
    
 If buffer points to a NULL pointer, an output buffer is obtained using
 the allocator in the context or malloc() if no context is supplied. A
 pointer to this buffer is placed in the variable to which buffer points.
 When no longer needed the output buffer must be freed by calling
 pcre2_converted_pattern_free(). If this function is called with a NULL
 argument, it returns immediately without doing anything.
-
    
-
    
+
    
+
    
 If buffer points to a non-NULL pointer, blength must be set to the
 actual length of the buffer provided (in code units).
-
    
-
    
+
    
+
    
 In all cases, after successful conversion, the variable pointed to by
 blength is updated to the length actually used (in code units), excluding
 the terminating zero that is always added.
-
    
-
    
+
    
+
    
 If an error occurs, the length (via blength) is set to the offset
 within the input pattern where the error was detected. Only gross syntax errors
 are caught; there are plenty of errors that will get passed on for
 pcre2_compile() to discover.
-
    
-
    
+
    
+
    
 The return from pcre2_pattern_convert() is zero on success or a non-zero
 PCRE2 error code. Note that PCRE2 error codes may be positive or negative:
 pcre2_compile() uses mostly positive codes and pcre2_match()
 negative ones; pcre2_convert() uses existing codes of both kinds. A
 textual error message can be obtained by calling
 pcre2_get_error_message().
-
    
+
    
 
    CONVERTING GLOBS
    
-
    
+
    
 Globs are used to match file names, and consequently have the concept of a
 "path separator", which defaults to backslash under Windows and forward slash
 otherwise. If PCRE2_CONVERT_GLOB is set, the wildcards * and ? are not
 permitted to match separator characters, but the double-star (**) feature
 (which does match separators) is supported.
-
    
-
    
+
    
+
    
 PCRE2_CONVERT_GLOB_NO_WILD_SEPARATOR matches globs with wildcards allowed to
 match separator characters. PCRE2_CONVERT_GLOB_NO_STARSTAR matches globs with
 the double-star feature disabled. These options may be given together.
-
    
+
    
 
    CONVERTING POSIX PATTERNS
    
-
    
+
    
 POSIX defines two kinds of regular expression pattern: basic and extended.
 These can be processed by setting PCRE2_CONVERT_POSIX_BASIC or
 PCRE2_CONVERT_POSIX_EXTENDED, respectively.
-
    
-
    
+
    
+
    
 In POSIX patterns, backslash is not special in a character class. Unmatched
 closing parentheses are treated as literals.
-
    
-
    
+
    
+
    
 In basic patterns, ? + | {} and () must be escaped to be recognized
 as metacharacters outside a character class. If the first character in the
 pattern is * it is treated as a literal. ^ is a metacharacter only at the start
 of a branch.
-
    
-
    
+
    
+
    
 In extended patterns, a backslash not in a character class always
 makes the next character literal, whatever it is. There are no backreferences.
-
    
-
    
+
    
+
    
 Note: POSIX mandates that the longest possible match at the first matching
 position must be found. This is not what pcre2_match() does; it yields
 the first match that is found. An application can use pcre2_dfa_match()
 to find the longest match, but that does not support backreferences (but then
 neither do POSIX extended patterns).
-
    
+
    
 
    AUTHOR
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    REVISION
    
-
    
+
    
 Last updated: 14 November 2023
 
    
 Copyright © 1997-2018 University of Cambridge.
diff --git a/doc/html/pcre2demo.html b/doc/html/pcre2demo.html
index 1cb7e0a7d..3c2279ea2 100644
--- a/doc/html/pcre2demo.html
+++ b/doc/html/pcre2demo.html
@@ -15,7 +15,7 @@ 
    pcre2demo man page
    
 
    
 SOURCE CODE
 
    
-
    +
     /*************************************************
 *           PCRE2 DEMONSTRATION PROGRAM          *
 *************************************************/
diff --git a/doc/html/pcre2grep.html b/doc/html/pcre2grep.html
index 5c9a57a59..16041ba6a 100644
--- a/doc/html/pcre2grep.html
+++ b/doc/html/pcre2grep.html
@@ -31,11 +31,11 @@ 
    pcre2grep man page
    
 
  • REVISION
 
 
    SYNOPSIS
    
-
    
+
    
 pcre2grep [options] [long options] [pattern] [path1 path2 ...]
-
    
+
    
 
    DESCRIPTION
    
-
    
+
    
 pcre2grep searches files for character patterns, in the same way as other
 grep commands do, but it uses the PCRE2 regular expression library to support
 patterns that are compatible with the regular expressions of Perl 5. See
@@ -44,8 +44,8 @@ 
    pcre2grep man page
    
 pcre2pattern(3)
 for a full description of the syntax and semantics of the regular expressions
 that PCRE2 supports.
-
    
-
    
+
    
+
    
 Patterns, whether supplied on the command line or in a separate file, are given
 without delimiters. For example:
 
    @@ -56,15 +56,15 @@ 
    pcre2grep man page
    
 pattern. Quotes can of course be used to delimit patterns on the command line
 because they are interpreted by the shell, and indeed quotes are required if a
 pattern contains white space or shell metacharacters.
-
    
-
    
+
    
+
    
 The first argument that follows any option settings is treated as the single
 pattern to be matched when neither -e nor -f is present.
 Conversely, when one or both of these options are used to specify patterns, all
 arguments are treated as path names. At least one of -e, -f, or an
 argument pattern must be provided.
-
    
-
    
+
    
+
    
 If no files are specified, pcre2grep reads the standard input. The
 standard input can also be referenced by a name consisting of a single hyphen.
 For example:
@@ -81,8 +81,8 @@ 
    pcre2grep man page
    
 defines a line boundary is controlled by the -N (--newline) option.
 The -h and -H options control whether or not file names are shown,
 and the -Z option changes the file name terminator to a zero byte.
-
    
-
    
+
    
+
    
 The amount of memory used for buffering files that are being scanned is
 controlled by parameters that can be set by the --buffer-size and
 --max-buffer-size options. The first of these sets the size of buffer
@@ -93,24 +93,24 @@ 
    pcre2grep man page
    
 built; if nothing is specified, the defaults are set to 20KiB and 1MiB
 respectively. An error occurs if a line is too long and the buffer can no
 longer be expanded.
-
    
-
    
+
    
+
    
 The block of memory that is actually used is three times the "buffer size", to
 allow for buffering "before" and "after" lines. If the buffer size is too
 small, fewer than requested "before" and "after" lines may be output.
-
    
-
    
+
    
+
    
 When matching with a multiline pattern, the size of the buffer must be at least
 half of the maximum match expected or the pattern might fail to match.
-
    
-
    
+
    
+
    
 Patterns can be no longer than 8KiB or BUFSIZ bytes, whichever is the greater.
 BUFSIZ is defined in <stdio.h>. When there is more than one pattern
 (specified by the use of -e and/or -f), each pattern is applied to
 each line in the order in which they are defined, except that all the -e
 patterns are tried before the -f patterns.
-
    
-
    
+
    
+
    
 By default, as soon as one pattern matches a line, no further patterns are
 considered. However, if --colour (or --color) is used to colour the
 matching substrings, or if --only-matching, --file-offsets,
@@ -121,31 +121,31 @@ 
    pcre2grep man page
    
 subject is processed; if there is more than one match at that position, the one
 with the longest matching substring is processed; if the matching substrings
 are equal, the first match found is processed.
-
    
-
    
+
    
+
    
 Scanning with all the patterns resumes immediately following the match, so that
 later matches on the same line can be found. Note, however, that an overlapping
 match that starts in the middle of another match will not be processed.
-
    
-
    
+
    
+
    
 The above behaviour was changed at release 10.41 to be more compatible with GNU
 grep. In earlier releases, pcre2grep did not recognize matches from
 later patterns that were earlier in the subject.
-
    
-
    
+
    
+
    
 Patterns that can match an empty string are accepted, but empty string
 matches are never recognized. An example is the pattern "(super)?(man)?", in
 which all components are optional. This pattern finds all occurrences of both
 "super" and "man"; the output differs from matching with "super|man" when only
 the matching substrings are being shown.
-
    
-
    
+
    
+
    
 If the LC_ALL or LC_CTYPE environment variable is set,
 pcre2grep uses the value to set a locale when calling the PCRE2 library.
 The --locale option can be used to override this.
-
    
+
    
 
    SUPPORT FOR COMPRESSED FILES
    
-
    
+
    
 Compile-time options for pcre2grep can set it up to use libz or
 libbz2 for reading compressed files whose names end in .gz or
 .bz2, respectively. You can find out whether your pcre2grep binary
@@ -155,37 +155,37 @@ 
    pcre2grep man page
    
 a .gz or .bz2 extension is not in fact compressed, it is read as a
 plain text file. When input is from a compressed .gz or .bz2 file, the
 --line-buffered option is ignored.
-
    
+
    
 
    BINARY FILES
    
-
    
+
    
 By default, a file that contains a binary zero byte within the first 1024 bytes
 is identified as a binary file, and is processed specially. However, if the
 newline type is specified as NUL, that is, the line terminator is a binary
 zero, the test for a binary file is not applied. See the --binary-files
 option for a means of changing the way binary files are handled.
-
    
+
    
 
    BINARY ZEROS IN PATTERNS
    
-
    
+
    
 Patterns passed from the command line are strings that are terminated by a
 binary zero, so cannot contain internal zeros. However, patterns that are read
 from a file via the -f option may contain binary zeros.
-
    
+
    
 
    OPTIONS
    
-
    
+
    
 The order in which some of the options appear can affect the output. For
 example, both the -H and -l options affect the printing of file
 names. Whichever comes later in the command line will be the one that takes
 effect. Similarly, except where noted below, if an option is given twice, the
 later setting is used. Numerical values for options may be followed by K or M,
 to signify multiplication by 1024 or 1024*1024 respectively.
-
    
-
    
+
    
+
    
 --
 This terminates the list of options. It is useful if the next item on the
 command line starts with a hyphen but is not an option. This allows for the
 processing of patterns and file names that start with hyphens.
-
    
-
    
+
    
+
    
 -A number, --after-context=number
 Output up to number lines of context after each matching line. Fewer
 lines are output if the next match or the end of the file is reached, or if the
@@ -196,19 +196,19 @@ 
    pcre2grep man page
    
 of lines, unless they are in fact contiguous in the input file. The value of
 number is expected to be relatively small. When -c is used,
 -A is ignored.
-
    
-
    
+
    
+
    
 -a, --text
 Treat binary files as text. This is equivalent to
 --binary-files=text.
-
    
-
    
+
    
+
    
 --allow-lookaround-bsk
 PCRE2 now forbids the use of \K in lookarounds by default, in line with Perl.
 This option causes pcre2grep to set the PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK
 option, which enables this somewhat dangerous usage.
-
    
-
    
+
    
+
    
 -B number, --before-context=number
 Output up to number lines of context before each matching line. Fewer
 lines are output if the previous match or the start of the file is within
@@ -219,8 +219,8 @@ 
    pcre2grep man page
    
 output between each group of lines, unless they are in fact contiguous in the
 input file. The value of number is expected to be relatively small. When
 -c is used, -B is ignored.
-
    
-
    
+
    
+
    
 --binary-files=word
 Specify how binary files are to be processed. If the word is "binary" (the
 default), pattern matching is performed on binary files, but the only output is
@@ -232,19 +232,19 @@ 
    pcre2grep man page
    
 -I option, binary files are not processed at all; they are assumed not to
 be of interest and are skipped without causing any output or affecting the
 return code.
-
    
-
    
+
    
+
    
 --buffer-size=number
 Set the parameter that controls how much memory is obtained at the start of
 processing for buffering files that are being scanned. See also
 --max-buffer-size below.
-
    
-
    
+
    
+
    
 -C number, --context=number
 Output number lines of context both before and after each matching line.
 This is equivalent to setting both -A and -B to the same value.
-
    
-
    
+
    
+
    
 -c, --count
 Do not output lines from the files that are being scanned; instead output the
 number of lines that would have been shown, either because they matched, or, if
@@ -260,14 +260,14 @@ 
    pcre2grep man page
    
 --files-with-matches option is also used, only those files whose counts
 are greater than zero are listed. When -c is used, the -A,
 -B, and -C options are ignored.
-
    
-
    
+
    
+
    
 --colour, --color
 If this option is given without any data, it is equivalent to "--colour=auto".
 If data is required, it must be given in the same shell item, separated by an
 equals sign.
-
    
-
    
+
    
+
    
 --colour=value, --color=value
 This option specifies under what circumstances the parts of a line that matched
 a pattern should be coloured in the output. It is ignored if
@@ -297,14 +297,14 @@ 
    pcre2grep man page
    
 colour on a terminal, so it is your responsibility to ensure that the values
 make sense. If no relevant environment variable is set, the default is "1;31",
 which gives red.
-
    
-
    
+
    
+
    
 -D action, --devices=action
 If an input path is not a regular file or a directory, "action" specifies how
 it is to be processed. Valid values are "read" (the default) or "skip"
 (silently skip the path).
-
    
-
    
+
    
+
    
 -d action, --directories=action
 If an input path is a directory, "action" specifies how it is to be processed.
 Valid values are "read" (the default in non-Windows environments, for
@@ -313,20 +313,20 @@ 
    pcre2grep man page
    
 "read" case, directories are read as if they were ordinary files. In some
 operating systems the effect of reading a directory like this is an immediate
 end-of-file; in others it may provoke an error.
-
    
-
    
+
    
+
    
 --depth-limit=number
 See --match-limit below.
-
    
-
    
+
    
+
    
 -E, --case-restrict
 When case distinctions are being ignored in Unicode mode, two ASCII letters (K
 and S) will by default match Unicode characters U+212A (Kelvin sign) and U+017F
 (long S) respectively, as well as their lower case ASCII counterparts. When
 this option is set, case equivalences are restricted such that no ASCII
 character matches a non-ASCII character, and vice versa.
-
    
-
    
+
    
+
    
 -e pattern, --regex=pattern, --regexp=pattern
 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
@@ -339,8 +339,8 @@ 
    pcre2grep man page
    
 If -f is used with -e, the command line patterns are matched first,
 followed by the patterns from the file(s), independent of the order in which
 these options are specified.
-
    
-
    
+
    
+
    
 --exclude=pattern
 Files (but not directories) whose names match the pattern are skipped without
 being processed. This applies to all files, whether listed on the command line,
@@ -351,16 +351,16 @@ 
    pcre2grep man page
    
 to specify multiple patterns. If a file name matches both an --include
 and an --exclude pattern, it is excluded. There is no short form for this
 option.
-
    
-
    
+
    
+
    
 --exclude-from=filename
 Treat each non-empty line of the file as the data for an --exclude
 option. What constitutes a newline when reading the file is the operating
 system's default. The --newline option has no effect on this option. This
 option may be given more than once in order to specify a number of files to
 read.
-
    
-
    
+
    
+
    
 --exclude-dir=pattern
 Directories whose names match the pattern are skipped without being processed,
 whatever the setting of the --recursive option. This applies to all
@@ -372,8 +372,8 @@ 
    pcre2grep man page
    
 specify more than one pattern. If a directory matches both --include-dir
 and --exclude-dir, it is excluded. There is no short form for this
 option.
-
    
-
    
+
    
+
    
 -F, --fixed-strings
 Interpret each data-matching pattern as a list of fixed strings, separated by
 newlines, instead of as a regular expression. What constitutes a newline for
@@ -384,8 +384,8 @@ 
    pcre2grep man page
    
 option applies only to the patterns that are matched against the contents of
 files; it does not apply to patterns specified by any of the --include or
 --exclude options.
-
    
-
    
+
    
+
    
 -f filename, --file=filename
 Read patterns from the file, one per line. As is the case with patterns on the
 command line, no delimiters should be used. What constitutes a newline when
@@ -403,8 +403,8 @@ 
    pcre2grep man page
    
 specified on the command line using -e may also be present; they are
 matched before the file's patterns. However, no pattern is taken from the
 command line; all arguments are treated as the names of paths to be searched.
-
    
-
    
+
    
+
    
 --file-list=filename
 Read a list of files and/or directories that are to be scanned from the given
 file, one per line. What constitutes a newline when reading the file is the
@@ -416,8 +416,8 @@ 
    pcre2grep man page
    
 terminal, from which further lines (the list of files) can be read after an
 end-of-file indication. If this option is given more than once, all the
 specified files are read.
-
    
-
    
+
    
+
    
 --file-offsets
 Instead of showing lines or parts of lines that match, show each match as an
 offset from the start of the file and a length, separated by a comma. In this
@@ -425,13 +425,13 @@ 
    pcre2grep man page
    
 -A, -B, and -C options are ignored. If there is more than one
 match in a line, each of them is shown separately. This option is mutually
 exclusive with --output, --line-offsets, and --only-matching.
-
    
-
    
+
    
+
    
 --group-separator=text
 Output this text string instead of two hyphens between groups of lines when
 -A, -B, or -C is in use. See also --no-group-separator.
-
    
-
    
+
    
+
    
 -H, --with-filename
 Force the inclusion of the file name at the start of output lines when
 searching a single file. The file name is not normally shown in this case.
@@ -441,8 +441,8 @@ 
    pcre2grep man page
    
 it follows the file name. When the -M option causes a pattern to match
 more than one line, only the first is preceded by the file name. This option
 overrides any previous -h, -l, or -L options.
-
    
-
    
+
    
+
    
 -h, --no-filename
 Suppress the output file names when searching multiple files. File names are
 normally shown when multiple files are searched. By default, for matching
@@ -450,29 +450,29 @@ 
    pcre2grep man page
    
 separator is used. The -Z option can be used to change the terminator to
 a zero byte. If a line number is also being output, it follows the file name.
 This option overrides any previous -H, -L, or -l options.
-
    
-
    
+
    
+
    
 --heap-limit=number
 See --match-limit below.
-
    
-
    
+
    
+
    
 --help
 Output a help message, giving brief details of the command options and file
 type support, and then exit. Anything else on the command line is
 ignored.
-
    
-
    
+
    
+
    
 -I
 Ignore binary files. This is equivalent to
 --binary-files=without-match.
-
    
-
    
+
    
+
    
 -i, --ignore-case
 Ignore upper/lower case distinctions when pattern matching. This applies when
 matching path names for inclusion or exclusion as well as when matching lines
 in files.
-
    
-
    
+
    
+
    
 --include=pattern
 If any --include patterns are specified, the only files that are
 processed are those whose names match one of the patterns and do not match an
@@ -484,15 +484,15 @@ 
    pcre2grep man page
    
 this pattern. The option may be given any number of times. If a file name
 matches both an --include and an --exclude pattern, it is excluded.
 There is no short form for this option.
-
    
-
    
+
    
+
    
 --include-from=filename
 Treat each non-empty line of the file as the data for an --include
 option. What constitutes a newline for this purpose is the operating system's
 default. The --newline option has no effect on this option. This option
 may be given any number of times; all the files are read.
-
    
-
    
+
    
+
    
 --include-dir=pattern
 If any --include-dir patterns are specified, the only directories that
 are processed are those whose names match one of the patterns and do not match
@@ -503,16 +503,16 @@ 
    pcre2grep man page
    
 -w, and -x options do not apply to this pattern. The option may be
 given any number of times. If a directory matches both --include-dir and
 --exclude-dir, it is excluded. There is no short form for this option.
-
    
-
    
+
    
+
    
 -L, --files-without-match
 Instead of outputting lines from the files, just output the names of the files
 that do not contain any lines that would have been output. Each file name is
 output once, on a separate line by default, but if the -Z option is set,
 they are separated by zero bytes instead of newlines. This option overrides any
 previous -H, -h, or -l options.
-
    
-
    
+
    
+
    
 -l, --files-with-matches
 Instead of outputting lines from the files, just output the names of the files
 containing lines that would have been output. Each file name is output once, on
@@ -524,14 +524,14 @@ 
    pcre2grep man page
    
 with -c is a way of suppressing the listing of files with no matches that
 occurs with -c on its own. This option overrides any previous -H,
 -h, or -L options.
-
    
-
    
+
    
+
    
 --label=name
 This option supplies a name to be used for the standard input when file names
 are being output. If not supplied, "(standard input)" is used. There is no
 short form for this option.
-
    
-
    
+
    
+
    
 --line-buffered
 When this option is given, non-compressed input is read and processed line by
 line, and the output is flushed after each write. By default, input is read in
@@ -543,8 +543,8 @@ 
    pcre2grep man page
    
 However, its use will affect performance, and the -M (multiline) option
 ceases to work. When input is from a compressed .gz or .bz2 file,
 --line-buffered is ignored.
-
    
-
    
+
    
+
    
 --line-offsets
 Instead of showing lines or parts of lines that match, show each match as a
 line number, the offset from the start of the line, and a length. The line
@@ -554,15 +554,15 @@ 
    pcre2grep man page
    
 options are ignored. If there is more than one match in a line, each of them is
 shown separately. This option is mutually exclusive with --output,
 --file-offsets, and --only-matching.
-
    
-
    
+
    
+
    
 --locale=locale-name
 This option specifies a locale to be used for pattern matching. It overrides
 the value in the LC_ALL or LC_CTYPE environment variables. If no
 locale is specified, the PCRE2 library's default (usually the "C" locale) is
 used. There is no short form for this option.
-
    
-
    
+
    
+
    
 -M, --multiline
 Allow patterns to match more than one line. When this option is set, the PCRE2
 library is called in "multiline" mode, and a match is allowed to continue past
@@ -604,8 +604,8 @@ 
    pcre2grep man page
    
 
    
 The -M option does not work when input is read line by line (see
 --line-buffered.)
-
    
-
    
+
    
+
    
 -m number, --max-count=number
 Stop processing after finding number matching lines, or non-matching
 lines if -v is also set. Any trailing context lines are output after the
@@ -615,8 +615,8 @@ 
    pcre2grep man page
    
 If -c is also set, the count that is output is never greater than
 number. This option has no effect if used with -L, -l, or
 -q, or when just checking for a match in a binary file.
-
    
-
    
+
    
+
    
 --match-limit=number
 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
@@ -646,14 +646,14 @@ 
    pcre2grep man page
    
 There are no short forms for these options. The default limits can be set
 when the PCRE2 library is compiled; if they are not specified, the defaults
 are very large and so effectively unlimited.
-
    
-
    
+
    
+
    
 --max-buffer-size=number
 This limits the expansion of the processing buffer, whose initial size can be
 set by --buffer-size. The maximum buffer size is silently forced to be no
 smaller than the starting buffer size.
-
    
-
    
+
    
+
    
 -N newline-type, --newline=newline-type
 Six different conventions for indicating the ends of lines in scanned files are
 supported. For example:
@@ -683,30 +683,30 @@ 
    pcre2grep man page
    
 not apply to files specified by the -f, --exclude-from, or
 --include-from options, which are expected to use the operating system's
 standard newline sequence.
-
    
-
    
+
    
+
    
 -n, --line-number
 Precede each output line by its line number in the file, followed by a colon
 for matching lines or a hyphen for context lines. If the file name is also
 being output, it precedes the line number. When the -M option causes a
 pattern to match more than one line, only the first is preceded by its line
 number. This option is forced if --line-offsets is used.
-
    
-
    
+
    
+
    
 --no-group-separator
 Do not output a separator between groups of lines when -A, -B, or
 -C is in use. The default is to output a line containing two hyphens. See
 also --group-separator.
-
    
-
    
+
    
+
    
 --no-jit
 If the PCRE2 library is built with support for just-in-time compiling (which
 speeds up matching), pcre2grep automatically makes use of this, unless it
 was explicitly disabled at build time. This option can be used to disable the
 use of JIT at run time. It is provided for testing and working around problems.
 It should never be needed in normal use.
-
    
-
    
+
    
+
    
 -O text, --output=text
 When there is a match, instead of outputting the line that matched, output just
 the text specified in this option, followed by an operating-system standard
@@ -747,8 +747,8 @@ 
    pcre2grep man page
    
 
    
 Any other character is substituted by itself. In particular, $$ is replaced by
 a single dollar.
-
    
-
    
+
    
+
    
 -o, --only-matching
 Show only the part of the line that matched a pattern instead of the whole
 line. In this mode, no context is shown. That is, the -A, -B, and
@@ -760,8 +760,8 @@ 
    pcre2grep man page
    
 name or line number are being printed, in which case they are shown on an
 otherwise empty line. This option is mutually exclusive with --output,
 --file-offsets and --line-offsets.
-
    
-
    
+
    
+
    
 -onumber, --only-matching=number
 Show only the part of the line that matched the capturing parentheses of the
 given number. Up to 50 capturing parentheses are supported by default. This
@@ -785,18 +785,18 @@ 
    pcre2grep man page
    
 -o3 -o1 -o3 causes the substrings matched by capturing parentheses 3 and 1 and
 then 3 again to be output. By default, there is no separator (but see the next
 but one option).
-
    
-
    
+
    
+
    
 --om-capture=number
 Set the number of capturing parentheses that can be accessed by -o. The
 default is 50.
-
    
-
    
+
    
+
    
 --om-separator=text
 Specify a separating string for multiple occurrences of -o. The default
 is an empty string. Separating strings are never coloured.
-
    
-
    
+
    
+
    
 -P, --no-ucp
 Starting from release 10.43, when UTF/Unicode mode is specified with -u
 or -U, the PCRE2_UCP option is used by default. This means that the
@@ -807,8 +807,8 @@ 
    pcre2grep man page
    
 option settings within patterns that affect individual classes. For example,
 when in UCP mode, the sequence (?aP) restricts [:word:] to ASCII letters, while
 allowing \w to match Unicode letters and digits.
-
    
-
    
+
    
+
    
 --posix-pattern-file
 When patterns are provided with the -f option, do not trim trailing
 spaces or ignore empty lines in a similar way than other grep tools. To keep
@@ -816,32 +816,32 @@ 
    pcre2grep man page
    
 terminated with CRLF (as character literals) then both characters won't be
 included as part of it, so if you really need to have pattern ending in '\r',
 use a escape sequence or provide it by a different method.
-
    
-
    
+
    
+
    
 -q, --quiet
 Work quietly, that is, display nothing except error messages. The exit
 status indicates whether or not any matches were found.
-
    
-
    
+
    
+
    
 -r, --recursive
 If any given path is a directory, recursively scan the files it contains,
 taking note of any --include and --exclude settings. By default, a
 directory is read as a normal file; in some operating systems this gives an
 immediate end-of-file. This option is a shorthand for setting the -d
 option to "recurse".
-
    
-
    
+
    
+
    
 --recursion-limit=number
 This is an obsolete synonym for --depth-limit. See --match-limit
 above for details.
-
    
-
    
+
    
+
    
 -s, --no-messages
 Suppress error messages about non-existent or unreadable files. Such files are
 quietly skipped. However, the return code is still 2, even if matches were
 found in other files.
-
    
-
    
+
    
+
    
 -t, --total-count
 This option is useful when scanning more than one file. If used on its own,
 -t suppresses all output except for a grand total number of matching
@@ -852,16 +852,16 @@ 
    pcre2grep man page
    
 "TOTAL:". Otherwise, it appears as just another number. The -t option is
 ignored when used with -L (list files without matches), because the grand
 total would always be zero.
-
    
-
    
+
    
+
    
 -u, --utf
 Operate in UTF/Unicode mode. This option is available only if PCRE2 has been
 compiled with UTF-8 support. All patterns (including those for any
 --exclude and --include options) and all lines that are scanned
 must be valid strings of UTF-8 characters. If an invalid UTF-8 string is
 encountered, an error occurs.
-
    
-
    
+
    
+
    
 -U, --utf-allow-invalid
 As --utf, but in addition subject lines may contain invalid UTF-8 code
 unit sequences. These can never form part of any pattern match. Patterns
@@ -871,21 +871,21 @@ 
    pcre2grep man page
    
 strings, see the
 pcre2unicode(3)
 documentation.
-
    
-
    
+
    
+
    
 -V, --version
 Write the version numbers of pcre2grep and the PCRE2 library to the
 standard output and then exit. Anything else on the command line is
 ignored.
-
    
-
    
+
    
+
    
 -v, --invert-match
 Invert the sense of the match, so that lines which do not match any of
 the patterns are the ones that are found. When this option is set, options such
 as --only-matching and --output, which specify parts of a match
 that are to be output, are ignored.
-
    
-
    
+
    
+
    
 -w, --word-regex, --word-regexp
 Force the patterns only to match "words". That is, there must be a word
 boundary at the start and end of each matched string. This is equivalent to
@@ -893,8 +893,8 @@ 
    pcre2grep man page
    
 option applies only to the patterns that are matched against the contents of
 files; it does not apply to patterns specified by any of the --include or
 --exclude options.
-
    
-
    
+
    
+
    
 -x, --line-regex, --line-regexp
 Force the patterns to start matching only at the beginnings of lines, and in
 addition, require them to match entire lines. In multiline mode the match may
@@ -902,38 +902,38 @@ 
    pcre2grep man page
    
 pattern and ")$" at the end. This option applies only to the patterns that are
 matched against the contents of files; it does not apply to patterns specified
 by any of the --include or --exclude options.
-
    
-
    
+
    
+
    
 -Z, --null
 Terminate files names in the regular output with a zero byte (the NUL
 character) instead of what would normally appear. This is useful when file
 names contain unusual characters such as colons, hyphens, or even newlines. The
 option does not apply to file names in error messages.
-
    
+
    
 
    ENVIRONMENT VARIABLES
    
-
    
+
    
 The environment variables LC_ALL and LC_CTYPE are examined, in that
 order, for a locale. The first one that is set is used. This can be overridden
 by the --locale option. If no locale is set, the PCRE2 library's default
 (usually the "C" locale) is used.
-
    
+
    
 
    NEWLINES
    
-
    
+
    
 The -N (--newline) option allows pcre2grep to scan files with
 newline conventions that differ from the default. This option affects only the
 way scanned files are processed. It does not affect the interpretation of files
 specified by the -f, --file-list, --exclude-from, or
 --include-from options.
-
    
-
    
+
    
+
    
 Any parts of the scanned input files that are written to the standard output
 are copied with whatever newline sequences they have in the input. However, if
 the final line of a file is output, and it does not end with a newline
 sequence, a newline sequence is added. If the newline setting is CR, LF, CRLF
 or NUL, that line ending is output; for the other settings (ANYCRLF or ANY) a
 single NL is used.
-
    
-
    
+
    
+
    
 The newline setting does not affect the way in which pcre2grep writes
 newlines in informational messages to the standard output and error streams.
 Under Windows, the standard output is set to be binary, so that "\r\n" at the
@@ -941,9 +941,9 @@ 
    pcre2grep man page
    
 "\r\r\n" by the C I/O library. This means that any messages written to the
 standard output must end with "\r\n". For all other operating systems, and
 for all messages to the standard error stream, "\n" is used.
-
    
+
    
 
    OPTIONS COMPATIBILITY WITH GNU GREP
    
-
    
+
    
 Many of the short and long forms of pcre2grep's options are the same as
 in the GNU grep program. Any long option of the form --xxx-regexp
 (GNU terminology) is also available as --xxx-regex (PCRE2 terminology).
@@ -955,17 +955,17 @@ 
    pcre2grep man page
    
 -U, and --utf-allow-invalid options are specific to
 pcre2grep, as is the use of the --only-matching option with a
 capturing parentheses number.
-
    
-
    
+
    
+
    
 Although most of the common options work the same way, a few are different in
 pcre2grep. For example, the --include option's argument is a glob
 for GNU grep, but in pcre2grep it is a regular expression to which
 the -i option applies. If both the -c and -l options are
 given, GNU grep lists only file names, without counts, but pcre2grep
 gives the counts as well.
-
    
+
    
 
    OPTIONS WITH DATA
    
-
    
+
    
 There are four different ways in which an option with data can be specified.
 If a short form option is used, the data may follow immediately, or (with one
 exception) in the next command line item. For example:
@@ -976,8 +976,8 @@ 
    pcre2grep man page
    
 The exception is the -o option, which may appear with or without data.
 Because of this, if data is present, it must follow immediately in the same
 item, for example -o3.
-
    
-
    
+
    
+
    
 If a long form option is used, the data may appear in the same command line
 item, separated by an equals character, or (with two exceptions) it may appear
 in the next command line item. For example:
@@ -989,15 +989,15 @@ 
    pcre2grep man page
    
 in a shell command, and have the shell expand ~ to a home directory, you must
 separate the file name from the option, because the shell does not treat ~
 specially unless it is at the start of an item.
-
    
-
    
+
    
+
    
 The exceptions to the above are the --colour (or --color) and
 --only-matching options, for which the data is optional. If one of these
 options does have data, it must be given in the first form, using an equals
 character. Otherwise pcre2grep will assume that it has no data.
-
    
+
    
 
    USING PCRE2'S CALLOUT FACILITY
    
-
    
+
    
 pcre2grep has, by default, support for calling external programs or
 scripts or echoing specific strings during matching by making use of PCRE2's
 callout facility. However, this support can be completely or partially disabled
@@ -1006,18 +1006,18 @@ 
    pcre2grep man page
    
 completely disabled, callouts in patterns are forbidden by pcre2grep.
 If the facility is partially disabled, calling external programs is not
 supported, and callouts that request it are ignored.
-
    
-
    
+
    
+
    
 A callout in a PCRE2 pattern is of the form (?C<arg>) where the argument is
 either a number or a quoted string (see the
 pcre2callout
 documentation for details). Numbered callouts are ignored by pcre2grep;
 only callouts with string arguments are useful.
-
    
+
    
 
    
 Echoing a specific string
 
    
-
    
+
    
 Starting the callout string with a pipe character invokes an echoing facility
 that avoids calling an external program or script. This facility is always
 available, provided that callouts were not completely disabled when
@@ -1037,17 +1037,17 @@ 
    pcre2grep man page
    
 Matching continues normally after the string is output. If you want to see only
 the callout output but not any output from an actual match, you should end the
 pattern with (*FAIL).
-
    
+
    
 
    
 Calling external programs or scripts
 
    
-
    
+
    
 This facility can be independently disabled when pcre2grep is built. It
 is supported for Windows, where a call to _spawnvp() is used, for VMS,
 where lib$spawn() is used, and for any Unix-like environment where
 fork() and execv() are available.
-
    
-
    
+
    
+
    
 If the callout string does not start with a pipe (vertical bar) character, it
 is parsed into a list of substrings separated by pipe characters. The first
 substring must be an executable name, with the following substrings specifying
@@ -1081,9 +1081,9 @@ 
    pcre2grep man page
    
 If running the program fails for any reason (including the non-existence of the
 executable), a local matching failure occurs and the matcher backtracks in the
 normal way.
-
    
+
    
 
    MATCHING ERRORS
    
-
    
+
    
 It is possible to supply a regular expression that takes a very long time to
 fail to match certain lines. Such patterns normally involve nested indefinite
 repeats, for example: (a+)*\d when matched against a line of a's with no final
@@ -1091,41 +1091,41 @@ 
    pcre2grep man page
    
 in these circumstances. If this happens, pcre2grep outputs an error
 message and the line that caused the problem to the standard error stream. If
 there are more than 20 such errors, pcre2grep gives up.
-
    
-
    
+
    
+
    
 The --match-limit option of pcre2grep can be used to set the
 overall resource limit. There are also other limits that affect the amount of
 memory used during matching; see the discussion of --heap-limit and
 --depth-limit above.
-
    
+
    
 
    DIAGNOSTICS
    
-
    
+
    
 Exit status is 0 if any matches were found, 1 if no matches were found, and 2
 for syntax errors, overlong lines, non-existent or inaccessible files (even if
 matches were found in other files) or too many matching errors. Using the
 -s option to suppress error messages about inaccessible files does not
 affect the return code.
-
    
-
    
+
    
+
    
 When run under VMS, the return code is placed in the symbol PCRE2GREP_RC
 because VMS does not distinguish between exit(0) and exit(1).
-
    
+
    
 
    SEE ALSO
    
-
    
+
    
 pcre2pattern(3), pcre2syntax(3), pcre2callout(3),
 pcre2unicode(3).
-
    
+
    
 
    AUTHOR
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    REVISION
    
-
    
+
    
 Last updated: 09 October 2024
 
    
 Copyright © 1997-2023 University of Cambridge.
diff --git a/doc/html/pcre2jit.html b/doc/html/pcre2jit.html
index 6835cd889..eb8896ea2 100644
--- a/doc/html/pcre2jit.html
+++ b/doc/html/pcre2jit.html
@@ -29,7 +29,7 @@ 
    pcre2jit man page
    
 
  • REVISION
 
 
    PCRE2 JUST-IN-TIME COMPILER SUPPORT
    
-
    
+
    
 Just-in-time compiling is a heavyweight optimization that can greatly speed up
 pattern matching. However, it comes at the cost of extra processing before the
 match is performed, so it is of most benefit when the same pattern is going to
@@ -39,14 +39,14 @@ 
    pcre2jit man page
    
 if the subject string is very long, it may still pay to use JIT even for
 one-off matches. JIT support is available for all of the 8-bit, 16-bit and
 32-bit PCRE2 libraries.
-
    
-
    
+
    
+
    
 JIT support applies only to the traditional Perl-compatible matching function.
 It does not apply when the DFA matching function is being used. The code for
 JIT support was written by Zoltan Herczeg.
-
    
+
    
 
    AVAILABILITY OF JIT SUPPORT
    
-
    
+
    
 JIT support is an optional feature of PCRE2. The "configure" option
 --enable-jit (or equivalent CMake option) must be set when PCRE2 is built if
 you want to use JIT. The support is limited to the following hardware
@@ -62,8 +62,8 @@ 
    pcre2jit man page
    
   RISC-V 32-bit and 64-bit
 
    • 
 If --enable-jit is set on an unsupported platform, compilation fails.
-
    
-
    
+
    
+
    
 A client program can tell if JIT support has been compiled by calling
 pcre2_config() with the PCRE2_CONFIG_JIT option. The result is one if
 PCRE2 was built with JIT support, and zero otherwise. However, having the JIT
@@ -75,48 +75,48 @@ 
    pcre2jit man page
    
 executable memory in which to build its compiled code. The only guarantee from
 pcre2_config() is that if it returns zero, JIT will definitely not
 be used.
-
    
-
    
+
    
+
    
 As of release 10.45 there is a more informative way to test for JIT support. If
 pcre2_compile_jit() is called with the single option PCRE2_JIT_TEST_ALLOC
 it returns zero if JIT is available and has a working allocator. Otherwise it
 returns PCRE2_ERROR_NOMEMORY if JIT is available but cannot allocate executable
 memory, or PCRE2_ERROR_JIT_UNSUPPORTED if JIT support is not compiled. The
 code argument is ignored, so it can be a NULL value.
-
    
-
    
+
    
+
    
 A simple program does not need to check availability in order to use JIT when
 possible. The API is implemented in a way that falls back to the interpretive
 code if JIT is not available or cannot be used for a given match. For programs
 that need the best possible performance, there is a
 "fast path"
 API that is JIT-specific.
-
    
+
    
 
    SIMPLE USE OF JIT
    
-
    
+
    
 To make use of the JIT support in the simplest way, all you have to do is to
 call pcre2_jit_compile() after successfully compiling a pattern with
 pcre2_compile(). This function has two arguments: the first is the
 compiled pattern pointer that was returned by pcre2_compile(), and the
 second is zero or more of the following option bits: PCRE2_JIT_COMPLETE,
 PCRE2_JIT_PARTIAL_HARD, or PCRE2_JIT_PARTIAL_SOFT.
-
    
-
    
+
    
+
    
 If JIT support is not available, a call to pcre2_jit_compile() does
 nothing and returns PCRE2_ERROR_JIT_BADOPTION. Otherwise, the compiled pattern
 is passed to the JIT compiler, which turns it into machine code that executes
 much faster than the normal interpretive code, but yields exactly the same
 results. The returned value from pcre2_jit_compile() is zero on success,
 or a negative error code.
-
    
-
    
+
    
+
    
 There is a limit to the size of pattern that JIT supports, imposed by the size
 of machine stack that it uses. The exact rules are not documented because they
 may change at any time, in particular, when new optimizations are introduced.
 If a pattern is too big, a call to pcre2_jit_compile() returns
 PCRE2_ERROR_NOMEMORY.
-
    
-
    
+
    
+
    
 PCRE2_JIT_COMPLETE requests the JIT compiler to generate code for complete
 matches. If you want to run partial matches using the PCRE2_PARTIAL_HARD or
 PCRE2_PARTIAL_SOFT options of pcre2_match(), you should set one or both
@@ -125,8 +125,8 @@ 
    pcre2jit man page
    
 (normal, soft partial, hard partial). When pcre2_match() is called, the
 appropriate code is run if it is available. Otherwise, the pattern is matched
 using interpretive code.
-
    
-
    
+
    
+
    
 You can call pcre2_jit_compile() multiple times for the same compiled
 pattern. It does nothing if it has previously compiled code for any of the
 option bits. For example, you can call it once with PCRE2_JIT_COMPLETE and
@@ -136,18 +136,18 @@ 
    pcre2jit man page
    
 pcre2_jit_compile() is called with no option bits set, it immediately
 returns zero. This is an alternative way of testing whether JIT support has
 been compiled.
-
    
-
    
+
    
+
    
 At present, it is not possible to free JIT compiled code except when the entire
 compiled pattern is freed by calling pcre2_code_free().
-
    
-
    
+
    
+
    
 In some circumstances you may need to call additional functions. These are
 described in the section entitled
 "Controlling the JIT stack"
 below.
-
    
-
    
+
    
+
    
 There are some pcre2_match() options that are not supported by JIT, and
 there are also some pattern items that JIT cannot handle. Details are given
 below.
@@ -160,8 +160,8 @@ 
    pcre2jit man page
    
 callback function is called whenever JIT code is about to be obeyed. If the
 match-time options are not right for JIT execution, the callback function is
 not obeyed.
-
    
-
    
+
    
+
    
 If the JIT compiler finds an unsupported item, no JIT data is generated. You
 can find out if JIT compilation was successful for a compiled pattern by
 calling pcre2_pattern_info() with the PCRE2_INFO_JITSIZE option. A
@@ -171,9 +171,9 @@ 
    pcre2jit man page
    
 pattern. Successful JIT compilation does not, however, guarantee the use of JIT
 at match time because there are some match time options that are not supported
 by JIT.
-
    
+
    
 
    MATCHING SUBJECTS CONTAINING INVALID UTF
    
-
    
+
    
 When a pattern is compiled with the PCRE2_UTF option, subject strings are
 normally expected to be a valid sequence of UTF code units. By default, this is
 checked at the start of matching and an error is generated if invalid UTF is
@@ -181,8 +181,8 @@ 
    pcre2jit man page
    
 skip the check (for improved performance) if you are sure that a subject string
 is valid. If this option is used with an invalid string, the result is
 undefined. The calling program may crash or loop or otherwise misbehave.
-
    
-
    
+
    
+
    
 However, a way of running matches on strings that may contain invalid UTF
 sequences is available. Calling pcre2_compile() with the
 PCRE2_MATCH_INVALID_UTF option has two effects: it tells the interpreter in
@@ -192,48 +192,48 @@ 
    pcre2jit man page
    
 is given in the
 pcre2unicode
 documentation.
-
    
-
    
+
    
+
    
 There is also an obsolete option for pcre2_jit_compile() called
 PCRE2_JIT_INVALID_UTF, which currently exists only for backward compatibility.
 It is superseded by the pcre2_compile() option PCRE2_MATCH_INVALID_UTF
 and should no longer be used. It may be removed in future.
-
    
+
    
 
    UNSUPPORTED OPTIONS AND PATTERN ITEMS
    
-
    
+
    
 The pcre2_match() options that are supported for JIT matching are
 PCRE2_COPY_MATCHED_SUBJECT, PCRE2_NOTBOL, PCRE2_NOTEOL, PCRE2_NOTEMPTY,
 PCRE2_NOTEMPTY_ATSTART, PCRE2_NO_UTF_CHECK, PCRE2_PARTIAL_HARD, and
 PCRE2_PARTIAL_SOFT. The PCRE2_ANCHORED and PCRE2_ENDANCHORED options are not
 supported at match time.
-
    
-
    
+
    
+
    
 If the PCRE2_NO_JIT option is passed to pcre2_match() it disables the
 use of JIT, forcing matching by the interpreter code.
-
    
-
    
+
    
+
    
 The only unsupported pattern items are \C (match a single data unit) when
 running in a UTF mode, and a callout immediately before an assertion condition
 in a conditional group.
-
    
+
    
 
    RETURN VALUES FROM JIT MATCHING
    
-
    
+
    
 When a pattern is matched using JIT, the return values are the same as those
 given by the interpretive pcre2_match() code, with the addition of one
 new error code: PCRE2_ERROR_JIT_STACKLIMIT. This means that the memory used for
 the JIT stack was insufficient. See
 "Controlling the JIT stack"
 below for a discussion of JIT stack usage.
-
    
-
    
+
    
+
    
 The error code PCRE2_ERROR_MATCHLIMIT is returned by the JIT code if searching
 a very large pattern tree goes on for too long, as it is in the same
 circumstance when JIT is not used, but the details of exactly what is counted
 are not the same. The PCRE2_ERROR_DEPTHLIMIT error code is never returned
 when JIT matching is used.
-
    
+
    
 
    CONTROLLING THE JIT STACK
    
-
    
+
    
 When the compiled JIT code runs, it needs a block of memory to use as a stack.
 By default, it uses 32KiB on the machine stack. However, some large or
 complicated patterns need more than this. The error PCRE2_ERROR_JIT_STACKLIMIT
@@ -242,8 +242,8 @@ 
    pcre2jit man page
    
 about the use of JIT stacks in the section entitled
 "JIT stack FAQ"
 below.
-
    
-
    
+
    
+
    
 The pcre2_jit_stack_create() function creates a JIT stack. Its arguments
 are a starting size, a maximum size, and a general context (for memory
 allocation functions, or NULL for standard memory allocation). It returns a
@@ -253,8 +253,8 @@ 
    pcre2jit man page
    
 immediately, without doing anything. (For the technically minded: the address
 space is allocated by mmap or VirtualAlloc.) A maximum stack size of 512KiB to
 1MiB should be more than enough for any pattern.
-
    
-
    
+
    
+
    
 The pcre2_jit_stack_assign() function specifies which stack JIT code
 should use. Its arguments are as follows:
 
    @@ -286,31 +286,31 @@ 
    pcre2jit man page
    
 obeyed when pcre2_match() is called with options that are incompatible
 for JIT matching. A callback function can therefore be used to determine
 whether a match operation was executed by JIT or by the interpreter.
-
    
-
    
+
    
+
    
 You may safely use the same JIT stack for more than one pattern (either by
 assigning directly or by callback), as long as the patterns are matched
 sequentially in the same thread. Currently, the only way to set up
 non-sequential matches in one thread is to use callouts: if a callout function
 starts another match, that match must use a different JIT stack to the one used
 for currently suspended match(es).
-
    
-
    
+
    
+
    
 In a multithread application, if you do not specify a JIT stack, or if you
 assign or pass back NULL from a callback, that is thread-safe, because each
 thread has its own machine stack. However, if you assign or pass back a
 non-NULL JIT stack, this must be a different stack for each thread so that the
 application is thread-safe.
-
    
-
    
+
    
+
    
 Strictly speaking, even more is allowed. You can assign the same non-NULL stack
 to a match context that is used by any number of patterns, as long as they are
 not used for matching by multiple threads at the same time. For example, you
 could use the same stack in all compiled patterns, with a global mutex in the
 callback to wait until the stack is available for use. However, this is an
 inefficient solution, and not recommended.
-
    
-
    
+
    
+
    
 This is a suggestion for how a multithreaded program that needs to set up
 non-default JIT stacks might operate:
 
    @@ -324,9 +324,9 @@ 
    pcre2jit man page
    
     return thread_local_var
 
    
 All the functions described in this section do nothing if JIT is not available.
-
    
+
    
 
    JIT STACK FAQ
    
-
    
+
    
 (1) Why do we need JIT stacks?
 
    
 
    
@@ -336,8 +336,8 @@ 
    pcre2jit man page
    
 stack chain needs to be updated every time if we extend the stack on PowerPC.
 Although it is possible, its updating time overhead decreases performance. So
 we do the recursion in memory.
-
    
-
    
+
    
+
    
 (2) Why don't we simply allocate blocks of memory with malloc()?
 
    
 
    
@@ -347,8 +347,8 @@ 
    pcre2jit man page
    
 important because of pointers). Thus we can allocate 1MiB address space, and
 use only a single memory page (usually 4KiB) if that is enough. However, we can
 still grow up to 1MiB anytime if needed.
-
    
-
    
+
    
+
    
 (3) Who "owns" a JIT stack?
 
    
 
    
@@ -359,8 +359,8 @@ 
    pcre2jit man page
    
 threads (to avoid overwriting the same memory area). The best practice for
 multithreaded programs is to allocate a stack for each thread, and return this
 stack through the JIT callback function.
-
    
-
    
+
    
+
    
 (4) When should a JIT stack be freed?
 
    
 
    
@@ -373,8 +373,8 @@ 
    pcre2jit man page
    
 currently used by pcre2_match() in another thread). You can also replace
 the stack in a context at any time when it is not in use. You should free the
 previous stack before assigning a replacement.
-
    
-
    
+
    
+
    
 (5) Should I allocate/free a stack every time before/after calling
 pcre2_match()?
 
    
@@ -383,8 +383,8 @@ 
    pcre2jit man page
    
 implement some clever idea which release the stack if it is not used in let's
 say two minutes. The JIT callback can help to achieve this without keeping a
 list of patterns.
-
    
-
    
+
    
+
    
 (6) OK, the stack is for long term memory allocation. But what happens if a
 pattern causes stack overflow with a stack of 1MiB? Is that 1MiB kept until the
 stack is freed?
@@ -395,29 +395,29 @@ 
    pcre2jit man page
    
 Probably a function call which returns with the currently allocated memory for
 any stack and another which allows releasing memory (shrinking the stack) would
 be a good idea if someone needs this.
-
    
-
    
+
    
+
    
 (7) This is too much of a headache. Isn't there any better solution for JIT
 stack handling?
 
    
 
    
 No, thanks to Windows. If POSIX threads were used everywhere, we could throw
 out this complicated API.
-
    
+
    
 
    FREEING JIT SPECULATIVE MEMORY
    
-
    
+
    
 void pcre2_jit_free_unused_memory(pcre2_general_context *gcontext);
-
    
-
    
+
    
+
    
 The JIT executable allocator does not free all memory when it is possible. It
 expects new allocations, and keeps some free memory around to improve
 allocation speed. However, in low memory conditions, it might be better to free
 all possible memory. You can cause this to happen by calling
 pcre2_jit_free_unused_memory(). Its argument is a general context, for custom
 memory management, or NULL for standard memory management.
-
    
+
    
 
    EXAMPLE CODE
    
-
    
+
    
 This is a single-threaded example that specifies a JIT stack without using a
 callback. A real program should include error checking after all the function
 calls.
@@ -443,10 +443,10 @@ 
    pcre2jit man page
    
   pcre2_match_context_free(mcontext);
   pcre2_jit_stack_free(jit_stack);
 
-
    
-
    
+
    • 
+
    
 
    JIT FAST PATH API
    
-
    
+
    
 Because the API described above falls back to interpreted matching when JIT is
 not available, it is convenient for programs that are written for general use
 in many environments. However, calling JIT via pcre2_match() does have a
@@ -455,8 +455,8 @@ 
    pcre2jit man page
    
 "fast path" API to call JIT matching directly instead of calling
 pcre2_match() (obviously only for patterns that have been successfully
 processed by pcre2_jit_compile()).
-
    
-
    
+
    
+
    
 The fast path function is called pcre2_jit_match(), and it takes exactly
 the same arguments as pcre2_match(). However, the subject string must be
 specified with a length; PCRE2_ZERO_TERMINATED is not supported. Unsupported
@@ -464,8 +464,8 @@ 
    pcre2jit man page
    
 is the PCRE2_NO_JIT option. The return values are also the same as for
 pcre2_match(), plus PCRE2_ERROR_JIT_BADOPTION if a matching mode (partial
 or complete) is requested that was not compiled.
-
    
-
    
+
    
+
    
 When you call pcre2_match(), as well as testing for invalid options, a
 number of other sanity checks are performed on the arguments. For example, if
 the subject pointer is NULL but the length is non-zero, an immediate error is
@@ -476,26 +476,26 @@ 
    pcre2jit man page
    
 or loop or give wrong results. In the absence of PCRE2_MATCH_INVALID_UTF you
 should call pcre2_jit_match() in UTF mode only if you are sure the
 subject is valid.
-
    
-
    
+
    
+
    
 Bypassing the sanity checks and the pcre2_match() wrapping can give
 speedups of more than 10%.
-
    
+
    
 
    SEE ALSO
    
-
    
+
    
 pcre2api(3), pcre2unicode(3)
-
    
+
    
 
    AUTHOR
    
-
    
+
    
 Philip Hazel (FAQ by Zoltan Herczeg)
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    REVISION
    
-
    
+
    
 Last updated: 22 August 2024
 
    
 Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/html/pcre2limits.html b/doc/html/pcre2limits.html
index 514c50b23..1b827262d 100644
--- a/doc/html/pcre2limits.html
+++ b/doc/html/pcre2limits.html
@@ -15,11 +15,11 @@ 
    pcre2limits man page
    
 
    
 SIZE AND OTHER LIMITATIONS
 
    
-
    
+
    
 There are some size limitations in PCRE2 but it is hoped that they will never
 in practice be relevant.
-
    
-
    
+
    
+
    
 The maximum size of a compiled pattern is approximately 64 thousand code units
 for the 8-bit and 16-bit libraries if PCRE2 is compiled with the default
 internal linkage size, which is 2 bytes for these libraries. If you want to
@@ -30,31 +30,31 @@ 
    pcre2limits man page
    
 documentation for details. In these cases the limit is substantially larger.
 However, the speed of execution is slower. In the 32-bit library, the internal
 linkage size is always 4.
-
    
-
    
+
    
+
    
 The maximum length of a source pattern string is essentially unlimited; it is
 the largest number a PCRE2_SIZE variable can hold. However, the program that
 calls pcre2_compile() can specify a smaller limit.
-
    
-
    
+
    
+
    
 The maximum length (in code units) of a subject string is one less than the
 largest number a PCRE2_SIZE variable can hold. PCRE2_SIZE is an unsigned
 integer type, usually defined as size_t. Its maximum value (that is
 ~(PCRE2_SIZE)0) is reserved as a special indicator for zero-terminated strings
 and unset offsets.
-
    
-
    
+
    
+
    
 All values in repeating quantifiers must be less than 65536.
-
    
-
    
+
    
+
    
 There are two different limits that apply to branches of lookbehind assertions.
 If every branch in such an assertion matches a fixed number of characters,
 the maximum length of any branch is 65535 characters. If any branch matches a
 variable number of characters, then the maximum matching length for every
 branch is limited. The default limit is set at compile time, defaulting to 255,
 but can be changed by the calling program.
-
    
-
    
+
    
+
    
 There is no limit to the number of parenthesized groups, but there can be no
 more than 65535 capture groups, and there is a limit to the depth of nesting of
 parenthesized subpatterns of all kinds. This is imposed in order to limit the
@@ -62,40 +62,40 @@ 
    pcre2limits man page
    
 when PCRE2 is built; if not, the default is set to 250. An application can
 change this limit by calling pcre2_set_parens_nest_limit() to set the limit in
 a compile context.
-
    
-
    
+
    
+
    
 The maximum length of name for a named capture group is 32 code units, and the
 maximum number of such groups is 10000.
-
    
-
    
+
    
+
    
 The maximum length of a name in a (*MARK), (*PRUNE), (*SKIP), or (*THEN) verb
 is 255 code units for the 8-bit library and 65535 code units for the 16-bit and
 32-bit libraries.
-
    
-
    
+
    
+
    
 The maximum length of a string argument to a callout is the largest number a
 32-bit unsigned integer can hold.
-
    
-
    
+
    
+
    
 The maximum amount of heap memory used for matching is controlled by the heap
 limit, which can be set in a pattern or in a match context. The default is a
 very large number, effectively unlimited.
-
    
+
    
 
    
 AUTHOR
 
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    
 REVISION
 
    
-
    
+
    
 Last updated: 16 August 2023
 
    
 Copyright © 1997-2023 University of Cambridge.
diff --git a/doc/html/pcre2matching.html b/doc/html/pcre2matching.html
index 4d0232507..276b1e299 100644
--- a/doc/html/pcre2matching.html
+++ b/doc/html/pcre2matching.html
@@ -23,7 +23,7 @@ 
    pcre2matching man page
    
 
  • REVISION
 
 
    PCRE2 MATCHING ALGORITHMS
    
-
    
+
    
 This document describes the two different algorithms that are available in
 PCRE2 for matching a compiled regular expression against a given subject
 string. The "standard" algorithm is the one provided by the pcre2_match()
@@ -32,14 +32,14 @@ 
    pcre2matching man page
    
 described in the
 pcre2jit
 documentation is compatible with this function.
-
    
-
    
+
    
+
    
 An alternative algorithm is provided by the pcre2_dfa_match() function;
 it operates in a different way, and is not Perl-compatible. This alternative
 has advantages and disadvantages compared with the standard algorithm, and
 these are described below.
-
    
-
    
+
    
+
    
 When there is only one possible way in which a given subject string can match a
 pattern, the two algorithms give the same answer. A difference arises, however,
 when there are multiple possibilities. For example, if the anchored pattern
@@ -52,18 +52,18 @@ 
    pcre2matching man page
    
 
    • 
 there are three possible answers. The standard algorithm finds only one of
 them, whereas the alternative algorithm finds all three.
-
    
+
    
 
    REGULAR EXPRESSIONS AS TREES
    
-
    
+
    
 The set of strings that are matched by a regular expression can be represented
 as a tree structure. An unlimited repetition in the pattern makes the tree of
 infinite size, but it is still a tree. Matching the pattern to a given subject
 string (from a given starting point) can be thought of as a search of the tree.
 There are two ways to search a tree: depth-first and breadth-first, and these
 correspond to the two matching algorithms provided by PCRE2.
-
    
+
    
 
    THE STANDARD MATCHING ALGORITHM
    
-
    
+
    
 In the terminology of Jeffrey Friedl's book "Mastering Regular Expressions",
 the standard algorithm is an "NFA algorithm". It conducts a depth-first search
 of the pattern tree. That is, it proceeds along a single path through the tree,
@@ -73,23 +73,23 @@ 
    pcre2matching man page
    
 alternative branch at that level. This often involves backing up (moving to the
 left) in the subject string as well. The order in which repetition branches are
 tried is controlled by the greedy or ungreedy nature of the quantifier.
-
    
-
    
+
    
+
    
 If a leaf node is reached, a matching string has been found, and at that point
 the algorithm stops. Thus, if there is more than one possible match, this
 algorithm returns the first one that it finds. Whether this is the shortest,
 the longest, or some intermediate length depends on the way the alternations
 and the greedy or ungreedy repetition quantifiers are specified in the
 pattern.
-
    
-
    
+
    
+
    
 Because it ends up with a single path through the tree, it is relatively
 straightforward for this algorithm to keep track of the substrings that are
 matched by portions of the pattern in parentheses. This provides support for
 capturing parentheses and backreferences.
-
    
+
    
 
    THE ALTERNATIVE MATCHING ALGORITHM
    
-
    
+
    
 This algorithm conducts a breadth-first search of the tree. Starting from the
 first matching point in the subject, it scans the subject string from left to
 right, once, character by character, and as it does this, it remembers all the
@@ -97,14 +97,14 @@ 
    pcre2matching man page
    
 this is a kind of "DFA algorithm", though it is not implemented as a
 traditional finite state machine (it keeps multiple states active
 simultaneously).
-
    
-
    
+
    
+
    
 Although the general principle of this matching algorithm is that it scans the
 subject string only once, without backtracking, there is one exception: when a
 lookaround assertion is encountered, the characters following or preceding the
 current point have to be independently inspected.
-
    
-
    
+
    
+
    
 The scan continues until either the end of the subject is reached, or there are
 no more unterminated paths. At this point, terminated paths represent the
 different matching possibilities (if there are none, the match has failed).
@@ -112,14 +112,14 @@ 
    pcre2matching man page
    
 them, and in particular, it finds the longest. The matches are returned in
 the output vector in decreasing order of length. There is an option to stop the
 algorithm after the first match (which is necessarily the shortest) is found.
-
    
-
    
+
    
+
    
 Note that the size of vector needed to contain all the results depends on the
 number of simultaneous matches, not on the number of capturing parentheses in
 the pattern. Using pcre2_match_data_create_from_pattern() to create the
 match data block is therefore not advisable when doing DFA matching.
-
    
-
    
+
    
+
    
 Note also that all the matches that are found start at the same point in the
 subject. If the pattern
 
    @@ -129,8 +129,8 @@ 
    pcre2matching man page
    
 three strings "caterpillar", "cater", and "cat" that start at the fifth
 character of the subject. The algorithm does not automatically move on to find
 matches that start at later positions.
-
    
-
    
+
    
+
    
 PCRE2's "auto-possessification" optimization usually applies to character
 repeats at the end of a pattern (as well as internally). For example, the
 pattern "a\d+" is compiled as if it were "a\d++" because there is no point
@@ -138,13 +138,13 @@ 
    pcre2matching man page
    
 DFA matching, this means that only one possible match is found. If you really
 do want multiple matches in such cases, either use an ungreedy repeat
 ("a\d+?") or set the PCRE2_NO_AUTO_POSSESS option when compiling.
-
    
-
    
+
    
+
    
 There are a number of features of PCRE2 regular expressions that are not
 supported or behave differently in the alternative matching function. Those
 that are not supported cause an error if encountered.
-
    
-
    
+
    
+
    
 1. Because the algorithm finds all possible matches, the greedy or ungreedy
 nature of repetition quantifiers is not relevant (though it may affect
 auto-possessification, as just described). During matching, greedy and ungreedy
@@ -158,14 +158,14 @@ 
    pcre2matching man page
    
 non-possessive quantifier. Similarly, if an atomic group is present, it is
 matched as if it were a standalone pattern at the current point, and the
 longest match is then "locked in" for the rest of the overall pattern.
-
    
-
    
+
    
+
    
 2. When dealing with multiple paths through the tree simultaneously, it is not
 straightforward to keep track of captured substrings for the different matching
 possibilities, and PCRE2's implementation of this algorithm does not attempt to
 do this. This means that no captured substrings are available.
-
    
-
    
+
    
+
    
 3. Because no substrings are captured, a number of related features are not
 available:
 
    
@@ -181,78 +181,78 @@ 
    pcre2matching man page
    
 
    
 
    
 (d) Scan substring assertions.
-
    
-
    
+
    
+
    
 4. Because many paths through the tree may be active, the \K escape sequence,
 which resets the start of the match when encountered (but may be on some paths
 and not on others), is not supported.
-
    
-
    
+
    
+
    
 5. Callouts are supported, but the value of the capture_top field is
 always 1, and the value of the capture_last field is always 0.
-
    
-
    
+
    
+
    
 6. The \C escape sequence, which (in the standard algorithm) always matches a
 single code unit, even in a UTF mode, is not supported in UTF modes because
 the alternative algorithm moves through the subject string one character (not
 code unit) at a time, for all active paths through the tree.
-
    
-
    
+
    
+
    
 7. Except for (*FAIL), the backtracking control verbs such as (*PRUNE) are not
 supported. (*FAIL) is supported, and behaves like a failing negative assertion.
-
    
-
    
+
    
+
    
 8. The PCRE2_MATCH_INVALID_UTF option for pcre2_compile() is not
 supported by pcre2_dfa_match().
-
    
+
    
 
    ADVANTAGES OF THE ALTERNATIVE ALGORITHM
    
-
    
+
    
 The main advantage of the alternative algorithm is that all possible matches
 (at a single point in the subject) are automatically found, and in particular,
 the longest match is found. To find more than one match at the same point using
 the standard algorithm, you have to do kludgy things with callouts.
-
    
-
    
+
    
+
    
 Partial matching is possible with this algorithm, though it has some
 limitations. The
 pcre2partial
 documentation gives details of partial matching and discusses multi-segment
 matching.
-
    
+
    
 
    DISADVANTAGES OF THE ALTERNATIVE ALGORITHM
    
-
    
+
    
 The alternative algorithm suffers from a number of disadvantages:
-
    
-
    
+
    
+
    
 1. It is substantially slower than the standard algorithm. This is partly
 because it has to search for all possible matches, but is also because it is
 less susceptible to optimization.
-
    
-
    
+
    
+
    
 2. Capturing parentheses and other features such as backreferences that rely on
 them are not supported.
-
    
-
    
+
    
+
    
 3. Matching within invalid UTF strings is not supported.
-
    
-
    
+
    
+
    
 4. Although atomic groups are supported, their use does not provide the
 performance advantage that it does for the standard algorithm.
-
    
-
    
+
    
+
    
 5. JIT optimization is not supported.
-
    
+
    
 
    AUTHOR
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    REVISION
    
-
    
+
    
 Last updated: 30 August 2024
 
    
 Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/html/pcre2partial.html b/doc/html/pcre2partial.html
index 067064d90..0c7354e6f 100644
--- a/doc/html/pcre2partial.html
+++ b/doc/html/pcre2partial.html
@@ -23,32 +23,32 @@ 
    pcre2partial man page
    
 
  • REVISION
 
 
    PARTIAL MATCHING IN PCRE2
    
-
    
+
    
 In normal use of PCRE2, if there is a match up to the end of a subject string,
 but more characters are needed to match the entire pattern, PCRE2_ERROR_NOMATCH
 is returned, just like any other failing match. There are circumstances where
 it might be helpful to distinguish this "partial match" case.
-
    
-
    
+
    
+
    
 One example is an application where the subject string is very long, and not
 all available at once. The requirement here is to be able to do the matching
 segment by segment, but special action is needed when a matched substring spans
 the boundary between two segments.
-
    
-
    
+
    
+
    
 Another example is checking a user input string as it is typed, to ensure that
 it conforms to a required format. Invalid characters can be immediately
 diagnosed and rejected, giving instant feedback.
-
    
-
    
+
    
+
    
 Partial matching is a PCRE2-specific feature; it is not Perl-compatible. It is
 requested by setting one of the PCRE2_PARTIAL_HARD or PCRE2_PARTIAL_SOFT
 options when calling a matching function. The difference between the two
 options is whether or not a partial match is preferred to an alternative
 complete match, though the details differ between the two types of matching
 function. If both options are set, PCRE2_PARTIAL_HARD takes precedence.
-
    
-
    
+
    
+
    
 If you want to use partial matching with just-in-time optimized code, as well
 as setting a partial match option for the matching function, you must also call
 pcre2_jit_compile() with one or both of these options:
@@ -59,8 +59,8 @@ 
    pcre2partial man page
    
 PCRE2_JIT_COMPLETE should also be set if you are going to run non-partial
 matches on the same pattern. Separate code is compiled for each mode. If the
 appropriate JIT mode has not been compiled, interpretive matching code is used.
-
    
-
    
+
    
+
    
 Setting a partial matching option disables two of PCRE2's standard
 optimization hints. PCRE2 remembers the last literal code unit in a pattern,
 and abandons matching immediately if it is not present in the subject string.
@@ -68,43 +68,43 @@ 
    pcre2partial man page
    
 partially. PCRE2 also remembers a minimum length of a matching string, and does
 not bother to run the matching function on shorter strings. This optimization
 is also disabled for partial matching.
-
    
+
    
 
    REQUIREMENTS FOR A PARTIAL MATCH
    
-
    
+
    
 A possible partial match occurs during matching when the end of the subject
 string is reached successfully, but either more characters are needed to
 complete the match, or the addition of more characters might change what is
 matched.
-
    
-
    
+
    
+
    
 Example 1: if the pattern is /abc/ and the subject is "ab", more characters are
 definitely needed to complete a match. In this case both hard and soft matching
 options yield a partial match.
-
    
-
    
+
    
+
    
 Example 2: if the pattern is /ab+/ and the subject is "ab", a complete match
 can be found, but the addition of more characters might change what is
 matched. In this case, only PCRE2_PARTIAL_HARD returns a partial match;
 PCRE2_PARTIAL_SOFT returns the complete match.
-
    
-
    
+
    
+
    
 On reaching the end of the subject, when PCRE2_PARTIAL_HARD is set, if the next
 pattern item is \z, \Z, \b, \B, or $ there is always a partial match.
 Otherwise, for both options, the next pattern item must be one that inspects a
 character, and at least one of the following must be true:
-
    
-
    
+
    
+
    
 (1) At least one character has already been inspected. An inspected character
 need not form part of the final matched string; lookbehind assertions and the
 \K escape sequence provide ways of inspecting characters before the start of a
 matched string.
-
    
-
    
+
    
+
    
 (2) The pattern contains one or more lookbehind assertions. This condition
 exists in case there is a lookbehind that inspects characters before the start
 of the match.
-
    
-
    
+
    
+
    
 (3) There is a special case when the whole pattern can match an empty string.
 When the starting point is at the end of the subject, the empty string match is
 a possibility, and if PCRE2_PARTIAL_SOFT is set and neither of the above
@@ -113,26 +113,26 @@ 
    pcre2partial man page
    
 which in this case means "there is going to be a match at this point, but until
 some more characters are added, we do not know if it will be an empty string or
 something longer".
-
    
+
    
 
    PARTIAL MATCHING USING pcre2_match()
    
-
    
+
    
 When a partial matching option is set, the result of calling
 pcre2_match() can be one of the following:
-
    
-
    
+
    
+
    
 A successful match
 A complete match has been found, starting and ending within this subject.
-
    
-
    
+
    
+
    
 PCRE2_ERROR_NOMATCH
 No match can start anywhere in this subject.
-
    
-
    
+
    
+
    
 PCRE2_ERROR_PARTIAL
 Adding more characters may result in a complete match that uses one or more
 characters from the end of this subject.
-
    
-
    
+
    
+
    
 When a partial match is returned, the first two elements in the ovector point
 to the portion of the subject that was matched, but the values in the rest of
 the ovector are undefined. The appearance of \K in the pattern has no effect
@@ -146,8 +146,8 @@ 
    pcre2partial man page
    
 is "456abc12", a partial match is found for the string "abc12", because all
 these characters are needed for a subsequent re-match with additional
 characters.
-
    
-
    
+
    
+
    
 If there is more than one partial match, the first one that was found provides
 the data that is returned. Consider this pattern:
 
    @@ -158,23 +158,23 @@ 
    pcre2partial man page
    
 PCRE2_ERROR_PARTIAL is returned. The offsets are set to 3 and 9, identifying
 "123dog" as the first partial match. (In this example, there are two partial
 matches, because "dog" on its own partially matches the second alternative.)
-
    
+
    
 
    
 How a partial match is processed by pcre2_match()
 
    
-
    
+
    
 What happens when a partial match is identified depends on which of the two
 partial matching options is set.
-
    
-
    
+
    
+
    
 If PCRE2_PARTIAL_HARD is set, PCRE2_ERROR_PARTIAL is returned as soon as a
 partial match is found, without continuing to search for possible complete
 matches. This option is "hard" because it prefers an earlier partial match over
 a later complete match. For this reason, the assumption is made that the end of
 the supplied subject string is not the true end of the available data, which is
 why \z, \Z, \b, \B, and $ always give a partial match.
-
    
-
    
+
    
+
    
 If PCRE2_PARTIAL_SOFT is set, the partial match is remembered, but matching
 continues as normal, and other alternatives in the pattern are tried. If no
 complete match can be found, PCRE2_ERROR_PARTIAL is returned instead of
@@ -183,8 +183,8 @@ 
    pcre2partial man page
    
 the subject string is potentially complete; \z, \Z, and $ match at the end of
 the subject, as normal, and for \b and \B the end of the subject is treated
 as a non-alphanumeric.
-
    
-
    
+
    
+
    
 The difference between the two partial matching options can be illustrated by a
 pattern such as:
 
    @@ -207,11 +207,11 @@ 
    pcre2partial man page
    
 
    
 The second pattern will never match "dogsbody", because it will always find the
 shorter match first.
-
    
+
    
 
    
 Example of partial matching using pcre2test
 
    
-
    
+
    
 The pcre2test data modifiers partial_hard (or ph) and
 partial_soft (or ps) set PCRE2_PARTIAL_HARD and PCRE2_PARTIAL_SOFT,
 respectively, when calling pcre2_match(). Here is a run of
@@ -239,9 +239,9 @@ 
    pcre2partial man page
    
 With PCRE2_PARTIAL_SOFT, the subject is matched completely. For
 PCRE2_PARTIAL_HARD, however, the subject is assumed not to be complete, so
 there is only a partial match.
-
    
+
    
 
    MULTI-SEGMENT MATCHING WITH pcre2_match()
    
-
    
+
    
 PCRE was not originally designed with multi-segment matching in mind. However,
 over time, features (including partial matching) that make multi-segment
 matching possible have been added. A very long string can be searched segment
@@ -250,15 +250,15 @@ 
    pcre2partial man page
    
 searching all the time. Normally, the strings that are being sought are much
 shorter than each individual segment, and are in the middle of very long
 strings, so the pattern is normally not anchored.
-
    
-
    
+
    
+
    
 Special logic must be implemented to handle a matched substring that spans a
 segment boundary. PCRE2_PARTIAL_HARD should be used, because it returns a
 partial match at the end of a segment whenever there is the possibility of
 changing the match by adding more characters. The PCRE2_NOTBOL option should
 also be set for all but the first segment.
-
    
-
    
+
    
+
    
 When a partial match occurs, the next segment must be added to the current
 subject and the match re-run, using the startoffset argument of
 pcre2_match() to begin at the point where the partial match started.
@@ -279,8 +279,8 @@ 
    pcre2partial man page
    
 second half is moved to the start of the buffer, and a new segment is added
 before repeating the match as in the example above. After a no match, the
 entire buffer can be discarded.
-
    
-
    
+
    
+
    
 If there are memory constraints, you may want to discard text that precedes a
 partial match before adding the next segment. Unfortunately, this is not at
 present straightforward. In cases such as the above, where the pattern does not
@@ -301,8 +301,8 @@ 
    pcre2partial man page
    
 not possible in general to obtain the exact number of characters that must be
 retained in order to get the right match result. If you cannot retain the
 entire segment, you must find some heuristic way of choosing.
-
    
-
    
+
    
+
    
 If you know the approximate length of the matching substrings, you can use that
 to decide how much text to retain. The only lookbehind information that is
 currently available via the API is the length of the longest individual
@@ -312,27 +312,27 @@ 
    pcre2partial man page
    
 units) that any individual lookbehind moves back when it is processed. A
 pattern such as "(?<=(?<!b)a)" has a maximum lookbehind value of one, but
 inspects two characters before its starting point.
-
    
-
    
+
    
+
    
 In a non-UTF or a 32-bit case, moving back is just a subtraction, but in
 UTF-8 or UTF-16 you have to count characters while moving back through the code
 units.
-
    
+
    
 
    PARTIAL MATCHING USING pcre2_dfa_match()
    
-
    
+
    
 The DFA function moves along the subject string character by character, without
 backtracking, searching for all possible matches simultaneously. If the end of
 the subject is reached before the end of the pattern, there is the possibility
 of a partial match.
-
    
-
    
+
    
+
    
 When PCRE2_PARTIAL_SOFT is set, PCRE2_ERROR_PARTIAL is returned only if there
 have been no complete matches. Otherwise, the complete matches are returned.
 If PCRE2_PARTIAL_HARD is set, a partial match takes precedence over any
 complete matches. The portion of the string that was matched when the longest
 partial match was found is set as the first matching string.
-
    
-
    
+
    
+
    
 Because the DFA function always searches for all possible matches, and there is
 no difference between greedy and ungreedy repetition, its behaviour is
 different from the pcre2_match(). Consider the string "dog" matched
@@ -343,9 +343,9 @@ 
    pcre2partial man page
    
 Whereas the standard function stops as soon as it finds the complete match for
 "dog", the DFA function also finds the partial match for "dogsbody", and so
 returns that when PCRE2_PARTIAL_HARD is set.
-
    
+
    
 
    MULTI-SEGMENT MATCHING WITH pcre2_dfa_match()
    
-
    
+
    
 When a partial match has been found using the DFA matching function, it is
 possible to continue the match by providing additional subject data and calling
 the function again with the same compiled regular expression, this time setting
@@ -379,26 +379,26 @@ 
    pcre2partial man page
    
 match because only those alternatives that match at one point in the subject
 are remembered. Depending on the application, this may or may not be what you
 want.
-
    
-
    
+
    
+
    
 If you do want to allow for starting again at the next character, one way of
 doing it is to retain some or all of the segment and try a new complete match,
 as described for pcre2_match() above. Another possibility is to work with
 two buffers. If a partial match at offset n in the first buffer is
 followed by "no match" when PCRE2_DFA_RESTART is used on the second buffer, you
 can then try a new match starting at offset n+1 in the first buffer.
-
    
+
    
 
    AUTHOR
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    REVISION
    
-
    
+
    
 Last updated: 27 November 2024
 
    
 Copyright © 1997-2019 University of Cambridge.
diff --git a/doc/html/pcre2pattern.html b/doc/html/pcre2pattern.html
index 84eb0aa17..5043c5833 100644
--- a/doc/html/pcre2pattern.html
+++ b/doc/html/pcre2pattern.html
@@ -51,7 +51,7 @@ 
    pcre2pattern man page
    
 
  • REVISION
 
 
    PCRE2 REGULAR EXPRESSION DETAILS
    
-
    
+
    
 The syntax and semantics of the regular expressions that are supported by PCRE2
 are described in detail below. There is a quick-reference syntax summary in the
 pcre2syntax
@@ -61,15 +61,15 @@ 
    pcre2pattern man page
    
 regular expressions in Python, .NET, and Oniguruma. There are in addition some
 options that enable alternative syntax and semantics that are not the same as
 in Perl.
-
    
-
    
+
    
+
    
 Perl's regular expressions are described in its own documentation, and regular
 expressions in general are covered in a number of books, some of which have
 copious examples. Jeffrey Friedl's "Mastering Regular Expressions", published
 by O'Reilly, covers regular expressions in great detail. This description of
 PCRE2's regular expressions is intended as reference material.
-
    
-
    
+
    
+
    
 This document discusses the regular expression patterns that are supported by
 PCRE2 when its main matching function, pcre2_match(), is used. PCRE2 also
 has an alternative matching function, pcre2_dfa_match(), which matches
@@ -79,9 +79,9 @@ 
    pcre2pattern man page
    
 function, are discussed in the
 pcre2matching
 page.
-
    
+
    
 
    EBCDIC CHARACTER CODES
    
-
    
+
    
 Most computers use ASCII or Unicode for encoding characters, and PCRE2 assumes
 this by default. However, it can be compiled to run in an environment that uses
 the EBCDIC code, which is the case for some IBM mainframe operating systems. In
@@ -91,20 +91,20 @@ 
    pcre2pattern man page
    
 an EBCDIC environment are described in the section
 "EBCDIC environments"
 below, which you can ignore unless you really are in an EBCDIC environment.
-
    
+
    
 
    SPECIAL START-OF-PATTERN ITEMS
    
-
    
+
    
 A number of options that can be passed to pcre2_compile() can also be set
 by special items at the start of a pattern. These are not Perl-compatible, but
 are provided to make these options accessible to pattern writers who are not
 able to change the program that processes the pattern. Any number of these
 items may appear, but they must all be together right at the start of the
 pattern string, and the letters must be in upper case.
-
    
+
    
 
    
 UTF support
 
    
-
    
+
    
 In the 8-bit and 16-bit PCRE2 libraries, characters may be coded either as
 single code units, or as multiple UTF-8 or UTF-16 code units. UTF-32 can be
 specified for the 32-bit library, in which case it constrains the character
@@ -117,17 +117,17 @@ 
    pcre2pattern man page
    
 below. There is also a summary of features in the
 pcre2unicode
 page.
-
    
-
    
+
    
+
    
 Some applications that allow their users to supply patterns may wish to
 restrict them to non-UTF data for security reasons. If the PCRE2_NEVER_UTF
 option is passed to pcre2_compile(), (*UTF) is not allowed, and its
 appearance in a pattern causes an error.
-
    
+
    
 
    
 Unicode property support
 
    
-
    
+
    
 Another special sequence that may appear at the start of a pattern is (*UCP).
 This has the same effect as setting the PCRE2_UCP option: it causes sequences
 such as \d and \w to use Unicode properties to determine character types,
@@ -137,27 +137,27 @@ 
    pcre2pattern man page
    
 These behaviours can be changed within the pattern; see the section entitled
 "Internal Option Setting"
 below.
-
    
-
    
+
    
+
    
 Some applications that allow their users to supply patterns may wish to
 restrict them for security reasons. If the PCRE2_NEVER_UCP option is passed to
 pcre2_compile(), (*UCP) is not allowed, and its appearance in a pattern
 causes an error.
-
    
+
    
 
    
 Locking out empty string matching
 
    
-
    
+
    
 Starting a pattern with (*NOTEMPTY) or (*NOTEMPTY_ATSTART) has the same effect
 as passing the PCRE2_NOTEMPTY or PCRE2_NOTEMPTY_ATSTART option to whichever
 matching function is subsequently called to match the pattern. These options
 lock out the matching of empty strings, either entirely, or only at the start
 of the subject.
-
    
+
    
 
    
 Disabling auto-possessification
 
    
-
    
+
    
 If a pattern starts with (*NO_AUTO_POSSESS), it has the same effect as setting
 the PCRE2_NO_AUTO_POSSESS option, or calling pcre2_set_optimize() with
 a PCRE2_AUTO_POSSESS_OFF directive. This stops PCRE2 from making quantifiers
@@ -165,22 +165,22 @@ 
    pcre2pattern man page
    
 default a+b is treated as a++b. For more details, see the
 pcre2api
 documentation.
-
    
+
    
 
    
 Disabling start-up optimizations
 
    
-
    
+
    
 If a pattern starts with (*NO_START_OPT), it has the same effect as setting the
 PCRE2_NO_START_OPTIMIZE option, or calling pcre2_set_optimize() with
 a PCRE2_START_OPTIMIZE_OFF directive. This disables several optimizations for
 quickly reaching "no match" results. For more details, see the
 pcre2api
 documentation.
-
    
+
    
 
    
 Disabling automatic anchoring
 
    
-
    
+
    
 If a pattern starts with (*NO_DOTSTAR_ANCHOR), it has the same effect as
 setting the PCRE2_NO_DOTSTAR_ANCHOR option, or calling pcre2_set_optimize()
 with a PCRE2_DOTSTAR_ANCHOR_OFF directive. This disables optimizations that
@@ -188,27 +188,27 @@ 
    pcre2pattern man page
    
 of arbitrary characters). For more details, see the
 pcre2api
 documentation.
-
    
+
    
 
    
 Disabling JIT compilation
 
    
-
    
+
    
 If a pattern that starts with (*NO_JIT) is successfully compiled, an attempt by
 the application to apply the JIT optimization by calling
 pcre2_jit_compile() is ignored.
-
    
+
    
 
    
 Setting match resource limits
 
    
-
    
+
    
 The pcre2_match() function contains a counter that is incremented every
 time it goes round its main loop. The caller of pcre2_match() can set a
 limit on this counter, which therefore limits the amount of computing resource
 used for a match. The maximum depth of nested backtracking can also be limited;
 this indirectly restricts the amount of heap memory that is used, but there is
 also an explicit memory limit that can be set.
-
    
-
    
+
    
+
    
 These facilities are provided to catch runaway matches that are provoked by
 patterns with huge matching trees. A common example is a pattern with nested
 unlimited repeats applied to a long string that does not match. When one of
@@ -225,12 +225,12 @@ 
    pcre2pattern man page
    
 limits set by the programmer, but not raise them. If there is more than one
 setting of one of these limits, the lower value is used. The heap limit is
 specified in kibibytes (units of 1024 bytes).
-
    
-
    
+
    
+
    
 Prior to release 10.30, LIMIT_DEPTH was called LIMIT_RECURSION. This name is
 still recognized for backwards compatibility.
-
    
-
    
+
    
+
    
 The heap limit applies only when the pcre2_match() or
 pcre2_dfa_match() interpreters are used for matching. It does not apply
 to JIT. The match limit is used (but in a different way) when JIT is being
@@ -239,11 +239,11 @@ 
    pcre2pattern man page
    
 relevant for DFA matching, which uses function recursion for recursions within
 the pattern and for lookaround assertions and atomic groups. In this case, the
 depth limit controls the depth of such recursion.
-
    
+
    
 
    
 Newline conventions
 
    
-
    
+
    
 PCRE2 supports six different conventions for indicating line breaks in
 strings: a single CR (carriage return) character, a single LF (linefeed)
 character, the two-character sequence CRLF, any of the three preceding, any
@@ -253,8 +253,8 @@ 
    pcre2pattern man page
    
 further discussion
 about newlines, and shows how to set the newline convention when calling
 pcre2_compile().
-
    
-
    
+
    
+
    
 It is also possible to specify a newline convention by starting a pattern
 string with one of the following sequences:
 
    @@ -273,8 +273,8 @@ 
    pcre2pattern man page
    
 changes the convention to CR. That pattern matches "a\nb" because LF is no
 longer a newline. If more than one of these settings is present, the last one
 is used.
-
    
-
    
+
    
+
    
 The newline convention affects where the circumflex and dollar assertions are
 true. It also affects the interpretation of the dot metacharacter when
 PCRE2_DOTALL is not set, and the behaviour of \N when not followed by an
@@ -285,19 +285,19 @@ 
    pcre2pattern man page
    
 "Newline sequences"
 below. A change of \R setting can be combined with a change of newline
 convention.
-
    
+
    
 
    
 Specifying what \R matches
 
    
-
    
+
    
 It is possible to restrict \R to match only CR, LF, or CRLF (instead of the
 complete set of Unicode line endings) by setting the option PCRE2_BSR_ANYCRLF
 at compile time. This effect can also be achieved by starting a pattern with
 (*BSR_ANYCRLF). For completeness, (*BSR_UNICODE) is also recognized,
 corresponding to PCRE2_BSR_UNICODE.
-
    
+
    
 
    CHARACTERS AND METACHARACTERS
    
-
    
+
    
 A regular expression is a pattern that is matched against a subject string from
 left to right. Most characters stand for themselves in a pattern, and match the
 corresponding characters in the subject. As a trivial example, the pattern
@@ -315,14 +315,14 @@ 
    pcre2pattern man page
    
 pattern). If the PCRE2_EXTRA_TURKISH_CASING option is in force (either passed
 to pcre2_compile() or set by (*TURKISH_CASING) within the pattern), then
 the 'i' letters are matched according to Turkish and Azeri languages.
-
    
-
    
+
    
+
    
 The power of regular expressions comes from the ability to include wild cards,
 character classes, alternatives, and repetitions in the pattern. These are
 encoded in the pattern by the use of metacharacters, which do not stand
 for themselves but instead are interpreted in some special way.
-
    
-
    
+
    
+
    
 There are two different sets of metacharacters: those that are recognized
 anywhere in the pattern except within square brackets, and those that are
 recognized within square brackets. Outside square brackets, the metacharacters
@@ -349,8 +349,8 @@ 
    pcre2pattern man page
    
 that is recognized only when the PCRE2_EXTRA_ALT_BSUX option is set. ECMAScript
 does not ignore such white space; it causes the item to be interpreted as
 literal.
-
    
-
    
+
    
+
    
 Part of a pattern that is in square brackets is called a "character class". In
 a character class the only metacharacters are:
 
    @@ -372,30 +372,30 @@ 
    pcre2pattern man page
    
 section entitled
 "Internal Option Setting"
 below.
-
    
-
    
+
    
+
    
 The following sections describe the use of each of the metacharacters.
-
    
+
    
 
    BACKSLASH
    
-
    
+
    
 The backslash character has several uses. Firstly, if it is followed by a
 character that is not a digit or a letter, it takes away any special meaning
 that character may have. This use of backslash as an escape character applies
 both inside and outside character classes.
-
    
-
    
+
    
+
    
 For example, if you want to match a * character, you must write \* in the
 pattern. This escaping action applies whether or not the following character
 would otherwise be interpreted as a metacharacter, so it is always safe to
 precede a non-alphanumeric with backslash to specify that it stands for itself.
 In particular, if you want to match a backslash, you write \\.
-
    
-
    
+
    
+
    
 Only ASCII digits and letters have any special meaning after a backslash. All
 other characters (in particular, those whose code points are greater than 127)
 are treated as literals.
-
    
-
    
+
    
+
    
 If you want to treat all characters in a sequence as literals, you can do so by
 putting them between \Q and \E. Note that this includes white space even when
 the PCRE2_EXTENDED option is set so that most other white space is ignored. The
@@ -420,19 +420,19 @@ 
    pcre2pattern man page
    
 the pattern (that is, \E is assumed at the end). If the isolated \Q is inside
 a character class, this causes an error, because the character class is then
 not terminated by a closing square bracket.
-
    
-
    
+
    
+
    
 Another difference from Perl is that any appearance of \Q or \E inside what
 might otherwise be a quantifier causes PCRE2 not to recognize the sequence as a
 quantifier. Perl recognizes a quantifier if (redundantly) either of the numbers
 is inside \Q...\E, but not if the separating comma is. When not recognized as
 a quantifier a sequence such as {\Q1\E,2} is treated as the literal string
 "{1,2}".
-
    
+
    
 
    
 Non-printing characters
 
    
-
    
+
    
 A second use of backslash provides a way of encoding non-printing characters
 in patterns in a visible manner. There is no restriction on the appearance of
 non-printing characters in a pattern, but when a pattern is being prepared by
@@ -458,26 +458,26 @@ 
    pcre2pattern man page
    
 later,
 following the discussion of
 parenthesized groups.
-
    
-
    
+
    
+
    
 By default, after \x that is not followed by {, one or two hexadecimal
 digits are read (letters can be in upper or lower case). If the character that
 follows \x is neither { nor a hexadecimal digit, an error occurs. This is
 different from Perl's default behaviour, which generates a NUL character, but
 is in line with the behaviour of Perl's 'strict' mode in re.
-
    
-
    
+
    
+
    
 Any number of hexadecimal digits may appear between \x{ and }. If a character
 other than a hexadecimal digit appears between \x{ and }, or if there is no
 terminating }, an error occurs.
-
    
-
    
+
    
+
    
 Characters whose code points are less than 256 can be defined by either of the
 two syntaxes for \x or by an octal sequence. There is no difference in the way
 they are handled. For example, \xdc is exactly the same as \x{dc} or \334.
 However, using the braced versions does make such sequences easier to read.
-
    
-
    
+
    
+
    
 Support is available for some ECMAScript (aka JavaScript) escape sequences via
 two compile-time options. If PCRE2_ALT_BSUX is set, the sequence \x followed
 by { is not recognized. Only if \x is followed by two hexadecimal digits is it
@@ -485,28 +485,28 @@ 
    pcre2pattern man page
    
 character. In this mode, support for code points greater than 256 is provided
 by \u, which must be followed by four hexadecimal digits; otherwise it is
 interpreted as a literal "u" character.
-
    
-
    
+
    
+
    
 PCRE2_EXTRA_ALT_BSUX has the same effect as PCRE2_ALT_BSUX and, in addition,
 \u{hhh..} is recognized as the character specified by hexadecimal code point.
 There may be any number of hexadecimal digits, but unlike other places that
 also use curly brackets, spaces are not allowed and would result in the string
 being interpreted as a literal. This syntax is from ECMAScript 6.
-
    
-
    
+
    
+
    
 The \N{U+hhh..} escape sequence is recognized only when PCRE2 is operating in
 UTF mode. Perl also uses \N{name} to specify characters by Unicode name; PCRE2
 does not support this. Note that when \N is not followed by an opening brace
 (curly bracket) it has an entirely different meaning, matching any character
 that is not a newline.
-
    
-
    
+
    
+
    
 There are some legacy applications where the escape sequence \r is expected to
 match a newline. If the PCRE2_EXTRA_ESCAPED_CR_IS_LF option is set, \r in a
 pattern is converted to \n so that it matches a LF (linefeed) instead of a CR
 (carriage return) character.
-
    
-
    
+
    
+
    
 An error occurs if \c is not followed by a character whose ASCII code point
 is in the range 32 to 126. The precise effect of \cx is as follows: if x is a
 lower case letter, it is converted to upper case. Then bit 6 of the character
@@ -514,51 +514,51 @@ 
    pcre2pattern man page
    
 5A), but \c{ becomes hex 3B ({ is 7B), and \c; becomes hex 7B (; is 3B). If
 the code unit following \c has a code point less than 32 or greater than 126,
 a compile-time error occurs.
-
    
-
    
+
    
+
    
 For differences in the way some escapes behave in EBCDIC environments,
 see section
 "EBCDIC environments"
 below.
-
    
+
    
 
    
 Octal escapes and back references
 
    
-
    
+
    
 The escape \o must be followed by a sequence of octal digits, enclosed in
 braces. An error occurs if this is not the case. This escape provides a way of
 specifying character code points as octal numbers greater than 0777, and it
 also allows octal numbers and backreferences to be unambiguously distinguished.
-
    
-
    
+
    
+
    
 If braces are not used, after \0 up to two further octal digits are read.
 However, if the PCRE2_EXTRA_NO_BS0 option is set, at least one more octal digit
 must follow \0 (use \00 to generate a NUL character). Make sure you supply
 two digits after the initial zero if the pattern character that follows is
 itself an octal digit.
-
    
-
    
+
    
+
    
 Inside a character class, when a backslash is followed by any octal digit, up
 to three octal digits are read to generate a code point. Any subsequent digits
 stand for themselves. The sequences \8 and \9 are treated as the literal
 characters "8" and "9".
-
    
-
    
+
    
+
    
 Outside a character class, Perl's handling of a backslash followed by a digit
 other than 0 is complicated by ambiguity, and Perl has changed over time,
 causing PCRE2 also to change. From PCRE2 release 10.45 there is an option
 called PCRE2_EXTRA_PYTHON_OCTAL that causes PCRE2 to use Python's unambiguous
 rules. The next two subsections describe the two sets of rules.
-
    
-
    
+
    
+
    
 For greater clarity and unambiguity, it is best to avoid following \ by a
 digit greater than zero. Instead, use \o{...} or \x{...} to specify numerical
 character code points, and \g{...} to specify backreferences.
-
    
+
    
 
    
 Perl rules for non-class backslash 1-9
 
    
-
    
+
    
 All the digits that follow the backslash are read as a decimal number. If the
 number is less than 10, begins with the digit 8 or 9, or if there are at least
 that many previous capture groups in the expression, the entire sequence is
@@ -578,11 +578,11 @@ 
    pcre2pattern man page
    
 Note that octal values of 100 or greater that are specified using this syntax
 must not be introduced by a leading zero, because no more than three octal
 digits are ever read.
-
    
+
    
 
    
 Python rules for non_class backslash 1-9
 
    
-
    
+
    
 If there are at least three octal digits after the backslash, exactly three are
 read as an octal code point number, but the value must be no greater than
 \377, even in modes where higher code point values are supported. Any
@@ -591,11 +591,11 @@ 
    pcre2pattern man page
    
 \12 is always a back reference, independent of how many captures there are in
 the pattern. An error is generated for a reference to a non-existent capturing
 group.
-
    
+
    
 
    
 Constraints on character values
 
    
-
    
+
    
 Characters that are specified using octal or hexadecimal numbers are
 limited to certain values, as follows:
 
    @@ -609,47 +609,47 @@ 
    pcre2pattern man page
    
 caller of pcre2_compile() by setting the option
 PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES. However, this is possible only in UTF-8
 and UTF-32 modes, because these values are not representable in UTF-16.
-
    
+
    
 
    
 Escape sequences in character classes
 
    
-
    
+
    
 All the sequences that define a single character value can be used both inside
 and outside character classes. In addition, inside a character class, \b is
 interpreted as the backspace character (hex 08).
-
    
-
    
+
    
+
    
 When not followed by an opening brace, \N is not allowed in a character class.
 \B, \R, and \X are not special inside a character class. Like other
 unrecognized alphabetic escape sequences, they cause an error. Outside a
 character class, these sequences have different meanings.
-
    
+
    
 
    
 Unsupported escape sequences
 
    
-
    
+
    
 In Perl, the sequences \F, \l, \L, \u, and \U are recognized by its string
 handler and used to modify the case of following characters. By default, PCRE2
 does not support these escape sequences in patterns. However, if either of the
 PCRE2_ALT_BSUX or PCRE2_EXTRA_ALT_BSUX options is set, \U matches a "U"
 character, and \u can be used to define a character by code point, as
 described above.
-
    
+
    
 
    
 Absolute and relative backreferences
 
    
-
    
+
    
 The sequence \g followed by a signed or unsigned number, optionally enclosed
 in braces, is an absolute or relative backreference. A named backreference
 can be coded as \g{name}. Backreferences are discussed
 later,
 following the discussion of
 parenthesized groups.
-
    
+
    
 
    
 Absolute and relative subroutine calls
 
    
-
    
+
    
 For compatibility with Oniguruma, the non-Perl syntax \g followed by a name or
 a number enclosed either in angle brackets or single quotes, is an alternative
 syntax for referencing a capture group as a subroutine. Details are discussed
@@ -658,11 +658,11 @@ 
    pcre2pattern man page
    
 synonymous. The former is a backreference; the latter is a
 subroutine
 call.
-
    
+
    
 
    
 Generic character types
 
    
-
    
+
    
 Another use of backslash is for specifying generic character types:
 
       \d     any decimal digit
@@ -685,23 +685,23 @@ 
    pcre2pattern man page
    
 "Non-printing characters"
 above for details. Perl also uses \N{name} to specify characters by Unicode
 name; PCRE2 does not support this.
-
    
-
    
+
    
+
    
 Each pair of lower and upper case escape sequences partitions the complete set
 of characters into two disjoint sets. Any given character matches one, and only
 one, of each pair. The sequences can appear both inside and outside character
 classes. They each match one character of the appropriate type. If the current
 matching point is at the end of the subject string, all of them fail, because
 there is no character to match.
-
    
-
    
+
    
+
    
 The default \s characters are HT (9), LF (10), VT (11), FF (12), CR (13), and
 space (32), which are defined as white space in the "C" locale. This list may
 vary if locale-specific matching is taking place. For example, in some locales
 the "non-breaking space" character (\xA0) is recognized as white space, and in
 others the VT character is not.
-
    
-
    
+
    
+
    
 A "word" character is an underscore or any character that is a letter or digit.
 By default, the definition of letters and digits is controlled by PCRE2's
 low-valued character tables, and may vary if locale-specific matching is taking
@@ -713,8 +713,8 @@ 
    pcre2pattern man page
    
 or "french" in Windows, some character codes greater than 127 are used for
 accented letters, and these are then matched by \w. The use of locales with
 Unicode is discouraged.
-
    
-
    
+
    
+
    
 By default, characters whose code points are greater than 127 never match \d,
 \s, or \w, and always match \D, \S, and \W, although this may be different
 for characters in the range 128-255 when locale-specific matching is happening.
@@ -730,22 +730,22 @@ 
    pcre2pattern man page
    
 The addition of \p{Mn} (non-spacing mark) and the replacement of an explicit
 test for underscore with a test for \p{Pc} (connector punctuation) happened in
 PCRE2 release 10.43. This brings PCRE2 into line with Perl.
-
    
-
    
+
    
+
    
 The upper case escapes match the inverse sets of characters. Note that \d
 matches only decimal digits, whereas \w matches any Unicode digit, as well as
 other character categories. Note also that PCRE2_UCP affects \b, and
 \B because they are defined in terms of \w and \W. Matching these sequences
 is noticeably slower when PCRE2_UCP is set.
-
    
-
    
+
    
+
    
 The effect of PCRE2_UCP on any one of these escape sequences can be negated by
 the options PCRE2_EXTRA_ASCII_BSD, PCRE2_EXTRA_ASCII_BSS, and
 PCRE2_EXTRA_ASCII_BSW, respectively. These options can be set and reset within
 a pattern by means of an internal option setting
 (see below).
-
    
-
    
+
    
+
    
 The sequences \h, \H, \v, and \V, in contrast to the other sequences, which
 match only ASCII characters by default, always match a specific list of code
 points, whether or not PCRE2_UCP is set. The horizontal space characters are:
@@ -782,11 +782,11 @@ 
    pcre2pattern man page
    
 
    
 In 8-bit, non-UTF-8 mode, only the characters with code points less than 256
 are relevant.
-
    
+
    
 
    
 Newline sequences
 
    
-
    
+
    
 Outside a character class, by default, the escape sequence \R matches any
 Unicode newline sequence. In 8-bit non-UTF-8 mode \R is equivalent to the
 following:
@@ -800,13 +800,13 @@ 
    pcre2pattern man page
    
 U+000B), FF (form feed, U+000C), CR (carriage return, U+000D), or NEL (next
 line, U+0085). Because this is an atomic group, the two-character sequence is
 treated as a single unit that cannot be split.
-
    
-
    
+
    
+
    
 In other modes, two additional characters whose code points are greater than 255
 are added: LS (line separator, U+2028) and PS (paragraph separator, U+2029).
 Unicode support is not needed for these characters to be recognized.
-
    
-
    
+
    
+
    
 It is possible to restrict \R to match only CR, LF, or CRLF (instead of the
 complete set of Unicode line endings) by setting the option PCRE2_BSR_ANYCRLF
 at compile time. (BSR is an abbreviation for "backslash R".) This can be made
@@ -829,11 +829,11 @@ 
    pcre2pattern man page
    
 They can also be combined with the (*UTF) or (*UCP) special sequences. Inside a
 character class, \R is treated as an unrecognized escape sequence, and causes
 an error.
-
    
+
    
 
    
 Unicode character properties
 
    
-
    
+
    
 When PCRE2 is built with Unicode support (the default), three additional escape
 sequences that match characters with specific properties are available. They
 can be used in any mode, though in 8-bit and 16-bit non-UTF modes these
@@ -841,15 +841,15 @@ 
    pcre2pattern man page
    
 less than U+0100 or U+10000, respectively. In 32-bit non-UTF mode, code points
 greater than 0x10ffff (the Unicode limit) may be encountered. These are all
 treated as being in the Unknown script and with an unassigned type.
-
    
-
    
+
    
+
    
 Matching characters by Unicode property is not fast, because PCRE2 has to do a
 multistage table lookup in order to find a character's property. That is why
 the traditional escape sequences such as \d and \w do not use Unicode
 properties in PCRE2 by default, though you can make them do so by setting the
 PCRE2_UCP option or by starting the pattern with (*UCP).
-
    
-
    
+
    
+
    
 The extra escape sequences that provide property support are:
 
       \p{xx}   a character with the xx property
@@ -859,14 +859,14 @@ 
    pcre2pattern man page
    
 For compatibility with Perl, negation can be specified by including a
 circumflex between the opening brace and the property. For example, \p{^Lu} is
 the same as \P{Lu}.
-
    
-
    
+
    
+
    
 In accordance with Unicode's "loose matching" rules, ASCII white space
 characters, hyphens, and underscores are ignored in the properties represented
 by xx above. As well as the space character, ASCII white space can be
 tab, linefeed, vertical tab, formfeed, or carriage return.
-
    
-
    
+
    
+
    
 Some properties are specified as a name only; others as a name and a value,
 separated by a colon or an equals sign. The names and values consist of ASCII
 letters and digits (with one Perl-specific exception, see below). They are not
@@ -887,11 +887,11 @@ 
    pcre2pattern man page
    
 Certain other Perl properties such as "InMusicalSymbols" are not supported by
 PCRE2. Note that \P{Any} does not match any characters, so always causes a
 match failure.
-
    
+
    
 
    
 Script properties for \p and \P
 
    
-
    
+
    
 There are three different syntax forms for matching a script. Each Unicode
 character has a basic script and, optionally, a list of other scripts ("Script
 Extensions") with which it is commonly used. Using the Adlam script as an
@@ -903,8 +903,8 @@ 
    pcre2pattern man page
    
 property type, for example, \p{Adlam}, it is treated as \p{scx:Adlam}. Perl
 changed to this interpretation at release 5.26 and PCRE2 changed at release
 10.40.
-
    
-
    
+
    
+
    
 Unassigned characters (and in non-UTF 32-bit mode, characters with code points
 greater than 0x10FFFF) are assigned the "Unknown" script. Others that are not
 part of an identified script are lumped together as "Common". The current list
@@ -913,12 +913,12 @@ 
    pcre2pattern man page
    
 
       pcre2test -LS
 
-
    
-
    
+
    
+
    
 
    
 The general category property for \p and \P
 
    
-
    
+
    
 Each character has exactly one Unicode general category property, specified by
 a two-letter abbreviation. If only one letter is specified with \p or \P, it
 includes all the general category properties that start with that letter. In
@@ -982,8 +982,8 @@ 
    pcre2pattern man page
    
 the properties Lu, Ll, and Lt are all treated as Lc when case-independent
 matching is set by the PCRE2_CASELESS option or (?i) within the pattern. The
 other properties are not affected by caseless matching.
-
    
-
    
+
    
+
    
 The Cs (Surrogate) property applies only to characters whose code points are in
 the range U+D800 to U+DFFF. These characters are no different to any other
 character when PCRE2 is not in UTF mode (using the 16-bit or 32-bit library).
@@ -992,33 +992,33 @@ 
    pcre2pattern man page
    
 discussion of PCRE2_NO_UTF_CHECK in the
 pcre2api
 page).
-
    
-
    
+
    
+
    
 The long synonyms for property names that Perl supports (such as \p{Letter})
 are not supported by PCRE2, nor is it permitted to prefix any of these
 properties with "Is".
-
    
-
    
+
    
+
    
 No character that is in the Unicode table has the Cn (unassigned) property.
 Instead, this property is assumed for any code point that is not in the
 Unicode table.
-
    
+
    
 
    
 Binary (yes/no) properties for \p and \P
 
    
-
    
+
    
 Unicode defines a number of binary properties, that is, properties whose only
 values are true or false. You can obtain a list of those that are recognized by
 \p and \P, along with their abbreviations, by running this command:
 
       pcre2test -LP
 
-
    
-
    
+
    
+
    
 
    
 The Bidi_Class property for \p and \P
 
    
-
    
+
    
 
       \p{Bidi_Class:<class>}   matches a character with the given class
   \p{BC:<class>}           matches a character with the given class
@@ -1052,11 +1052,11 @@ 
    pcre2pattern man page
    
 As in all property specifications, an equals sign may be used instead of a
 colon and the class names are case-insensitive. Only the short names listed
 above are recognized; PCRE2 does not at present support any long alternatives.
-
    
+
    
 
    
 Extended grapheme clusters
 
    
-
    
+
    
 The \X escape matches any number of Unicode characters that form an "extended
 grapheme cluster", and treats the sequence as an atomic group
 (see below).
@@ -1067,50 +1067,50 @@ 
    pcre2pattern man page
    
 abandoned the use of some previous properties that had been used for emojis.
 Instead it introduced various emoji-specific properties. PCRE2 uses only the
 Extended Pictographic property.
-
    
-
    
+
    
+
    
 \X always matches at least one character. Then it decides whether to add
 additional characters according to the following rules for ending a cluster:
-
    
-
    
+
    
+
    
 1. End at the end of the subject string.
-
    
-
    
+
    
+
    
 2. Do not end between CR and LF; otherwise end after any control character.
-
    
-
    
+
    
+
    
 3. Do not break Hangul (a Korean script) syllable sequences. Hangul characters
 are of five types: L, V, T, LV, and LVT. An L character may be followed by an
 L, V, LV, or LVT character; an LV or V character may be followed by a V or T
 character; an LVT or T character may be followed only by a T character.
-
    
-
    
+
    
+
    
 4. Do not end before extending characters or spacing marks or the zero-width
 joiner (ZWJ) character. Characters with the "mark" property always have the
 "extend" grapheme breaking property.
-
    
-
    
+
    
+
    
 5. Do not end after prepend characters.
-
    
-
    
+
    
+
    
 6. Do not end within emoji modifier sequences or emoji ZWJ (zero-width
 joiner) sequences. An emoji ZWJ sequence consists of a character with the
 Extended_Pictographic property, optionally followed by one or more characters
 with the Extend property, followed by the ZWJ character, followed by another
 Extended_Pictographic character.
-
    
-
    
+
    
+
    
 7. Do not break within emoji flag sequences. That is, do not break between
 regional indicator (RI) characters if there are an odd number of RI characters
 before the break point.
-
    
-
    
+
    
+
    
 8. Otherwise, end the cluster.
-
    
+
    
 
    
 PCRE2's additional properties
 
    
-
    
+
    
 As well as the standard Unicode properties described above, PCRE2 supports four
 more that make it possible to convert traditional escape sequences such as \w
 and \s to use Unicode properties. PCRE2 uses these non-standard, non-Perl
@@ -1129,8 +1129,8 @@ 
    pcre2pattern man page
    
 to exclude vertical tab, for Perl compatibility, but Perl changed. Xwd matches
 the same characters as Xan, plus those that match Mn (non-spacing mark) or Pc
 (connector punctuation, which includes underscore).
-
    
-
    
+
    
+
    
 There is another non-standard property, Xuc, which matches any character that
 can be represented by a Universal Character Name in C++ and other programming
 languages. These are the characters $, @, ` (grave accent), and all characters
@@ -1139,11 +1139,11 @@ 
    pcre2pattern man page
    
 excluded. (Universal Character Names are of the form \uHHHH or \UHHHHHHHH
 where H is a hexadecimal digit. Note that the Xuc property does not match these
 sequences but the characters that they represent.)
-
    
+
    
 
    
 Resetting the match start
 
    
-
    
+
    
 In normal use, the escape sequence \K causes any previously matched characters
 not to be included in the final matched sequence that is returned. For example,
 the pattern:
@@ -1168,8 +1168,8 @@ 
    pcre2pattern man page
    
   (foo)\Kbar
 
    
 matches "foobar", the first substring is still set to "foo".
-
    
-
    
+
    
+
    
 From version 5.32.0 Perl forbids the use of \K in lookaround assertions. From
 release 10.38 PCRE2 also forbids this by default. However, the
 PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK option can be used when calling
@@ -1185,11 +1185,11 @@ 
    pcre2pattern man page
    
 If the subject is "foobar", a call to pcre2_match() with a starting
 offset of 3 succeeds and reports the matching string as "foobar", that is, the
 start of the reported match is earlier than where the match started.
-
    
+
    
 
    
 Simple assertions
 
    
-
    
+
    
 The final use of backslash is for certain simple assertions. An assertion
 specifies a condition that has to be met at a particular point in a match,
 without consuming any characters from the subject string. The use of
@@ -1208,8 +1208,8 @@ 
    pcre2pattern man page
    
 Inside a character class, \b has a different meaning; it matches the backspace
 character. If any other of these assertions appears in a character class, an
 "invalid escape sequence" error is generated.
-
    
-
    
+
    
+
    
 A word boundary is a position in the subject string where the current character
 and the previous character do not both match \w or \W (i.e. one matches
 \w and the other matches \W), or the start or end of the string if the
@@ -1219,8 +1219,8 @@ 
    pcre2pattern man page
    
 nor Perl has a separate "start of word" or "end of word" metasequence. However,
 whatever follows \b normally determines which it is. For example, the fragment
 \ba matches "a" at the start of a word.
-
    
-
    
+
    
+
    
 The \A, \Z, and \z assertions differ from the traditional circumflex and
 dollar (described in the next section) in that they only ever match at the very
 start and end of the subject string, whatever options are set. Thus, they are
@@ -1232,29 +1232,29 @@ 
    pcre2pattern man page
    
 The difference between \Z and \z is that \Z matches before a newline at the
 end of the string as well as at the very end, whereas \z matches only at the
 end.
-
    
-
    
+
    
+
    
 The \G assertion is true only when the current matching position is at the
 start point of the matching process, as specified by the startoffset
 argument of pcre2_match(). It differs from \A when the value of
 startoffset is non-zero. By calling pcre2_match() multiple times
 with appropriate arguments, you can mimic Perl's /g option, and it is in this
 kind of implementation where \G can be useful.
-
    
-
    
+
    
+
    
 Note, however, that PCRE2's implementation of \G, being true at the starting
 character of the matching process, is subtly different from Perl's, which
 defines it as true at the end of the previous match. In Perl, these can be
 different when the previously matched string was empty. Because PCRE2 does just
 one match at a time, it cannot reproduce this behaviour.
-
    
-
    
+
    
+
    
 If all the alternatives of a pattern begin with \G, the expression is anchored
 to the starting match position, and the "anchored" flag is set in the compiled
 regular expression.
-
    
+
    
 
    CIRCUMFLEX AND DOLLAR
    
-
    
+
    
 The circumflex and dollar metacharacters are zero-width assertions. That is,
 they test for a particular condition being true without consuming any
 characters from the subject string. These two metacharacters are concerned with
@@ -1262,8 +1262,8 @@ 
    pcre2pattern man page
    
 only the two-character sequence CRLF is recognized as a newline, isolated CR
 and LF characters are treated as ordinary data characters, and are not
 recognized as newlines.
-
    
-
    
+
    
+
    
 Outside a character class, in the default matching mode, the circumflex
 character is an assertion that is true only if the current matching point is at
 the start of the subject string. If the startoffset argument of
@@ -1271,8 +1271,8 @@ 
    pcre2pattern man page
    
 never match if the PCRE2_MULTILINE option is unset. Inside a character class,
 circumflex has an entirely different meaning
 (see below).
-
    
-
    
+
    
+
    
 Circumflex need not be the first character of the pattern if a number of
 alternatives are involved, but it should be the first thing in each alternative
 in which it appears if the pattern is ever to match that branch. If all
@@ -1280,8 +1280,8 @@ 
    pcre2pattern man page
    
 constrained to match only at the start of the subject, it is said to be an
 "anchored" pattern. (There are also other constructs that can cause a pattern
 to be anchored.)
-
    
-
    
+
    
+
    
 The dollar character is an assertion that is true only if the current matching
 point is at the end of the subject string, or immediately before a newline at
 the end of the string (by default), unless PCRE2_NOTEOL is set. Note, however,
@@ -1289,13 +1289,13 @@ 
    pcre2pattern man page
    
 character of the pattern if a number of alternatives are involved, but it
 should be the last item in any branch in which it appears. Dollar has no
 special meaning in a character class.
-
    
-
    
+
    
+
    
 The meaning of dollar can be changed so that it matches only at the very end of
 the string, by setting the PCRE2_DOLLAR_ENDONLY option at compile time. This
 does not affect the \Z assertion.
-
    
-
    
+
    
+
    
 The meanings of the circumflex and dollar metacharacters are changed if the
 PCRE2_MULTILINE option is set. When this is the case, a dollar character
 matches before any newlines in the string, as well as at the very end, and a
@@ -1303,16 +1303,16 @@ 
    pcre2pattern man page
    
 of the subject string. It does not match after a newline that ends the string,
 for compatibility with Perl. However, this can be changed by setting the
 PCRE2_ALT_CIRCUMFLEX option.
-
    
-
    
+
    
+
    
 For example, the pattern /^abc$/ matches the subject string "def\nabc" (where
 \n represents a newline) in multiline mode, but not otherwise. Consequently,
 patterns that are anchored in single line mode because all branches start with
 ^ are not anchored in multiline mode, and a match for circumflex is possible
 when the startoffset argument of pcre2_match() is non-zero. The
 PCRE2_DOLLAR_ENDONLY option is ignored if PCRE2_MULTILINE is set.
-
    
-
    
+
    
+
    
 When the newline convention (see
 "Newline conventions"
 below) recognizes the two-character sequence CRLF as a newline, this is
@@ -1321,74 +1321,74 @@ 
    pcre2pattern man page
    
 circumflex matches before "xyz" in the string "abc\r\nxyz" rather than after
 CR, even though CR on its own is a valid newline. (It also matches at the very
 start of the string, of course.)
-
    
-
    
+
    
+
    
 Note that the sequences \A, \Z, and \z can be used to match the start and
 end of the subject in both modes, and if all branches of a pattern start with
 \A it is always anchored, whether or not PCRE2_MULTILINE is set.
-
    
+
    
 
    FULL STOP (PERIOD, DOT) AND \N
    
-
    
+
    
 Outside a character class, a dot in the pattern matches any one character in
 the subject string except (by default) a character that signifies the end of a
 line. One or more characters may be specified as line terminators (see
 "Newline conventions"
 above).
-
    
-
    
+
    
+
    
 Dot never matches a single line-ending character. When the two-character
 sequence CRLF is the only line ending, dot does not match CR if it is
 immediately followed by LF, but otherwise it matches all characters (including
 isolated CRs and LFs). When ANYCRLF is selected for line endings, no occurrences
 of CR of LF match dot. When all Unicode line endings are being recognized, dot
 does not match CR or LF or any of the other line ending characters.
-
    
-
    
+
    
+
    
 The behaviour of dot with regard to newlines can be changed. If the
 PCRE2_DOTALL option is set, a dot matches any one character, without exception.
 If the two-character sequence CRLF is present in the subject string, it takes
 two dots to match it.
-
    
-
    
+
    
+
    
 The handling of dot is entirely independent of the handling of circumflex and
 dollar, the only relationship being that they both involve newlines. Dot has no
 special meaning in a character class.
-
    
-
    
+
    
+
    
 The escape sequence \N when not followed by an opening brace behaves like a
 dot, except that it is not affected by the PCRE2_DOTALL option. In other words,
 it matches any character except one that signifies the end of a line.
-
    
-
    
+
    
+
    
 When \N is followed by an opening brace it has a different meaning. See the
 section entitled
-"Non-printing characters"
+"Non-printing characters"
 above for details. Perl also uses \N{name} to specify characters by Unicode
 name; PCRE2 does not support this.
-
    
+
    
 
    MATCHING A SINGLE CODE UNIT
    
-
    
+
    
 Outside a character class, the escape sequence \C matches any one code unit,
 whether or not a UTF mode is set. In the 8-bit library, one code unit is one
 byte; in the 16-bit library it is a 16-bit unit; in the 32-bit library it is a
 32-bit unit. Unlike a dot, \C always matches line-ending characters. The
 feature is provided in Perl in order to match individual bytes in UTF-8 mode,
 but it is unclear how it can usefully be used.
-
    
-
    
+
    
+
    
 Because \C breaks up characters into individual code units, matching one unit
 with \C in UTF-8 or UTF-16 mode means that the rest of the string may start
 with a malformed UTF character. This has undefined results, because PCRE2
 assumes that it is matching character by character in a valid UTF string (by
 default it checks the subject string's validity at the start of processing
 unless the PCRE2_NO_UTF_CHECK or PCRE2_MATCH_INVALID_UTF option is used).
-
    
-
    
+
    
+
    
 An application can lock out the use of \C by setting the
 PCRE2_NEVER_BACKSLASH_C option when compiling a pattern. It is also possible to
 build PCRE2 with the use of \C permanently disabled.
-
    
-
    
+
    
+
    
 PCRE2 does not allow \C to appear in lookbehind assertions
 (described below)
 in UTF-8 or UTF-16 modes, because this would make it impossible to calculate
@@ -1396,13 +1396,13 @@ 
    pcre2pattern man page
    
 pcre2_dfa_match() nor the JIT optimizer support \C in these UTF modes.
 The former gives a match-time error; the latter fails to optimize and so the
 match is always run using the interpreter.
-
    
-
    
+
    
+
    
 In the 32-bit library, however, \C is always supported (when not explicitly
 locked out) because it always matches a single code unit, whether or not UTF-32
 is specified.
-
    
-
    
+
    
+
    
 In general, the \C escape sequence is best avoided. However, one way of using
 it that avoids the problem of malformed UTF-8 or UTF-16 characters is to use a
 lookahead to check the length of the next character, as in this pattern, which
@@ -1420,9 +1420,9 @@ 
    pcre2pattern man page
    
 character for values whose encoding uses 1, 2, 3, or 4 bytes, respectively. The
 character's individual bytes are then captured by the appropriate number of
 \C groups.
-
    
+
    
 
    SQUARE BRACKETS AND CHARACTER CLASSES
    
-
    
+
    
 An opening square bracket introduces a character class, terminated by a closing
 square bracket. A closing square bracket on its own is not special by default.
 If a closing square bracket is required as a member of the class, it should be
@@ -1430,24 +1430,24 @@ 
    pcre2pattern man page
    
 or escaped with a backslash. This means that, by default, an empty class cannot
 be defined. However, if the PCRE2_ALLOW_EMPTY_CLASS option is set, a closing
 square bracket at the start does end the (empty) class.
-
    
-
    
+
    
+
    
 A character class matches a single character in the subject. A matched
 character must be in the set of characters defined by the class, unless the
 first character in the class definition is a circumflex, in which case the
 subject character must not be in the set defined by the class. If a circumflex
 is actually required as a member of the class, ensure it is not the first
 character, or escape it with a backslash.
-
    
-
    
+
    
+
    
 For example, the character class [aeiou] matches any lower case English vowel,
 whereas [^aeiou] matches all other characters. Note that a circumflex is just a
 convenient notation for specifying the characters that are in the class by
 enumerating those that are not. A class that starts with a circumflex is not an
 assertion; it still consumes a character from the subject string, and therefore
 it fails to match if the current pointer is at the end of the string.
-
    
-
    
+
    
+
    
 Characters in a class may be specified by their code points using \o, \x, or
 \N{U+hh..} in the usual way. When caseless matching is set, any letters in a
 class represent both their upper case and lower case versions, so for example,
@@ -1459,14 +1459,14 @@ 
    pcre2pattern man page
    
 these ASCII/non-ASCII case equivalences, you can suppress them by setting
 PCRE2_EXTRA_CASELESS_RESTRICT, either as an option in a compile context, or by
 including (*CASELESS_RESTRICT) or (?r) within a pattern.
-
    
-
    
+
    
+
    
 Characters that might indicate line breaks are never treated in any special way
 when matching character classes, whatever line-ending sequence is in use, and
 whatever setting of the PCRE2_DOTALL and PCRE2_MULTILINE options is used. A
 class such as [^a] always matches one of these characters.
-
    
-
    
+
    
+
    
 The generic character type escape sequences \d, \D, \h, \H, \p, \P, \s,
 \S, \v, \V, \w, and \W may appear in a character class, and add the
 characters that they match to the class. For example, [\dABCDEF] matches any
@@ -1479,8 +1479,8 @@ 
    pcre2pattern man page
    
 not special inside a character class. Like any other unrecognized escape
 sequences, they cause an error. The same is true for \N when not followed by
 an opening brace.
-
    
-
    
+
    
+
    
 The minus (hyphen) character can be used to specify a range of characters in a
 character class. For example, [d-m] matches any letter between d and m,
 inclusive. If a minus character is required in a class, it must be escaped with
@@ -1488,21 +1488,21 @@ 
    pcre2pattern man page
    
 indicating a range, typically as the first or last character in the class,
 or immediately after a range. For example, [b-d-z] matches letters in the range
 b to d, a hyphen character, or z.
-
    
-
    
+
    
+
    
 There is some special treatment for alphabetic ranges in EBCDIC environments;
 see the section
 "EBCDIC environments"
 below.
-
    
-
    
+
    
+
    
 Perl treats a hyphen as a literal if it appears before or after a POSIX class
 (see below) or before or after a character type escape such as \d or \H.
 However, unless the hyphen is the last character in the class, Perl outputs a
 warning in its warning mode, as this is most likely a user error. As PCRE2 has
 no facility for warning, an error is given in these cases.
-
    
-
    
+
    
+
    
 It is not possible to have the literal character "]" as the end character of a
 range. A pattern such as [W-]46] is interpreted as a class of two characters
 ("W" and "-") followed by a literal string "46]", so it would match "W46]" or
@@ -1510,8 +1510,8 @@ 
    pcre2pattern man page
    
 the end of a range, so [W-\]46] is interpreted as a class containing a range
 and two other characters. The octal or hexadecimal representation of "]" can
 also be used to end a range.
-
    
-
    
+
    
+
    
 Ranges normally include all code points between the start and end characters,
 inclusive. They can also be used for code points specified numerically, for
 example [\000-\037]. Ranges can include any characters that are valid for the
@@ -1520,23 +1520,23 @@ 
    pcre2pattern man page
    
 explicitly by default (the PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES option disables
 this check). However, ranges such as [\x{d7ff}-\x{e000}], which include the
 surrogates, are always permitted.
-
    
-
    
+
    
+
    
 If a range that includes letters is used when caseless matching is set, it
 matches the letters in either case. For example, [W-c] is equivalent to
 [][\\^_`wxyzabc], matched caselessly, and in a non-UTF mode, if character
 tables for a French locale are in use, [\xc8-\xcb] matches accented E
 characters in both cases.
-
    
-
    
+
    
+
    
 A circumflex can conveniently be used with the upper case character types to
 specify a more restricted set of characters than the matching lower case type.
 For example, the class [^\W_] matches any letter or digit, but not underscore,
 whereas [\w] includes underscore. A positive character class should be read as
 "something OR something OR ..." and a negative class as "NOT something AND NOT
 something AND NOT ...".
-
    
-
    
+
    
+
    
 The metacharacters that are recognized in character classes are backslash,
 hyphen (when it can be interpreted as specifying a range), circumflex
 (only at the start), and the terminating closing square bracket. An opening
@@ -1547,63 +1547,63 @@ 
    pcre2pattern man page
    
 "Compatibility feature for word boundaries"
 below. Escaping any non-alphanumeric character in a class turns it into a
 literal, whether or not it would otherwise be a metacharacter.
-
    
+
    
 
    PERL EXTENDED CHARACTER CLASSES
    
-
    
+
    
 From release 10.45 PCRE2 supports Perl's (?[...]) extended character class
 syntax. This can be used to perform set operations such as intersection on
 character classes.
-
    
-
    
+
    
+
    
 The syntax permitted within (?[...]) is quite different to ordinary character
 classes. Inside the extended class, there is an expression syntax consisting of
 "atoms", operators, and ordinary parentheses "()" used for grouping. Such
 classes always have the Perl /xx modifier (PCRE2 option PCRE2_EXTENDED_MORE)
 turned on within them. This means that literal space and tab characters are
 ignored everywhere in the class.
-
    
-
    
+
    
+
    
 The allowed atoms are individual characters specified by escape sequences such
 as \n or \x{123}, character types such as \d, POSIX classes such as
 [:alpha:], and nested ordinary (non-extended) character classes. For example,
 in (?[\d & [...]]) the nested class [...] follows the usual rules for ordinary
 character classes, in which parentheses are not metacharacters, and character
 literals and ranges are permitted.
-
    
-
    
+
    
+
    
 Character literals and ranges may not appear outside a nested ordinary
 character class because they are not atoms in the extended syntax. The extended
 syntax does not introduce any additional escape sequences, so (?[\y]) is an
 unknown escape, as it would be in [\y].
-
    
-
    
+
    
+
    
 In the extended syntax, ^ does not negate a class (except within an
 ordinary class nested inside an extended class); it is instead a binary
 operator.
-
    
-
    
+
    
+
    
 The binary operators are "&" (intersection), "|" or "+" (union), "-"
 (subtraction) and "^" (symmetric difference). These are left-associative and
 "&" has higher (tighter) precedence, while the others have equal lower
 precedence. The one prefix unary operator is "!" (complement), with highest
 precedence.
-
    
+
    
 
    UTS#18 EXTENDED CHARACTER CLASSES
    
-
    
+
    
 The PCRE2_ALT_EXTENDED_CLASS option enables an alternative to Perl's (?[...])
 syntax, allowing instead extended class behaviour inside ordinary [...]
 character classes. This altered syntax for [...] classes is loosely described
 by the Unicode standard UTS#18. The PCRE2_ALT_EXTENDED_CLASS option does not
 prevent use of (?[...]) classes; it just changes the meaning of all
 [...] classes that are not nested inside a Perl (?[...]) class.
-
    
-
    
+
    
+
    
 Firstly, in ordinary Perl [...] syntax, an expression such as "[a[]" is a
 character class with two literal characters "a" and "[", but in UTS#18 extended
 classes the "[" character becomes an additional metacharacter within classes,
 denoting the start of a nested class, so a literal "[" must be escaped as "\[".
-
    
-
    
+
    
+
    
 Secondly, within the UTS#18 extended syntax, there are operators "||", "&&",
 "--" and "~~" which denote character class union, intersection, subtraction,
 and symmetric difference respectively. In standard Perl syntax, these would
@@ -1613,21 +1613,21 @@ 
    pcre2pattern man page
    
 A literal "-" at the start or end of a range must be escaped, so while "[--1]"
 in Perl syntax is the range from hyphen to "1", it must be escaped as "[\--1]"
 in UTS#18 extended classes.
-
    
-
    
+
    
+
    
 Unlike Perl's (?[...]) extended classes, the PCRE2_EXTENDED_MORE option to
 ignore space and tab characters is not automatically enabled for UTS#18
 extended classes, but it is honoured if set.
-
    
-
    
+
    
+
    
 Extended UTS#18 classes can be nested, and nested classes are themselves
 extended classes (unlike Perl, where nested classes must be simple classes).
 For example, [\p{L}&&[\p{Thai}||\p{Greek}]] matches any letter that is in
 the Thai or Greek scripts. Note that this means that no special grouping
 characters (such as the parentheses used in Perl's (?[...]) class syntax) are
 needed.
-
    
-
    
+
    
+
    
 Individual class items (literal characters, literal ranges, properties such as
 \d or \p{...}, and nested classes) can be combined by juxtaposition or by an
 operator. Juxtaposition is the implicit union operator, and binds more tightly
@@ -1635,13 +1635,13 @@ 
    pcre2pattern man page
    
 as if it is enclosed in square brackets. For example, [A-Z0-9&&[^E8]] is the
 same as [[A-Z0-9]&&[^E8]], which matches any upper case alphanumeric character
 except "E" or "8".
-
    
-
    
+
    
+
    
 Precedence between the explicit operators is not defined, so mixing operators
 is a syntax error. For example, [A&&B--C] is an error, but [A&&[B--C]] is
 valid.
-
    
-
    
+
    
+
    
 This is an emerging syntax which is being adopted gradually across the regex
 ecosystem: for example JavaScript adopted the "/v" flag in ECMAScript 2024;
 Python's "re" module reserves the syntax for future use with a FutureWarning
@@ -1650,16 +1650,16 @@ 
    pcre2pattern man page
    
 Rust's "regex" crate and Python's "regex" PyPi module both implement UTS#18
 extended classes, but with slight incompatibilities ([A||B&&C] is parsed as
 [A||[B&&C]] in Python's "regex" but as [[A||B]&&C] in Rust's "regex").
-
    
-
    
+
    
+
    
 PCRE2's syntax adds syntax restrictions similar to ECMASCript's /v flag, so
 that all the UTS#18 extended classes accepted as valid by PCRE2 have the
 property that they are interpreted either with the same behaviour, or as
 invalid, by all other major engines. Please file an issue if you are aware of
 cross-engine differences in behaviour between PCRE2 and another major engine.
-
    
+
    
 
    POSIX CHARACTER CLASSES
    
-
    
+
    
 Perl supports the POSIX notation for character classes. This uses names
 enclosed by [: and :] within the enclosing square brackets. PCRE2 also supports
 this notation, in both ordinary and extended classes. For example,
@@ -1688,8 +1688,8 @@ 
    pcre2pattern man page
    
 and space (32). If locale-specific matching is taking place, the list of space
 characters may be different; there may be fewer or more of them. "Space" and
 \s match the same set of characters, as do "word" and \w.
-
    
-
    
+
    
+
    
 The name "word" is a Perl extension, and "blank" is a GNU extension from Perl
 5.8. Another Perl extension is negation, which is indicated by a ^ character
 after the colon. For example,
@@ -1699,8 +1699,8 @@ 
    pcre2pattern man page
    
 matches "1", "2", or any non-digit. PCRE2 (and Perl) also recognize the POSIX
 syntax [.ch.] and [=ch=] where "ch" is a "collating element", but these are not
 supported, and an error is given if they are encountered.
-
    
-
    
+
    
+
    
 By default, characters with values greater than 127 do not match any of the
 POSIX character classes, although this may be different for characters in the
 range 128-255 when locale-specific matching is happening. However, in UCP mode,
@@ -1720,8 +1720,8 @@ 
    pcre2pattern man page
    
 
    
 Negated versions, such as [:^alpha:] use \P instead of \p. Four other POSIX
 classes are handled specially in UCP mode:
-
    
-
    
+
    
+
    
 [:graph:]
 This matches characters that have glyphs that mark the page when printed. In
 Unicode property terms, it matches all characters with the L, M, N, P, S, or Cf
@@ -1731,39 +1731,39 @@ 
    pcre2pattern man page
    
   U+180E           Mongolian Vowel Separator
   U+2066 - U+2069  Various "isolate"s
 
-
    
-
    
-
    
+
    • 
+
    
+
    
 [:print:]
 This matches the same characters as [:graph:] plus space characters that are
 not controls, that is, characters with the Zs property.
-
    
-
    
+
    
+
    
 [:punct:]
 This matches all characters that have the Unicode P (punctuation) property,
 plus those characters with code points less than 256 that have the S (Symbol)
 property.
-
    
-
    
+
    
+
    
 [:xdigit:]
 In addition to the ASCII hexadecimal digits, this also matches the "fullwidth"
 versions of those characters, whose Unicode code points start at U+FF10. This
 is a change that was made in PCRE2 release 10.43 for Perl compatibility.
-
    
-
    
+
    
+
    
 The other POSIX classes are unchanged by PCRE2_UCP, and match only characters
 with code points less than 256.
-
    
-
    
+
    
+
    
 There are two options that can be used to restrict the POSIX classes to ASCII
 characters when PCRE2_UCP is set. The option PCRE2_EXTRA_ASCII_DIGIT affects
 just [:digit:] and [:xdigit:]. Within a pattern, this can be set and unset by
 (?aT) and (?-aT). The PCRE2_EXTRA_ASCII_POSIX option disables UCP processing
 for all POSIX classes, including [:digit:] and [:xdigit:]. Within a pattern,
 (?aP) and (?-aP) set and unset both these options for consistency.
-
    
+
    
 
    COMPATIBILITY FEATURE FOR WORD BOUNDARIES
    
-
    
+
    
 In the POSIX.2 compliant library that was included in 4.4BSD Unix, the ugly
 syntax [[:<:]] and [[:>:]] is used for matching "start of word" and "end of
 word". PCRE2 treats these items as follows:
@@ -1782,9 +1782,9 @@ 
    pcre2pattern man page
    
 used above in order to give exactly the POSIX behaviour. Note also that the
 PCRE2_UCP option changes the meaning of \w (and therefore \b) by default, so
 it also affects these POSIX sequences.
-
    
+
    
 
    VERTICAL BAR
    
-
    
+
    
 Vertical bar characters are used to separate alternative patterns. For example,
 the pattern
 
    @@ -1797,9 +1797,9 @@ 
    pcre2pattern man page
    
 (defined below),
 "succeeds" means matching the rest of the main pattern as well as the
 alternative in the group.
-
    
+
    
 
    INTERNAL OPTION SETTING
    
-
    
+
    
 The settings of several options can be changed within a pattern by a sequence
 of letters enclosed between "(?" and ")". The following are Perl-compatible,
 and are described in detail in the
@@ -1817,20 +1817,20 @@ 
    pcre2pattern man page
    
 unset these options by preceding the relevant letters with a hyphen, for
 example (?-im). The two "extended" options are not independent; unsetting
 either one cancels the effects of both of them.
-
    
-
    
+
    
+
    
 A combined setting and unsetting such as (?im-sx), which sets PCRE2_CASELESS
 and PCRE2_MULTILINE while unsetting PCRE2_DOTALL and PCRE2_EXTENDED, is also
 permitted. Only one hyphen may appear in the options string. If a letter
 appears both before and after the hyphen, the option is unset. An empty options
 setting "(?)" is allowed. Needless to say, it has no effect.
-
    
-
    
+
    
+
    
 If the first character following (? is a circumflex, it causes all of the above
 options to be unset. Letters may follow the circumflex to cause some options to
 be re-instated, but a hyphen may not appear.
-
    
-
    
+
    
+
    
 Some PCRE2-specific options can be changed by the same mechanism using these
 pairs or individual letters:
 
    @@ -1846,13 +1846,13 @@ 
    pcre2pattern man page
    
 However, except for 'r', these are not unset by (?^), which is equivalent to
 (?-imnrsx). If 'a' is not followed by any of the upper case letters shown
 above, it sets (or unsets) all the ASCII options.
-
    
-
    
+
    
+
    
 PCRE2_EXTRA_ASCII_DIGIT has no additional effect when PCRE2_EXTRA_ASCII_POSIX
 is set, but including it in (?aP) means that (?-aP) suppresses all ASCII
 restrictions for POSIX classes.
-
    
-
    
+
    
+
    
 When one of these option changes occurs at top level (that is, not inside group
 parentheses), the change applies until a subsequent change, or the end of the
 pattern. An option change within a group (see below for a description of
@@ -1872,8 +1872,8 @@ 
    pcre2pattern man page
    
 branch is abandoned before the option setting. This is because the effects of
 option settings happen at compile time. There would be some very weird
 behaviour otherwise.
-
    
-
    
+
    
+
    
 As a convenient shorthand, if any option settings are required at the start of
 a non-capturing group (see the next section), the option letters may
 appear between the "?" and the ":". Thus the two patterns
@@ -1882,8 +1882,8 @@ 
    pcre2pattern man page
    
   (?:(?i)saturday|sunday)
 
    
 match exactly the same set of strings.
-
    
-
    
+
    
+
    
 Note: There are other PCRE2-specific options, applying to the whole
 pattern, which can be set by the application when the compiling function is
 called. In addition, the pattern can contain special leading sequences such as
@@ -1895,9 +1895,9 @@ 
    pcre2pattern man page
    
 PCRE2_UTF and PCRE2_UCP options, respectively. However, the application can set
 the PCRE2_NEVER_UTF or PCRE2_NEVER_UCP options, which lock out the use of the
 (*UTF) and (*UCP) sequences.
-
    
+
    
 
    GROUPS
    
-
    
+
    
 Groups are delimited by parentheses (round brackets), which can be nested.
 Turning part of a pattern into a group does two things:
 
    
@@ -1915,8 +1915,8 @@ 
    pcre2pattern man page
    
 back to the caller, separately from the portion that matched the whole pattern.
 (This applies only to the traditional matching function; the DFA matching
 function does not support capturing.)
-
    
-
    
+
    
+
    
 Opening parentheses are counted from left to right (starting from 1) to obtain
 numbers for capture groups. For example, if the string "the red king" is
 matched against the pattern
@@ -1925,8 +1925,8 @@ 
    pcre2pattern man page
    
 
    
 the captured substrings are "red king", "red", and "king", and are numbered 1,
 2, and 3, respectively.
-
    
-
    
+
    
+
    
 The fact that plain parentheses fulfil two functions is not always helpful.
 There are often times when grouping is required without capturing. If an
 opening parenthesis is followed by a question mark and a colon, the group
@@ -1938,8 +1938,8 @@ 
    pcre2pattern man page
    
 
    • 
 the captured substrings are "white queen" and "queen", and are numbered 1 and
 2. The maximum number of capture groups is 65535.
-
    
-
    
+
    
+
    
 As a convenient shorthand, if any option settings are required at the start of
 a non-capturing group, the option letters may appear between the "?" and the
 ":". Thus the two patterns
@@ -1951,9 +1951,9 @@ 
    pcre2pattern man page
    
 from left to right, and options are not reset until the end of the group is
 reached, an option setting in one branch does affect subsequent branches, so
 the above patterns match "SUNDAY" as well as "Saturday".
-
    
+
    
 
    DUPLICATE GROUP NUMBERS
    
-
    
+
    
 Perl 5.10 introduced a feature whereby each alternative in a group uses the
 same numbers for its capturing parentheses. Such a group starts with (?| and is
 itself a non-capturing group. For example, consider this pattern:
@@ -1987,27 +1987,27 @@ 
    pcre2pattern man page
    A relative reference such as (?-1) is no different: it is just a convenient way of computing an absolute group number. -

    -

    +

    +

    If a condition test for a group's having matched refers to a non-unique number, the test is true if any group with that number has matched. -

    -

    +

    +

    An alternative approach to using this "branch reset" feature is to use duplicate named groups, as described in the next section. -

    +


    NAMED CAPTURE GROUPS
    -

    +

    Identifying capture groups by number is simple, but it can be very hard to keep track of the numbers in complicated patterns. Furthermore, if an expression is modified, the numbers may change. To help with this difficulty, PCRE2 supports the naming of capture groups. This feature was not added to Perl until release 5.10. Python had the feature earlier, and PCRE1 introduced it at release 4.0, using the Python syntax. PCRE2 supports both the Perl and the Python syntax. -

    -

    +

    +

    In PCRE2, a capture group can be named in one of three ways: (?<name>...) or (?'name'...) as in Perl, or (?P<name>...) as in Python. Names may be up to 128 code units long. When PCRE2_UTF is not set, they may contain only ASCII @@ -2025,16 +2025,16 @@

    pcre2pattern man page

    and conditions, can all be made by name as well as by number. -

    -

    +

    +

    Named capture groups are allocated numbers as well as names, exactly as if the names were not present. In both PCRE2 and Perl, capture groups are primarily identified by numbers; any names are just aliases for these numbers. The PCRE2 API provides function calls for extracting the complete name-to-number translation table from a compiled pattern, as well as convenience functions for extracting captured substrings by name. -

    -

    +

    +

    Warning: When more than one capture group has the same number, as described in the previous section, a name given to one of them applies to all of them. Perl allows identically numbered groups to have different names. @@ -2044,8 +2044,8 @@

    pcre2pattern man page

    Perl allows this, with both names AA and BB as aliases of group 1. Thus, after a successful match, both names yield the same value (either "aa" or "bb"). -

    -

    +

    +

    In an attempt to reduce confusion, PCRE2 does not allow the same group number to be associated with more than one name. The example above provokes a compile-time error. However, there is still scope for confusion. Consider this @@ -2056,8 +2056,8 @@

    pcre2pattern man page

    Although the second group number 1 is not explicitly named, the name AA is still an alias for any group 1. Whether the pattern matches "aa" or "bb", a reference by name to group AA yields the matched string. -

    -

    +

    +

    By default, a name must be unique within a pattern, except that duplicate names are permitted for groups with the same number, for example: 

    @@ -2068,8 +2068,8 @@ 
    pcre2pattern man page
    
 in the section entitled
 "Internal Option Setting"
 above.
-
    
-
    
+
    
+
    
 Duplicate names can be useful for patterns where only one instance of the named
 capture group can match. Suppose you want to match the name of a weekday,
 either as a 3-letter abbreviation or as the full name, and in both cases you
@@ -2089,8 +2089,8 @@ 
    pcre2pattern man page
    
 saves searching to find which numbered group it was. (An alternative way of
 solving this problem is to use a "branch reset" group, as described in the
 previous section.)
-
    
-
    
+
    
+
    
 If you make a backreference to a non-unique named group from elsewhere in the
 pattern, the groups to which the name refers are checked in the order in which
 they appear in the overall pattern. The first one that is set is used for the
@@ -2099,14 +2099,14 @@ 
    pcre2pattern man page
    
 
       (?J)(?:(?<n>foo)|(?<n>bar))\k<n>
 
-
    
-
    
-
    
+
    +

    +

    If you make a subroutine call to a non-unique named group, the one that corresponds to the first occurrence of the name is used. In the absence of duplicate numbers this is the one with the lowest number. -

    -

    +

    +

    If you use a named reference in a condition test (see the section about conditions @@ -2117,9 +2117,9 @@

    pcre2pattern man page

    capture groups, see the pcre2api documentation. -

    +


    REPETITION
    -

    +

    Repetition is specified by quantifiers, which may follow any one of these items: 

    @@ -2161,24 +2161,24 @@ 
    pcre2pattern man page
    
 This is a change in behaviour that happened in Perl 5.34.0 and PCRE2 10.43. In
 earlier versions such a sequence was not interpreted as a quantifier. Other
 regular expression engines may behave either way.
-
    
-
    
+
    
+
    
 If the characters that follow an opening brace do not match the syntax of a
 quantifier, the brace is taken as a literal character. In particular, this
 means that {,} is a literal string of three characters.
-
    
-
    
+
    
+
    
 Note that not every opening brace is potentially the start of a quantifier
 because braces are used in other items such as \N{U+345} or \k{name}.
-
    
-
    
+
    
+
    
 In UTF modes, quantifiers apply to characters rather than to individual code
 units. Thus, for example, \x{100}{2} matches two characters, each of
 which is represented by a two-byte sequence in a UTF-8 string. Similarly,
 \X{3} matches three Unicode extended grapheme clusters, each of which may be
 several code units long (and they may be of different lengths).
-
    
-
    
+
    
+
    
 The quantifier {0} is permitted, causing the expression to behave as if the
 previous item and the quantifier were not present. This may be useful for
 capture groups that are referenced as
@@ -2187,8 +2187,8 @@ 
    pcre2pattern man page
    
 "Defining capture groups for use by reference only"
 below). Except for parenthesized groups, items that have a {0} quantifier are
 omitted from the compiled pattern.
-
    
-
    
+
    
+
    
 For convenience, the three most common quantifiers have single-character
 abbreviations:
 
    @@ -2207,8 +2207,8 @@ 
    pcre2pattern man page
    
 characters, matching moves on to the next item in the pattern instead of
 repeatedly matching an empty string. This does not prevent backtracking into
 any of the iterations if a subsequent item fails to match.
-
    
-
    
+
    
+
    
 By default, quantifiers are "greedy", that is, they match as much as possible
 (up to the maximum number of permitted repetitions), without causing the rest
 of the pattern to fail. The classic example of where this gives problems is in
@@ -2238,32 +2238,32 @@ 
    pcre2pattern man page
    
 
    
 which matches one digit by preference, but can match two if that is the only
 way the rest of the pattern matches.
-
    
-
    
+
    
+
    
 If the PCRE2_UNGREEDY option is set (an option that is not available in Perl),
 the quantifiers are not greedy by default, but individual ones can be made
 greedy by following them with a question mark. In other words, it inverts the
 default behaviour.
-
    
-
    
+
    
+
    
 When a parenthesized group is quantified with a minimum repeat count that
 is greater than 1 or with a limited maximum, more memory is required for the
 compiled pattern, in proportion to the size of the minimum or maximum.
-
    
-
    
+
    
+
    
 If a pattern starts with .* or .{0,} and the PCRE2_DOTALL option (equivalent
 to Perl's /s) is set, thus allowing the dot to match newlines, the pattern is
 implicitly anchored, because whatever follows will be tried against every
 character position in the subject string, so there is no point in retrying the
 overall match at any position after the first. PCRE2 normally treats such a
 pattern as though it were preceded by \A.
-
    
-
    
+
    
+
    
 In cases where it is known that the subject string contains no newlines, it is
 worth setting PCRE2_DOTALL in order to obtain this optimization, or
 alternatively, using ^ to indicate anchoring explicitly.
-
    
-
    
+
    
+
    
 However, there are some cases where the optimization cannot be used. When .*
 is inside capturing parentheses that are the subject of a backreference
 elsewhere in the pattern, a match at the start may fail where a later one
@@ -2273,8 +2273,8 @@ 
    pcre2pattern man page
    If the subject is "xyz123abc123" the match point is the fourth character. For this reason, such a pattern is not implicitly anchored. -

    -

    +

    +

    Another case where implicit anchoring is not applied is when the leading .* is inside an atomic group. Once again, a match at the start may fail where a later one succeeds. Consider this pattern: @@ -2285,8 +2285,8 @@

    pcre2pattern man page

    (*PRUNE) and (*SKIP) also disable this optimization. To do so explicitly, either pass the compile option PCRE2_NO_DOTSTAR_ANCHOR, or call pcre2_set_optimize() with a PCRE2_DOTSTAR_ANCHOR_OFF directive. -

    -

    +

    +

    When a capture group is repeated, the value captured is the substring that matched the final iteration. For example, after 

    @@ -2299,17 +2299,17 @@ 
    pcre2pattern man page
    
   (a|(b))+
    matches "aba" the value of the second captured substring is "b". -

    +


    ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS
    -

    +

    With both maximizing ("greedy") and minimizing ("ungreedy" or "lazy") repetition, failure of what follows normally causes the repeated item to be re-evaluated to see if a different number of repeats allows the rest of the pattern to match. Sometimes it is useful to prevent this, either to change the nature of the match, or to cause it fail earlier than it otherwise might, when the author of the pattern knows there is no point in carrying on. -

    -

    +

    +

    Consider, for example, the pattern \d+foo when applied to the subject line 

       123456bar
@@ -2319,8 +2319,8 @@ 
    pcre2pattern man page
    
 item, and then with 4, and so on, before ultimately failing. "Atomic grouping"
 (a term taken from Jeffrey Friedl's book) provides the means for specifying
 that once a group has matched, it is not to be re-evaluated in this way.
-
    
-
    
+
    
+
    
 If we use atomic grouping for the previous example, the matcher gives up
 immediately on failing to match "foo" the first time. The notation is a kind of
 special parenthesis, starting with (?> as in this example:
@@ -2336,20 +2336,20 @@ 
    pcre2pattern man page
    
 once it has matched, and a failure further into the pattern is prevented from
 backtracking into it. Backtracking past it to previous items, however, works as
 normal.
-
    
-
    
+
    
+
    
 An alternative description is that a group of this type matches exactly the
 string of characters that an identical standalone pattern would match, if
 anchored at the current point in the subject string.
-
    
-
    
+
    
+
    
 Atomic groups are not capture groups. Simple cases such as the above example
 can be thought of as a maximizing repeat that must swallow everything it can.
 So, while both \d+ and \d+? are prepared to adjust the number of digits they
 match in order to make the rest of the pattern match, (?>\d+) can only match
 an entire sequence of digits.
-
    
-
    
+
    
+
    
 Atomic groups in general can of course contain arbitrarily complicated
 expressions, and can be nested. However, when the contents of an atomic
 group is just a single repeated item, as in the example above, a simpler
@@ -2369,23 +2369,23 @@ 
    pcre2pattern man page
    
 atomic group. However, there is no difference in the meaning of a possessive
 quantifier and the equivalent atomic group, though there may be a performance
 difference; possessive quantifiers should be slightly faster.
-
    
-
    
+
    
+
    
 The possessive quantifier syntax is an extension to the Perl 5.8 syntax.
 Jeffrey Friedl originated the idea (and the name) in the first edition of his
 book. Mike McCloskey liked it, so implemented it when he built Sun's Java
 package, and PCRE1 copied it from there. It found its way into Perl at release
 5.10.
-
    
-
    
+
    
+
    
 PCRE2 has an optimization that automatically "possessifies" certain simple
 pattern constructs. For example, the sequence A+B is treated as A++B because
 there is no point in backtracking into a sequence of A's when B must follow.
 This feature can be disabled by the PCRE2_NO_AUTO_POSSESS option, by calling
 pcre2_set_optimize() with a PCRE2_AUTO_POSSESS_OFF directive, or by
 starting the pattern with (*NO_AUTO_POSSESS).
-
    
-
    
+
    
+
    
 When a pattern contains an unlimited repeat inside a group that can itself be
 repeated an unlimited number of times, the use of an atomic group is the only
 way to avoid some failing matches taking a very long time indeed. The pattern
@@ -2410,23 +2410,23 @@ 
    pcre2pattern man page
    
   ((?>\D+)|<\d+>)*[!?]
    sequences of non-digits cannot be broken, and failure happens quickly. -

    +


    BACKREFERENCES
    -

    +

    Outside a character class, a backslash followed by a digit greater than 0 (and possibly further digits) is a backreference to a capture group earlier (that is, to its left) in the pattern, provided there have been that many previous capture groups. -

    -

    +

    +

    However, if the decimal number following the backslash is less than 8, it is always taken as a backreference, and causes an error only if there are not that many capture groups in the entire pattern. In other words, the group that is referenced need not be to the left of the reference for numbers less than 8. A "forward backreference" of this type can make sense when a repetition is involved and the group to the right has participated in an earlier iteration. -

    -

    +

    +

    It is not possible to have a numerical "forward backreference" to a group whose number is 8 or more using this syntax because a sequence such as \50 is interpreted as a character defined in octal. See the subsection entitled @@ -2435,8 +2435,8 @@

    pcre2pattern man page

    for further details of the handling of digits following a backslash. Other forms of backreferencing do not suffer from this restriction. In particular, there is no problem when named capture groups are used (see below). -

    -

    +

    +

    Another way of avoiding the ambiguity inherent in the use of digits following a backslash is to use the \g escape sequence. This escape must be followed by a signed or unsigned number, optionally enclosed in braces. These examples are @@ -2464,14 +2464,14 @@

    pcre2pattern man page

    The use of relative references can be helpful in long patterns, and also in patterns that are created by joining together fragments that contain references within themselves. -

    -

    +

    +

    The sequence \g{+1} is a reference to the next capture group that is started after this item, and \g{+2} refers to the one after that, and so on. This kind of forward reference can be useful in patterns that repeat. Perl does not support the use of + in this way. -

    -

    +

    +

    A backreference matches whatever actually most recently matched the capture group in the current subject string, rather than anything at all that matches the group (see @@ -2488,8 +2488,8 @@

    pcre2pattern man page

    matches "rah rah" and "RAH RAH", but not "RAH rah", even though the original capture group is matched caselessly. -

    -

    +

    +

    There are several different ways of writing backreferences to named capture groups. The .NET syntax is \k{name}, the Python syntax is (?=name), and the original Perl syntax is \k<name> or \k'name'. All of these are now supported @@ -2504,8 +2504,8 @@

    pcre2pattern man page

    A capture group that is referenced by name may appear in the pattern before or after the reference. -

    -

    +

    +

    There may be more than one backreference to the same group. If a group has not actually been used in a particular match, backreferences to it always fail by default. For example, the pattern @@ -2515,8 +2515,8 @@

    pcre2pattern man page

    always fails if it starts to match "a" rather than "bc". However, if the PCRE2_MATCH_UNSET_BACKREF option is set at compile time, a backreference to an unset value matches an empty string. -

    -

    +

    +

    Because there may be many capture groups in a pattern, all digits following a backslash are taken as part of a potential backreference number. If the pattern continues with a digit character, some delimiter must be used to terminate the @@ -2524,11 +2524,11 @@

    pcre2pattern man page

    can be white space. Otherwise, the \g{} syntax or an empty comment (see "Comments" below) can be used. -

    +


    Recursive backreferences
    -

    +

    A backreference that occurs inside the group to which it refers fails when the group is first used, so, for example, (a\1) never matches. However, such references can be useful inside repeated groups. For example, the pattern @@ -2541,70 +2541,70 @@

    pcre2pattern man page

    the first iteration does not need to match the backreference. This can be done using alternation, as in the example above, or by a quantifier with a minimum of zero. -

    -

    +

    +

    For versions of PCRE2 less than 10.25, backreferences of this type used to cause the group that they reference to be treated as an atomic group. This restriction no longer applies, and backtracking into such groups can occur as normal. -

    +


    ASSERTIONS
    -

    +

    An assertion is a test that does not consume any characters. The test must succeed for the match to continue. The simple assertions coded as \b, \B, \A, \G, \Z, \z, ^ and $ are described above. -

    -

    +

    +

    More complicated assertions are coded as parenthesized groups. If matching such a group succeeds, matching continues after it, but with the matching position in the subject string reset to what it was before the assertion was processed. -

    -

    +

    +

    A special kind of assertion, called a "scan substring" assertion, matches a subpattern against a previously captured substring. This is described in the section entitled "Scan substring assertions" below. It is a PCRE2 extension, not compatible with Perl. -

    -

    +

    +

    The other goup-based assertions are of two kinds: those that look ahead of the current position in the subject string, and those that look behind it, and in each case an assertion may be positive (must match for the assertion to be true) or negative (must not match for the assertion to be true). -

    -

    +

    +

    The Perl-compatible lookaround assertions are atomic. If an assertion is true, but there is a subsequent matching failure, there is no backtracking into the assertion. However, there are some cases where non-atomic assertions can be useful. PCRE2 has some support for these, described in the section entitled "Non-atomic assertions" below, but they are not Perl-compatible. -

    -

    +

    +

    A lookaround assertion may appear as the condition in a conditional group (see below). In this case, the result of matching the assertion determines which branch of the condition is followed. -

    -

    +

    +

    Assertion groups are not capture groups. If an assertion contains capture groups within it, these are counted for the purposes of numbering the capture groups in the whole pattern. Within each branch of an assertion, locally captured substrings may be referenced in the usual way. For example, a sequence such as (.)\g{-1} can be used to check that two adjacent characters are the same. -

    -

    +

    +

    When a branch within an assertion fails to match, any substrings that were captured are discarded (as happens with any pattern branch that fails to match). A negative assertion is true only when all its branches fail to match; this means that no captured substrings are ever retained after a successful negative assertion. When an assertion contains a matching branch, what happens depends on the type of assertion. -

    -

    +

    +

    For a positive assertion, internally captured substrings in the successful branch are retained, and matching continues with the next pattern item after the assertion. For a negative assertion, a matching branch means that the @@ -2614,8 +2614,8 @@

    pcre2pattern man page

    the "no" branch of the condition. For other failing negative assertions, control passes to the previous backtracking point, thus discarding any captured strings within the assertion. -

    -

    +

    +

    Most assertion groups may be repeated; though it makes no sense to assert the same thing several times, the side effect of capturing in positive assertions may occasionally be useful. However, an assertion that forms the condition for @@ -2623,11 +2623,11 @@

    pcre2pattern man page

    repetition of assertions, but from release 10.35 the only restriction is that an unlimited maximum repetition is changed to be one more than the minimum. For example, {3,} is treated as {3,4}. -

    +


    Alphabetic assertion names
    -

    +

    Traditionally, symbolic sequences such as (?= and (?<= have been used to specify lookaround assertions. Perl 5.28 introduced some experimental alphabetic alternatives which might be easier to remember. They all start with @@ -2642,11 +2642,11 @@

    pcre2pattern man page

    For example, (*pla:foo) is the same assertion as (?=foo). In the following sections, the various assertions are described using the original symbolic forms. -

    +


    Lookahead assertions
    -

    +

    Lookahead assertions start with (?= for positive assertions and (?! for negative assertions. For example, 

    @@ -2666,17 +2666,17 @@ 
    pcre2pattern man page
    
 "foo"; it finds any occurrence of "bar" whatsoever, because the assertion
 (?!foo) is always true when the next three characters are "bar". A
 lookbehind assertion is needed to achieve the other effect.
-
    
-
    
+
    
+
    
 If you want to force a matching failure at some point in a pattern, the most
 convenient way to do it is with (?!) because an empty string always matches, so
 an assertion that requires there not to be an empty string must always fail.
 The backtracking control verb (*FAIL) or (*F) is a synonym for (?!).
-
    
+
    
 
    
 Lookbehind assertions
 
    
-
    
+
    
 Lookbehind assertions start with (?<= for positive assertions and (?<! for
 negative assertions. For example,
 
    @@ -2685,8 +2685,8 @@ 
    pcre2pattern man page
    
 does find an occurrence of "bar" that is not preceded by "foo". The contents of
 a lookbehind assertion are restricted such that there must be a known maximum
 to the lengths of all the strings it matches. There are two cases:
-
    
-
    
+
    
+
    
 If every top-level alternative matches a fixed length, for example
 
       (?<=colour|color)
@@ -2695,8 +2695,8 @@ 
    pcre2pattern man page
    
 the same, as this example demonstrates. This is the only kind of lookbehind
 supported by PCRE2 versions earlier than 10.43 and by the alternative matching
 function pcre2_dfa_match().
-
    
-
    
+
    
+
    
 In PCRE2 10.43 and later, pcre2_match() supports lookbehind assertions in
 which one or more top-level alternatives can match more than one string length,
 for example
@@ -2709,23 +2709,23 @@ 
    pcre2pattern man page
    
 (see above)
 can be used instead of a lookbehind assertion at the start of a pattern to get
 round the length limit restriction.
-
    
-
    
+
    
+
    
 In UTF-8 and UTF-16 modes, PCRE2 does not allow the \C escape (which matches a
 single code unit even in a UTF mode) to appear in lookbehind assertions,
 because it makes it impossible to calculate the length of the lookbehind. The
 \X and \R escapes, which can match different numbers of code units, are never
 permitted in lookbehinds.
-
    
-
    
+
    
+
    
 "Subroutine"
 calls (see below) such as (?2) or (?&X) are permitted in lookbehinds, as long
 as the called capture group matches a limited-length string. However,
 recursion,
 that is, a "subroutine" call into a group that is already active,
 is not supported.
-
    
-
    
+
    
+
    
 PCRE2 supports backreferences in lookbehinds, but only if certain conditions
 are met. The PCRE2_MATCH_UNSET_BACKREF option must not be set, there must be no
 use of (?| in the pattern (it creates duplicate group numbers), and if the
@@ -2735,9 +2735,9 @@ 
    pcre2pattern man page
    
 same character:
 
        \b(\w)\w++(?<=\1)
-
    
-
    
-
    
+
    
+
    
+
    
 Possessive quantifiers can be used in conjunction with lookbehind assertions to
 specify efficient matching at the end of subject strings. Consider a simple
 pattern such as
@@ -2763,11 +2763,11 @@ 
    pcre2pattern man page
    
 assertion does a single test on the last four characters. If it fails, the
 match fails immediately. For long strings, this approach makes a significant
 difference to the processing time.
-
    
+
    
 
    
 Using multiple assertions
 
    
-
    
+
    
 Several assertions (of any sort) may occur in succession. For example,
 
       (?<=\d{3})(?<!999)foo
@@ -2785,8 +2785,8 @@ 
    pcre2pattern man page
    
 This time the first assertion looks at the preceding six characters, checking
 that the first three are digits, and then the second assertion checks that the
 preceding three characters are not "999".
-
    
-
    
+
    
+
    
 Assertions can be nested in any combination. For example,
 
       (?<=(?<!foo)bar)baz
@@ -2798,9 +2798,9 @@ 
    pcre2pattern man page
    
 
    
 is another pattern that matches "foo" preceded by three digits and any three
 characters that are not "999".
-
    
+
    
 
    NON-ATOMIC ASSERTIONS
    
-
    
+
    
 Traditional lookaround assertions are atomic. That is, if an assertion is true,
 but there is a subsequent matching failure, there is no backtracking into the
 assertion. However, there are some cases where non-atomic positive assertions
@@ -2822,8 +2822,8 @@ 
    pcre2pattern man page
    
 string, but then has to backtrack until the rest of the assertion can match a
 word, which is captured by group 1. In other words, when the assertion first
 succeeds, it captures the right-most word in the string.
-
    
-
    
+
    
+
    
 The current matching point is then reset to the start of the subject, and the
 rest of the pattern match checks for two occurrences of the captured word,
 using an ungreedy .*? to scan from the left. If this succeeds, we are done, but
@@ -2831,42 +2831,42 @@ 
    pcre2pattern man page
    
 fails. If a traditional atomic lookahead (?= or (*pla: had been used, the
 assertion could not be re-entered, and the whole match would fail. The pattern
 would succeed only if the very last word in the subject was found twice.
-
    
-
    
+
    
+
    
 Using a non-atomic lookahead, however, means that when the last word does not
 occur twice in the string, the lookahead can backtrack and find the second-last
 word, and so on, until either the match succeeds, or all words have been
 tested.
-
    
-
    
+
    
+
    
 Two conditions must be met for a non-atomic assertion to be useful: the
 contents of one or more capturing groups must change after a backtrack into the
 assertion, and there must be a backreference to a changed group later in the
 pattern. If this is not the case, the rest of the pattern match fails exactly
 as before because nothing has changed, so using a non-atomic assertion just
 wastes resources.
-
    
-
    
+
    
+
    
 There is one exception to backtracking into a non-atomic assertion. If an
 (*ACCEPT) control verb is triggered, the assertion succeeds atomically. That
 is, a subsequent match failure cannot backtrack into the assertion.
-
    
-
    
+
    
+
    
 Non-atomic assertions are not supported by the alternative matching function
 pcre2_dfa_match(). They are supported by JIT, but only if they do not
 contain any control verbs such as (*ACCEPT). (This may change in future). Note
 that assertions that appear as conditions for
 conditional groups
 (see below) must be atomic.
-
    
+
    
 
    SCAN SUBSTRING ASSERTIONS
    
-
    
+
    
 A special kind of assertion, not compatible with Perl, makes it possible to
 check the contents of a captured substring by matching it with a subpattern.
 Because this involves capturing, this feature is not supported by
 pcre2_dfa_match().
-
    
-
    
+
    
+
    
 A scan substring assertion starts with the sequence (*scan_substring: or
 (*scs: which is followed by a list of substring numbers (absolute or relative)
 and/or substring names enclosed in single quotes or angle brackets, all within
@@ -2883,8 +2883,8 @@ 
    pcre2pattern man page
    
 PCRE2_DUPNAMES is set and there are ambiguous group names, all groups with the
 same name are checked in numerical order. A scan substring assertion fails if
 none of the groups it references have been set.
-
    
-
    
+
    
+
    
 The pattern match on the substring is always anchored, that is, it must match
 from the start of the substring. There is no "bumpalong" if it does not match
 at the start. The end of the subject is temporarily reset to be the end of the
@@ -2892,8 +2892,8 @@ 
    pcre2pattern man page
    
 subject is not reset. This means that ^ matches only if the substring is
 actually at the start of the main subject, but it also means that lookbehind
 assertions into what precedes the substring are possible.
-
    
-
    
+
    
+
    
 Here is a very simple example: find a word that contains the rare (in English)
 sequence of letters "rh" not at the start:
 
    @@ -2917,9 +2917,9 @@ 
    pcre2pattern man page
    
 Within a substring scanning subpattern, references to other groups work as
 normal. Capturing groups may appear, and will retain their values during
 ongoing matching if the assertion succeeds.
-
    
+
    
 
    SCRIPT RUNS
    
-
    
+
    
 In concept, a script run is a sequence of characters that are all from the same
 Unicode script such as Latin or Greek. However, because some scripts are
 commonly used together, and because some diacritical and other marks are used
@@ -2929,8 +2929,8 @@ 
    pcre2pattern man page
    
 in the
 pcre2unicode
 documentation.
-
    
-
    
+
    
+
    
 If part of a pattern is enclosed between (*script_run: or (*sr: and a closing
 parenthesis, it fails if the sequence of characters that it matches are not a
 script run. After a failure, normal backtracking occurs. Script runs can be
@@ -2954,9 +2954,9 @@ 
    pcre2pattern man page
    
 
       \s+(?=[0-9_.]*\p{Latin})(*sr:\S+)
 
-
    
-
    
-
    
+
    
+
    
+
    
 In many cases, backtracking into a script run pattern fragment is not
 desirable. The script run can employ an atomic group to prevent this. Because
 this is a common requirement, a shorthand notation is provided by
@@ -2966,22 +2966,22 @@ 
    pcre2pattern man page
    
 
    
 Note that the atomic group is inside the script run. Putting it outside would
 not prevent backtracking into the script run pattern.
-
    
-
    
+
    
+
    
 Support for script runs is not available if PCRE2 is compiled without Unicode
 support. A compile-time error is given if any of the above constructs is
 encountered. Script runs are not supported by the alternate matching function,
 pcre2_dfa_match() because they use the same mechanism as capturing
 parentheses.
-
    
-
    
+
    
+
    
 Warning: The (*ACCEPT) control verb
 (see below)
 should not be used within a script run group, because it causes an immediate
 exit from the group, bypassing the script run checking.
-
    
+
    
 
    CONDITIONAL GROUPS
    
-
    
+
    
 It is possible to cause the matching process to obey a pattern fragment
 conditionally or to choose between two alternative fragments, depending on
 the result of an assertion, or whether a specific capture group has
@@ -3000,16 +3000,16 @@ 
    pcre2pattern man page
    
 
       (?(1) (A|B|C) | (D | (?(2)E|F) | E) )
 
-
    
-
    
-
    
+
    
+
    
+
    
 There are five kinds of condition: references to capture groups, references to
 recursion, two pseudo-conditions called DEFINE and VERSION, and assertions.
-
    
+
    
 
    
 Checking for a used capture group by number
 
    
-
    
+
    
 If the text between the parentheses consists of a sequence of digits, the
 condition is true if a capture group of that number has previously matched. If
 there is more than one capture group with the same number (see the earlier
@@ -3022,8 +3022,8 @@ 
    pcre2pattern man page
    
 and so on. Inside loops it can also make sense to refer to subsequent groups.
 The next capture group to be opened can be referenced as (?(+1), and so on. The
 value zero in any of these forms is not used; it provokes a compile-time error.
-
    
-
    
+
    
+
    
 Consider the following pattern, which contains non-significant white space to
 make it more readable (assume the PCRE2_EXTENDED option) and to divide it into
 three parts for ease of discussion:
@@ -3039,19 +3039,19 @@ 
    pcre2pattern man page
    
 parenthesis is required. Otherwise, since no-pattern is not present, the
 conditional group matches nothing. In other words, this pattern matches a
 sequence of non-parentheses, optionally enclosed in parentheses.
-
    
-
    
+
    
+
    
 If you were embedding this pattern in a larger one, you could use a relative
 reference:
 
       ...other stuff... ( \( )?    [^()]+    (?(-1) \) ) ...
 
    
 This makes the fragment independent of the parentheses in the larger pattern.
-
    
+
    
 
    
 Checking for a used capture group by name
 
    
-
    
+
    
 Perl uses the syntax (?(<name>)...) or (?('name')...) to test for a used
 capture group by name. For compatibility with earlier versions of PCRE1, which
 had this facility before Perl, the syntax (?(name)...) is also recognized.
@@ -3064,11 +3064,11 @@ 
    pcre2pattern man page
    
 If the name used in a condition of this kind is a duplicate, the test is
 applied to all groups of the same name, and is true if any one of them has
 matched.
-
    
+
    
 
    
 Checking for pattern recursion
 
    
-
    
+
    
 "Recursion" in this sense refers to any subroutine-like call from one part of
 the pattern to another, whether or not it is actually recursive. See the
 sections entitled
@@ -3076,8 +3076,8 @@ 
    pcre2pattern man page
    
 and
 "Groups as subroutines"
 below for details of recursion and subroutine calls.
-
    
-
    
+
    
+
    
 If a condition is the string (R), and there is no capture group with the name
 R, the condition is true if matching is currently in a recursion or subroutine
 call to the whole pattern or any capture group. If digits follow the letter R,
@@ -3091,28 +3091,28 @@ 
    pcre2pattern man page
    
 condition tests for its being set, as described in the section above, instead
 of testing for recursion. For example, creating a group with the name R1 by
 adding (?<R1>) to the above pattern completely changes its meaning.
-
    
-
    
+
    
+
    
 If a name preceded by ampersand follows the letter R, for example:
 
       (?(R&name)...)
 
    
 the condition is true if the most recent recursion is into a group of that name
 (which must exist within the pattern).
-
    
-
    
+
    
+
    
 This condition does not check the entire recursion stack. It tests only the
 current level. If the name used in a condition of this kind is a duplicate, the
 test is applied to all groups of the same name, and is true if any one of
 them is the most recent recursion.
-
    
-
    
+
    
+
    
 At "top level", all these recursion test conditions are false.
-
    
+
    
 
    
 Defining capture groups for use by reference only
 
    
-
    
+
    
 If the condition is the string (DEFINE), the condition is always false, even if
 there is a group with the name DEFINE. In this case, there may be only one
 alternative in the rest of the conditional group. It is always skipped if
@@ -3132,11 +3132,11 @@ 
    pcre2pattern man page
    
 pattern is skipped because DEFINE acts like a false condition. The rest of the
 pattern uses references to the named group to match the four dot-separated
 components of an IPv4 address, insisting on a word boundary at each end.
-
    
+
    
 
    
 Checking the PCRE2 version
 
    
-
    
+
    
 Programs that link with a PCRE2 library can check the version by calling
 pcre2_config() with appropriate arguments. Users of applications that do
 not have access to the underlying code cannot do this. A special "condition"
@@ -3150,17 +3150,17 @@ 
    pcre2pattern man page
    
 This pattern matches "yes" if the PCRE2 version is greater or equal to 10.4, or
 "no" otherwise. The fractional part of the version number may not contain more
 than two digits.
-
    
+
    
 
    
 Assertion conditions
 
    
-
    
+
    
 If the condition is not in any of the above formats, it must be a parenthesized
 assertion. This may be a positive or negative lookahead or lookbehind
 assertion. However, it must be a traditional atomic assertion, not one of the
 non-atomic assertions.
-
    
-
    
+
    
+
    
 Consider this pattern, again containing non-significant white space, and with
 the two alternatives on the second line:
 
    @@ -3173,23 +3173,23 @@ 
    pcre2pattern man page
    
 subject is matched against the first alternative; otherwise it is matched
 against the second. This pattern matches strings in one of the two forms
 dd-aaa-dd or dd-dd-dd, where aaa are letters and dd are digits.
-
    
-
    
+
    
+
    
 When an assertion that is a condition contains capture groups, any
 capturing that occurs in a matching branch is retained afterwards, for both
 positive and negative assertions, because matching always continues after the
 assertion, whether it succeeds or fails. (Compare non-conditional assertions,
 for which captures are retained only for positive assertions that succeed.)
-
    
+
    
 
    COMMENTS
    
-
    
+
    
 There are two ways of including comments in patterns that are processed by
 PCRE2. In both cases, the start of the comment must not be in a character
 class, nor in the middle of any other sequence of related characters such as
 (?: or a group name or number or a Unicode property name. The characters that
 make up a comment play no part in the pattern matching.
-
    
-
    
+
    
+
    
 The sequence (?# marks the start of a comment that continues up to the next
 closing parenthesis. Nested parentheses are not permitted. If the
 PCRE2_EXTENDED or PCRE2_EXTENDED_MORE option is set, an unescaped # character
@@ -3210,15 +3210,15 @@ 
    pcre2pattern man page
    
 a newline in the pattern. The sequence \n is still literal at this stage, so
 it does not terminate the comment. Only an actual character with the code value
 0x0a (the default newline) does so.
-
    
+
    
 
    RECURSIVE PATTERNS
    
-
    
+
    
 Consider the problem of matching a string in parentheses, allowing for
 unlimited nested parentheses. Without the use of recursion, the best that can
 be done is to use a pattern that matches up to some fixed depth of nesting. It
 is not possible to handle an arbitrary nesting depth.
-
    
-
    
+
    
+
    
 For some time, Perl has provided a facility that allows regular expressions to
 recurse (amongst other things). It does this by interpolating Perl code in the
 expression at run time, and the code can refer to the expression itself. A Perl
@@ -3229,22 +3229,22 @@ 
    pcre2pattern man page
    
 
    
 The (?p{...}) item interpolates Perl code at run time, and in this case refers
 recursively to the pattern in which it appears.
-
    
-
    
+
    
+
    
 Obviously, PCRE2 cannot support the interpolation of Perl code. Instead, it
 supports special syntax for recursion of the entire pattern, and also for
 individual capture group recursion. After its introduction in PCRE1 and Python,
 this kind of recursion was subsequently introduced into Perl at release 5.10.
-
    
-
    
+
    
+
    
 A special item that consists of (? followed by a number greater than zero and a
 closing parenthesis is a recursive subroutine call of the capture group of the
 given number, provided that it occurs inside that group. (If not, it is a
 non-recursive subroutine
 call, which is described in the next section.) The special item (?R) or (?0) is
 a recursive call of the entire regular expression.
-
    
-
    
+
    
+
    
 This PCRE2 pattern solves the nested parentheses problem (assume the
 PCRE2_EXTENDED option is set so that white space is ignored):
 
    @@ -3255,8 +3255,8 @@ 
    pcre2pattern man page
    
 match of the pattern itself (that is, a correctly parenthesized substring).
 Finally there is a closing parenthesis. Note the use of a possessive quantifier
 to avoid backtracking into sequences of non-parentheses.
-
    
-
    
+
    
+
    
 If this were part of a larger pattern, you would not want to recurse the entire
 pattern, so instead you could use this:
 
    @@ -3264,15 +3264,15 @@ 
    pcre2pattern man page
    
 
    
 We have put the pattern into parentheses, and caused the recursion to refer to
 them instead of the whole pattern.
-
    
-
    
+
    
+
    
 In a larger pattern, keeping track of parenthesis numbers can be tricky. This
 is made easier by the use of relative references. Instead of (?1) in the
 pattern above you can write (?-2) to refer to the second most recently opened
 parentheses preceding the recursion. In other words, a negative number counts
 capturing parentheses leftwards from the point at which it is encountered.
-
    
-
    
+
    
+
    
 Be aware however, that if
 duplicate capture group numbers
 are in use, relative references refer to the earliest group with the
@@ -3286,15 +3286,15 @@ 
    pcre2pattern man page
    
 group) to which the recursion refers. This would be the same if an absolute
 reference (?1) was used. In other words, relative references are just a
 shorthand for computing a group number.
-
    
-
    
+
    
+
    
 It is also possible to refer to subsequent capture groups, by writing
 references such as (?+2). However, these cannot be recursive because the
 reference is not inside the parentheses that are referenced. They are always
 non-recursive subroutine
 calls, as described in the next section.
-
    
-
    
+
    
+
    
 An alternative approach is to use named parentheses. The Perl syntax for this
 is (?&name); PCRE1's earlier syntax (?P>name) is also supported. We could
 rewrite the above example as follows:
@@ -3303,8 +3303,8 @@ 
    pcre2pattern man page
    
 
    
 If there is more than one group with the same name, the earliest one is
 used.
-
    
-
    
+
    
+
    
 The example pattern that we have been looking at contains nested unlimited
 repeats, and so the use of a possessive quantifier for matching strings of
 non-parentheses is important when applying the pattern to strings that do not
@@ -3316,8 +3316,8 @@ 
    pcre2pattern man page
    
 the match runs for a very long time indeed because there are so many different
 ways the + and * repeats can carve up the subject, and all have to be tested
 before failure can be reported.
-
    
-
    
+
    
+
    
 At the end of a match, the values of capturing parentheses are those from
 the outermost level. If you want to obtain intermediate values, a callout
 function can be used (see below and the
@@ -3330,8 +3330,8 @@ 
    pcre2pattern man page
    
 the last value taken on at the top level. If a capture group is not matched at
 the top level, its final captured value is unset, even if it was (temporarily)
 set at a deeper level during the matching process.
-
    
-
    
+
    
+
    
 Do not confuse the (?R) item with the condition (R), which tests for recursion.
 Consider this pattern, which matches text in angle brackets, allowing for
 arbitrary nesting. Only digits are allowed in nested brackets (that is, when
@@ -3342,28 +3342,28 @@ 
    pcre2pattern man page
    
 In this pattern, (?(R) is the start of a conditional group, with two different
 alternatives for the recursive and non-recursive cases. The (?R) item is the
 actual recursive call.
-
    
+
    
 
    
 Differences in recursion processing between PCRE2 and Perl
 
    
-
    
+
    
 Some former differences between PCRE2 and Perl no longer exist.
-
    
-
    
+
    
+
    
 Before release 10.30, recursion processing in PCRE2 differed from Perl in that
 a recursive subroutine call was always treated as an atomic group. That is,
 once it had matched some of the subject string, it was never re-entered, even
 if it contained untried alternatives and there was a subsequent matching
 failure. (Historical note: PCRE implemented recursion before Perl did.)
-
    
-
    
+
    
+
    
 Starting with release 10.30, recursive subroutine calls are no longer treated
 as atomic. That is, they can be re-entered to try unused alternatives if there
 is a matching failure later in the pattern. This is now compatible with the way
 Perl works. If you want a subroutine call to be atomic, you must explicitly
 enclose it in an atomic group.
-
    
-
    
+
    
+
    
 Supporting backtracking into recursions simplifies certain types of recursive
 pattern. For example, this pattern matches palindromic strings:
 
    @@ -3383,8 +3383,8 @@ 
    pcre2pattern man page
    
 avoid backtracking into sequences of non-word characters. Without this, PCRE2
 takes a great deal longer (ten times or more) to match typical phrases, and
 Perl takes so long that you think it has gone into a loop.
-
    
-
    
+
    
+
    
 Another way in which PCRE2 and Perl used to differ in their recursion
 processing is in the handling of captured values. Formerly in Perl, when a
 group was called recursively or as a subroutine (see the next section), it
@@ -3398,9 +3398,9 @@ 
    pcre2pattern man page
    
 alternative matches "a" and then recurses. In the recursion, \1 does now match
 "b" and so the whole match succeeds. This match used to fail in Perl, but in
 later versions (I tried 5.024) it now works.
-
    
+
    
 
    GROUPS AS SUBROUTINES
    
-
    
+
    
 If the syntax for a recursive group call (either by number or by name) is used
 outside the parentheses to which it refers, it operates a bit like a subroutine
 in a programming language. More accurately, PCRE2 treats the referenced group
@@ -3423,14 +3423,14 @@ 
    pcre2pattern man page
    
 
    
 is used, it does match "sense and responsibility" as well as the other two
 strings. Another example is given in the discussion of DEFINE above.
-
    
-
    
+
    
+
    
 Like recursions, subroutine calls used to be treated as atomic, but this
 changed at PCRE2 release 10.30, so backtracking into subroutine calls can now
 occur. However, any capturing parentheses that are set during the subroutine
 call revert to their previous values afterwards.
-
    
-
    
+
    
+
    
 Processing options such as case-independence are fixed when a group is
 defined, so if it is used as a subroutine, such options cannot be changed for
 different calls. For example, consider this pattern:
@@ -3439,16 +3439,16 @@ 
    pcre2pattern man page
    It matches "abcabc". It does not match "abcABC" because the change of processing option does not affect the called group. -

    -

    +

    +

    The behaviour of backtracking control verbs in groups when called as subroutines is described in the section entitled "Backtracking verbs in subroutines" below. -

    +


    ONIGURUMA SUBROUTINE SYNTAX
    -

    +

    For compatibility with Oniguruma, the non-Perl syntax \g followed by a name or a number enclosed either in angle brackets or single quotes, is an alternative syntax for calling a group as a subroutine, possibly recursively. Here are two @@ -3464,15 +3464,15 @@

    pcre2pattern man page

    Note that \g{...} (Perl syntax) and \g<...> (Oniguruma syntax) are not synonymous. The former is a backreference; the latter is a subroutine call. -

    +


    CALLOUTS
    -

    +

    Perl has a feature whereby using the sequence (?{...}) causes arbitrary Perl code to be obeyed in the middle of matching a regular expression. This makes it possible, amongst other things, to extract different substrings that match the same pair of parentheses when there is a repetition. -

    -

    +

    +

    PCRE2 provides a similar feature, but of course it cannot obey arbitrary Perl code. The feature is called "callout". The caller of PCRE2 provides an external function by putting its entry point in a match context using the function @@ -3481,8 +3481,8 @@

    pcre2pattern man page

    entry point is set to NULL, callout points will be passed over silently during matching. To disallow callouts in the pattern syntax, you may use the PCRE2_EXTRA_NEVER_CALLOUT option. -

    -

    +

    +

    Within a regular expression, (?C<arg>) indicates a point at which the external function is to be called. There are two kinds of callout: those with a numerical argument and those with a string argument. (?C) on its own with no @@ -3490,15 +3490,15 @@

    pcre2pattern man page

    distinguish between different callouts. String arguments were added for release 10.20 to make it possible for script languages that use PCRE2 to embed short scripts within patterns in a similar way to Perl. -

    -

    +

    +

    During matching, when PCRE2 reaches a callout point, the external function is called. It is provided with the number or string argument of the callout, the position in the pattern, and one item of data that is also set in the match block. The callout function may cause matching to proceed, to backtrack, or to fail. -

    -

    +

    +

    By default, PCRE2 implements a number of optimizations at matching time, and one side-effect is that sometimes callouts are skipped. If you need all possible callouts to happen, you need to set options that disable the relevant @@ -3506,11 +3506,11 @@

    pcre2pattern man page

    programming interface to the callout function, are given in the pcre2callout documentation. -

    +


    Callouts with numerical arguments
    -

    +

    If you just want to have a means of identifying different callout points, put a number less than 256 after the letter C. For example, this pattern has two callout points: @@ -3528,11 +3528,11 @@

    pcre2pattern man page

    Note that this applies only to assertion conditions, not to other types of condition. -

    +


    Callouts with string arguments
    -

    +

    A delimited string may be used instead of a number as a callout argument. The starting delimiter must be one of ` ' " ^ % # $ { and the ending delimiter is the same as the start, except for {, where the ending delimiter is }. If the @@ -3542,63 +3542,63 @@

    pcre2pattern man page

    (?C'ab ''c'' d')xyz(?C{any text})pqr The doubling is removed before the string is passed to the callout function. -

    +


    BACKTRACKING CONTROL
    -

    +

    There are a number of special "Backtracking Control Verbs" (to use Perl's terminology) that modify the behaviour of backtracking during matching. They are generally of the form (*VERB) or (*VERB:NAME). Some verbs take either form, and may behave differently depending on whether or not a name argument is present. The names are not required to be unique within the pattern. -

    -

    +

    +

    By default, for compatibility with Perl, a name is any sequence of characters that does not include a closing parenthesis. The name is not processed in any way, and it is not possible to include a closing parenthesis in the name. This can be changed by setting the PCRE2_ALT_VERBNAMES option, but the result is no longer Perl-compatible. -

    -

    +

    +

    When PCRE2_ALT_VERBNAMES is set, backslash processing is applied to verb names and only an unescaped closing parenthesis terminates the name. However, the only backslash items that are permitted are \Q, \E, and sequences such as \x{100} that define character code points. Character type escapes such as \d are faulted. -

    -

    +

    +

    A closing parenthesis can be included in a name either as \) or between \Q and \E. In addition to backslash processing, if the PCRE2_EXTENDED or PCRE2_EXTENDED_MORE option is also set, unescaped whitespace in verb names is skipped, and #-comments are recognized, exactly as in the rest of the pattern. PCRE2_EXTENDED and PCRE2_EXTENDED_MORE do not affect verb names unless PCRE2_ALT_VERBNAMES is also set. -

    -

    +

    +

    The maximum length of a name is 255 in the 8-bit library and 65535 in the 16-bit and 32-bit libraries. If the name is empty, that is, if the closing parenthesis immediately follows the colon, the effect is as if the colon were not there. Any number of these verbs may occur in a pattern. Except for (*ACCEPT), they may not be quantified. -

    -

    +

    +

    Since these verbs are specifically related to backtracking, most of them can be used only when the pattern is to be matched using the traditional matching function or JIT, because they use backtracking algorithms. With the exception of (*FAIL), which behaves like a failing negative assertion, the backtracking control verbs cause an error if encountered by the DFA matching function. -

    -

    +

    +

    The behaviour of these verbs in repeated groups, assertions, and in capture groups called as subroutines (whether or not recursively) is documented below. -

    +


    Optimizations that affect backtracking verbs
    -

    +

    PCRE2 contains some optimizations that are used to speed up matching by running some checks at the start of each match attempt. For example, it may know the minimum length of matching subject, or that a particular character must be @@ -3613,15 +3613,15 @@

    pcre2pattern man page

    in the pcre2api documentation. -

    -

    +

    +

    Experiments with Perl suggest that it too has similar optimizations, and like PCRE2, turning them off can change the result of a match. -

    +


    Verbs that act immediately
    -

    +

    The following verbs act as soon as they are encountered. 

        (*ACCEPT) or (*ACCEPT:NAME)
@@ -3631,8 +3631,8 @@ 
    pcre2pattern man page
    
 subroutine, only that group is ended successfully. Matching then continues
 at the outer level. If (*ACCEPT) in triggered in a positive assertion, the
 assertion succeeds; in a negative assertion, the assertion fails.
-
    
-
    
+
    
+
    
 If (*ACCEPT) is inside capturing parentheses, the data so far is captured. For
 example:
 
    @@ -3640,8 +3640,8 @@ 
    pcre2pattern man page
    
 
    
 This matches "AB", "AAD", or "ACD"; when it matches "AB", "B" is captured by
 the outer parentheses.
-
    
-
    
+
    
+
    
 (*ACCEPT) is the only backtracking verb that is allowed to be quantified
 because an ungreedy quantification with a minimum of zero acts only when a
 backtrack happens. Consider, for example,
@@ -3653,8 +3653,8 @@ 
    pcre2pattern man page
    
 the match succeeds. In both cases, all but C is captured. Whereas (*COMMIT)
 (see below) means "fail on backtrack", a repeated (*ACCEPT) of this type means
 "succeed on backtrack".
-
    
-
    
+
    
+
    
 Warning: (*ACCEPT) should not be used within a script run group, because
 it causes an immediate exit from the group, bypassing the script run checking.
 
    @@ -3670,16 +3670,16 @@ 
    pcre2pattern man page
    
 
    
 A match with the string "aaaa" always fails, but the callout is taken before
 each backtrack happens (in this example, 10 times).
-
    
-
    
+
    
+
    
 (*ACCEPT:NAME) and (*FAIL:NAME) behave the same as (*MARK:NAME)(*ACCEPT) and
 (*MARK:NAME)(*FAIL), respectively, that is, a (*MARK) is recorded just before
 the verb acts.
-
    
+
    
 
    
 Recording which path was taken
 
    
-
    
+
    
 There is one verb whose main purpose is to track how a match was arrived at,
 though it also has a secondary use in conjunction with advancing the match
 starting point (see (*SKIP) below).
@@ -3688,8 +3688,8 @@ 
    pcre2pattern man page
    A name is always required with this verb. For all the other backtracking control verbs, a NAME argument is optional. -

    -

    +

    +

    When a match succeeds, the name of the last-encountered mark name on the matching path is passed back to the caller as described in the section entitled "Other information about the match" @@ -3699,8 +3699,8 @@

    pcre2pattern man page

    including those inside assertions and atomic groups. However, there are differences in those cases when (*MARK) is used in conjunction with (*SKIP) as described below. -

    -

    +

    +

    The mark name that was last encountered on the matching path is passed back. A verb without a NAME argument is ignored for this purpose. Here is an example of pcre2test output, where the "mark" modifier requests the retrieval and @@ -3718,13 +3718,13 @@

    pcre2pattern man page

    indicates which of the two alternatives matched. This is a more efficient way of obtaining this information than putting each alternative in its own capturing parentheses. -

    -

    +

    +

    If a verb with a name is encountered in a positive assertion that is true, the name is recorded and passed back if it is the last-encountered. This does not happen for negative assertions or failing positive assertions. -

    -

    +

    +

    After a partial match or a failed match, the last encountered name in the entire match process is returned. For example: 

    @@ -3736,18 +3736,18 @@ 
    pcre2pattern man page
    
 attempt that started at the letter "X" in the subject. Subsequent match
 attempts starting at "P" and then with an empty string do not get as far as the
 (*MARK) item, but nevertheless do not reset it.
-
    
-
    
+
    
+
    
 If you are interested in (*MARK) values after failed matches, you should
 probably either set the PCRE2_NO_START_OPTIMIZE option or call
 pcre2_set_optimize() with a PCRE2_START_OPTIMIZE_OFF directive
 (see above)
 to ensure that the match is always attempted.
-
    
+
    
 
    
 Verbs that act after backtracking
 
    
-
    
+
    
 The following verbs do nothing when they are encountered. Matching continues
 with what follows, but if there is a subsequent match failure, causing a
 backtrack to the verb, a failure is forced. That is, backtracking cannot pass
@@ -3756,8 +3756,8 @@ 
    pcre2pattern man page
    
 confined to that group, because once the group has been matched, there is never
 any backtracking into it. Backtracking from beyond an atomic assertion or group
 ignores the entire group, and seeks a preceding backtracking point.
-
    
-
    
+
    
+
    
 These verbs differ in exactly what kind of failure occurs when backtracking
 reaches them. The behaviour described below is what happens when the verb is
 not in a subroutine or an assertion. Subsequent sections cover these special
@@ -3776,19 +3776,19 @@ 
    pcre2pattern man page
    This matches "xxaab" but not "aacaab". It can be thought of as a kind of dynamic anchor, or "I've started, so I must finish." -

    -

    +

    +

    The behaviour of (*COMMIT:NAME) is not the same as (*MARK:NAME)(*COMMIT). It is like (*MARK:NAME) in that the name is remembered for passing back to the caller. However, (*SKIP:NAME) searches only for names that are set with (*MARK), ignoring those set by any of the other backtracking verbs. -

    -

    +

    +

    If there is more than one backtracking verb in a pattern, a different one that follows (*COMMIT) may be triggered first, so merely passing (*COMMIT) during a match does not always guarantee that a match must be at this starting point. -

    -

    +

    +

    Note that (*COMMIT) at the start of a pattern is not the same as an anchor, unless PCRE2's start-of-match optimizations are turned off, as shown in this output from pcre2test: @@ -3820,8 +3820,8 @@

    pcre2pattern man page

    possessive quantifier, but there are some uses of (*PRUNE) that cannot be expressed in any other way. In an anchored pattern (*PRUNE) has the same effect as (*COMMIT). -

    -

    +

    +

    The behaviour of (*PRUNE:NAME) is not the same as (*MARK:NAME)(*PRUNE). It is like (*MARK:NAME) in that the name is remembered for passing back to the caller. However, (*SKIP:NAME) searches only for names set with (*MARK), @@ -3843,8 +3843,8 @@

    pcre2pattern man page

    effect as this example; although it would suppress backtracking during the first match attempt, the second attempt would start at the second character instead of skipping on to "c". -

    -

    +

    +

    If (*SKIP) is used to specify a new starting position that is the same as the starting position of the current match, or (by being inside a lookbehind) earlier, the position specified by (*SKIP) is ignored, and instead the normal @@ -3858,8 +3858,8 @@

    pcre2pattern man page

    advance is to the subject position that corresponds to that (*MARK) instead of to where (*SKIP) was encountered. If no (*MARK) with a matching name is found, the (*SKIP) is ignored. -

    -

    +

    +

    The search for a (*MARK) name uses the normal backtracking mechanism, which means that it does not see (*MARK) settings that are inside atomic groups or assertions, because they are never re-entered by backtracking. Compare the @@ -3883,8 +3883,8 @@

    pcre2pattern man page

    matching attempt to start at the second character. This time, the (*MARK) is never seen because "a" does not match "b", so the matcher immediately jumps to the second branch of the pattern. -

    -

    +

    +

    Note that (*SKIP:NAME) searches only for names set by (*MARK:NAME). It ignores names that are set by other backtracking verbs. 

    @@ -3903,14 +3903,14 @@ 
    pcre2pattern man page
    
 succeeds and BAR fails, COND3 is tried. If subsequently BAZ fails, there are no
 more alternatives, so there is a backtrack to whatever came before the entire
 group. If (*THEN) is not inside an alternation, it acts like (*PRUNE).
-
    
-
    
+
    
+
    
 The behaviour of (*THEN:NAME) is not the same as (*MARK:NAME)(*THEN). It is
 like (*MARK:NAME) in that the name is remembered for passing back to the
 caller. However, (*SKIP:NAME) searches only for names set with (*MARK),
 ignoring those set by other backtracking verbs.
-
    
-
    
+
    
+
    
 A group that does not contain a | character is just a part of the enclosing
 alternative; it is not a nested alternation with only one alternative. The
 effect of (*THEN) extends beyond such a group to the enclosing alternative.
@@ -3929,8 +3929,8 @@ 
    pcre2pattern man page
    
 The effect of (*THEN) is now confined to the inner group. After a failure in C,
 matching moves to (*FAIL), which causes the whole group to fail because there
 are no more alternatives to try. In this case, matching does backtrack into A.
-
    
-
    
+
    
+
    
 Note that a conditional group is not considered as having two alternatives,
 because only one is ever used. In other words, the | character in a conditional
 group has a different meaning. Ignoring white space, consider:
@@ -3944,8 +3944,8 @@ 
    pcre2pattern man page
    
 character. The conditional group is part of the single alternative that
 comprises the whole pattern, and so the match fails. (If there was a backtrack
 into .*?, allowing it to match "b", the match would succeed.)
-
    
-
    
+
    
+
    
 The verbs just described provide four different "strengths" of control when
 subsequent matching fails. (*THEN) is the weakest, carrying on the match at the
 next alternative. (*PRUNE) comes next, failing the match at the current
@@ -3953,11 +3953,11 @@ 
    pcre2pattern man page
    
 unanchored pattern). (*SKIP) is similar, except that the advance may be more
 than one character. (*COMMIT) is the strongest, causing the entire match to
 fail.
-
    
+
    
 
    
 More than one backtracking verb
 
    
-
    
+
    
 If more than one backtracking verb is present in a pattern, the one that is
 backtracked onto first acts. For example, consider this pattern, where A, B,
 etc. are complex pattern fragments:
@@ -3976,11 +3976,11 @@ 
    pcre2pattern man page
    
 If there is a matching failure to the right, backtracking onto (*PRUNE) causes
 it to be triggered, and its action is taken. There can never be a backtrack
 onto (*COMMIT).
-
    
+
    
 
    
 Backtracking verbs in repeated groups
 
    
-
    
+
    
 PCRE2 sometimes differs from Perl in its handling of backtracking verbs in
 repeated groups. For example, consider:
 
    @@ -3989,37 +3989,37 @@ 
    pcre2pattern man page
    
 If the subject is "abac", Perl matches unless its optimizations are disabled,
 but PCRE2 always fails because the (*COMMIT) in the second repeat of the group
 acts.
-
    
+
    
 
    
 Backtracking verbs in assertions
 
    
-
    
+
    
 (*FAIL) in any assertion has its normal effect: it forces an immediate
 backtrack. The behaviour of the other backtracking verbs depends on whether or
 not the assertion is standalone or acting as the condition in a conditional
 group.
-
    
-
    
+
    
+
    
 (*ACCEPT) in a standalone positive assertion causes the assertion to succeed
 without any further processing; captured strings and a mark name (if set) are
 retained. In a standalone negative assertion, (*ACCEPT) causes the assertion to
 fail without any further processing; captured substrings and any mark name are
 discarded.
-
    
-
    
+
    
+
    
 If the assertion is a condition, (*ACCEPT) causes the condition to be true for
 a positive assertion and false for a negative one; captured substrings are
 retained in both cases.
-
    
-
    
+
    
+
    
 The remaining verbs act only when a later failure causes a backtrack to
 reach them. This means that, for the Perl-compatible assertions, their effect
 is confined to the assertion, because Perl lookaround assertions are atomic. A
 backtrack that occurs after such an assertion is complete does not jump back
 into the assertion. Note in particular that a (*MARK) name that is set in an
 assertion is not "seen" by an instance of (*SKIP:NAME) later in the pattern.
-
    
-
    
+
    
+
    
 PCRE2 now supports non-atomic positive assertions and also "scan substring"
 assertions, as described in the sections entitled
 "Non-atomic assertions"
@@ -4029,57 +4029,57 @@ 
    pcre2pattern man page
    
 not Perl-compatible. For these assertions, a later backtrack does jump back
 into the assertion, and therefore verbs such as (*COMMIT) can be triggered by
 backtracks from later in the pattern.
-
    
-
    
+
    
+
    
 The effect of (*THEN) is not allowed to escape beyond an assertion. If there
 are no more branches to try, (*THEN) causes a positive assertion to be false,
 and a negative assertion to be true. This behaviour differs from Perl when the
 assertion has only one branch.
-
    
-
    
+
    
+
    
 The other backtracking verbs are not treated specially if they appear in a
 standalone positive assertion. In a conditional positive assertion,
 backtracking (from within the assertion) into (*COMMIT), (*SKIP), or (*PRUNE)
 causes the condition to be false. However, for both standalone and conditional
 negative assertions, backtracking into (*COMMIT), (*SKIP), or (*PRUNE) causes
 the assertion to be true, without considering any further alternative branches.
-
    
+
    
 
    
 Backtracking verbs in subroutines
 
    
-
    
+
    
 These behaviours occur whether or not the group is called recursively.
-
    
-
    
+
    
+
    
 (*ACCEPT) in a group called as a subroutine causes the subroutine match to
 succeed without any further processing. Matching then continues after the
 subroutine call. Perl documents this behaviour. Perl's treatment of the other
 verbs in subroutines is different in some cases.
-
    
-
    
+
    
+
    
 (*FAIL) in a group called as a subroutine has its normal effect: it forces
 an immediate backtrack.
-
    
-
    
+
    
+
    
 (*COMMIT), (*SKIP), and (*PRUNE) cause the subroutine match to fail when
 triggered by being backtracked to in a group called as a subroutine. There is
 then a backtrack at the outer level.
-
    
-
    
+
    
+
    
 (*THEN), when triggered, skips to the next alternative in the innermost
 enclosing group that has alternatives (its normal behaviour). However, if there
 is no such group within the subroutine's group, the subroutine match fails and
 there is a backtrack at the outer level.
-
    
+
    
 
    EBCDIC ENVIRONMENTS
    
-
    
+
    
 Differences in the way PCRE behaves when it is running in an EBCDIC environment
 are covered in this section.
-
    
+
    
 
    
 Escape sequences
 
    
-
    
+
    
 When PCRE2 is compiled in EBCDIC mode, \N{U+hhh..} is not supported. \a, \e,
 \f, \n, \r, and \t generate the appropriate EBCDIC code values. The \c
 escape is processed as specified for Perl in the perlebcdic document. The
@@ -4088,25 +4088,25 @@ 
    pcre2pattern man page
    
 \c@ encodes character code 0; after \c the letters (in either case) encode
 characters 1-26 (hex 01 to hex 1A); [, \, ], ^, and _ encode characters 27-31
 (hex 1B to hex 1F), and \c? becomes either 255 (hex FF) or 95 (hex 5F).
-
    
-
    
+
    
+
    
 Thus, apart from \c?, these escapes generate the same character code values as
 they do in an ASCII or Unicode environment, though the meanings of the values
 mostly differ. For example, \cG always generates code value 7, which is BEL in
 ASCII but DEL in EBCDIC.
-
    
-
    
+
    
+
    
 The sequence \c? generates DEL (127, hex 7F) in an ASCII environment, but
 because 127 is not a control character in EBCDIC, Perl makes it generate the
 APC character. Unfortunately, there are several variants of EBCDIC. In most of
 them the APC character has the value 255 (hex FF), but in the one Perl calls
 POSIX-BC its value is 95 (hex 5F). If certain other characters have POSIX-BC
 values, PCRE2 makes \c? generate 95; otherwise it generates 255.
-
    
+
    
 
    
 Character classes
 
    
-
    
+
    
 In character classes there is a special case in EBCDIC environments for ranges
 whose end points are both specified as literal letters in the same case. For
 compatibility with Perl, EBCDIC code points within the range that are not
@@ -4114,23 +4114,23 @@ 
    pcre2pattern man page
    
 though the EBCDIC codes for h and k are 0x88 and 0x92, a range of 11 code
 points. However, if the range is specified numerically, for example,
 [\x88-\x92] or [h-\x92], all code points are included.
-
    
+
    
 
    SEE ALSO
    
-
    
+
    
 pcre2api(3), pcre2callout(3), pcre2matching(3),
 pcre2syntax(3), pcre2(3).
-
    
+
    
 
    AUTHOR
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    REVISION
    
-
    
+
    
 Last updated: 27 November 2024
 
    
 Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/html/pcre2perform.html b/doc/html/pcre2perform.html
index b595119ba..1ae46c0ee 100644
--- a/doc/html/pcre2perform.html
+++ b/doc/html/pcre2perform.html
@@ -21,13 +21,13 @@ 
    pcre2perform man page
    
 
  • REVISION
 
 
    PCRE2 PERFORMANCE
    
-
    
+
    
 Two aspects of performance are discussed below: memory usage and processing
 time. The way you express your pattern as a regular expression can affect both
 of them.
-
    
+
    
 
    COMPILED PATTERN MEMORY USAGE
    
-
    
+
    
 Patterns are compiled by PCRE2 into a reasonably efficient interpretive code,
 so that most simple patterns do not use much memory for storing the compiled
 version. However, there is one case where the memory usage of a compiled
@@ -43,8 +43,8 @@ 
    pcre2perform man page
    
 
    • 
 (Technical aside: It is done this way so that backtrack points within each of
 the repetitions can be independently maintained.)
-
    
-
    
+
    
+
    
 For regular expressions whose quantifiers use only small numbers, this is not
 usually a problem. However, if the numbers are large, and particularly if such
 repetitions are nested, the memory usage can become an embarrassment. For
@@ -59,8 +59,8 @@ 
    pcre2perform man page
    
 from 3 to 4. PCRE2 can be compiled to use larger internal pointers and thus
 handle larger compiled patterns, but it is better to try to rewrite your
 pattern to use less memory if you can.
-
    
-
    
+
    
+
    
 One way of reducing the memory usage for such patterns is to make use of
 PCRE2's
 "subroutine"
@@ -76,22 +76,22 @@ 
    pcre2perform man page
    
 cannot otherwise handle. The matching performance of the two different versions
 of the pattern are roughly the same. (This applies from release 10.30 - things
 were different in earlier releases.)
-
    
+
    
 
    STACK AND HEAP USAGE AT RUN TIME
    
-
    
+
    
 From release 10.30, the interpretive (non-JIT) version of pcre2_match()
 uses very little system stack at run time. In earlier releases recursive
 function calls could use a great deal of stack, and this could cause problems,
 but this usage has been eliminated. Backtracking positions are now explicitly
 remembered in memory frames controlled by the code.
-
    
-
    
+
    
+
    
 The size of each frame depends on the size of pointer variables and the number
 of capturing parenthesized groups in the pattern being matched. On a 64-bit
 system the frame size for a pattern with no captures is 128 bytes. For each
 capturing group the size increases by 16 bytes.
-
    
-
    
+
    
+
    
 Until release 10.41, an initial 20KiB frames vector was allocated on the system
 stack, but this still caused some issues for multi-thread applications where
 each thread has a very small stack. From release 10.41 backtracking memory
@@ -99,8 +99,8 @@ 
    pcre2perform man page
    
 the first time any match data block is passed to pcre2_match(). This is
 remembered with the match data block and re-used if that block is used for
 another match. It is freed when the match data block itself is freed.
-
    
-
    
+
    
+
    
 The size of the initial block is the larger of 20KiB or ten times the pattern's
 frame size, unless the heap limit is less than this, in which case the heap
 limit is used. If the initial block proves to be too small during matching, it
@@ -108,8 +108,8 @@ 
    pcre2perform man page
    
 checked only when a new block is to be allocated. Reducing the heap limit
 between calls to pcre2_match() with the same match data block does not
 affect the saved block.
-
    
-
    
+
    
+
    
 In contrast to pcre2_match(), pcre2_dfa_match() does use recursive
 function calls, but only for processing atomic groups, lookaround assertions,
 and recursion within the pattern. The original version of the code used to
@@ -118,14 +118,14 @@ 
    pcre2perform man page
    
 10.32 the code for pcre2_dfa_match() has been re-factored to use heap
 memory when necessary for internal workspace when recursing, though recursive
 function calls are still used.
-
    
-
    
+
    
+
    
 The "match depth" parameter can be used to limit the depth of function
 recursion, and the "match heap" parameter to limit heap memory in
 pcre2_dfa_match().
-
    
+
    
 
    PROCESSING TIME
    
-
    
+
    
 Certain items in regular expression patterns are processed more efficiently
 than others. It is more efficient to use a character class like [aeiou] than a
 set of single-character alternatives such as (a|e|i|o|u). In general, the
@@ -133,14 +133,14 @@ 
    pcre2perform man page
    
 efficient. Jeffrey Friedl's book contains a lot of useful general discussion
 about optimizing regular expressions for efficient performance. This document
 contains a few observations about PCRE2.
-
    
-
    
+
    
+
    
 Using Unicode character properties (the \p, \P, and \X escapes) is slow,
 because PCRE2 has to use a multi-stage table lookup whenever it needs a
 character's property. If you can find an alternative pattern that does not use
 character properties, it will probably be faster.
-
    
-
    
+
    
+
    
 By default, the escape sequences \b, \d, \s, and \w, and the POSIX
 character classes such as [:alpha:] do not use Unicode properties, partly for
 backwards compatibility, and partly for performance reasons. However, you can
@@ -149,8 +149,8 @@ 
    pcre2perform man page
    
 such as \d, when matched with pcre2_match(); the performance loss is
 less with a DFA matching function, and in both cases there is not much
 difference for \b.
-
    
-
    
+
    
+
    
 When a pattern begins with .* not in atomic parentheses, nor in parentheses
 that are the subject of a backreference, and the PCRE2_DOTALL option is set,
 the pattern is implicitly anchored by PCRE2, since it can match only at the
@@ -158,8 +158,8 @@ 
    pcre2perform man page
    
 must all be anchorable. The optimization can be disabled by the
 PCRE2_NO_DOTSTAR_ANCHOR option, and is automatically disabled if the pattern
 contains (*PRUNE) or (*SKIP).
-
    
-
    
+
    
+
    
 If PCRE2_DOTALL is not set, PCRE2 cannot make this optimization, because the
 dot metacharacter does not then match a newline, and if the subject string
 contains newlines, the pattern may match from the character immediately
@@ -170,14 +170,14 @@ 
    pcre2perform man page
    
 matches the subject "first\nand second" (where \n stands for a newline
 character), with the match starting at the seventh character. In order to do
 this, PCRE2 has to retry the match starting after every newline in the subject.
-
    
-
    
+
    
+
    
 If you are using such a pattern with subject strings that do not contain
 newlines, the best performance is obtained by setting PCRE2_DOTALL, or starting
 the pattern with ^.* or ^.*? to indicate explicit anchoring. That saves PCRE2
 from having to scan along the subject looking for a newline to restart at.
-
    
-
    
+
    
+
    
 Beware of patterns that contain nested indefinite repeats. These can take a
 long time to run when applied to a string that does not match. Consider the
 pattern fragment
@@ -191,8 +191,8 @@ 
    pcre2perform man page
    
 entire match is going to fail, PCRE2 has in principle to try every possible
 variation, and this can take an extremely long time, even for relatively short
 strings.
-
    
-
    
+
    
+
    
 An optimization catches some of the more simple cases such as
 
       (a+)*b
@@ -208,8 +208,8 @@ 
    pcre2perform man page
    
 with the pattern above. The former gives a failure almost instantly when
 applied to a whole line of "a" characters, whereas the latter takes an
 appreciable time with strings longer than about 20 characters.
-
    
-
    
+
    
+
    
 In many cases, the solution to this kind of performance issue is to use an
 atomic group or a possessive quantifier. This can often reduce memory
 requirements as well. As another example, consider this pattern:
@@ -233,16 +233,16 @@ 
    pcre2perform man page
    
 version also uses a lot less memory because entry to a new set of parentheses
 happens only when a "<" character that is not followed by "inet" is encountered
 (and we assume this is relatively rare).
-
    
-
    
+
    
+
    
 This example shows that one way of optimizing performance when matching long
 subject strings is to write repeated parenthesized subpatterns to match more
 than one character whenever possible.
-
    
+
    
 
    
 SETTING RESOURCE LIMITS
 
    
-
    
+
    
 You can set limits on the amount of processing that takes place when matching,
 and on the amount of heap memory that is used. The default values of the limits
 are very large, and unlikely ever to operate. They can be changed when PCRE2 is
@@ -254,23 +254,23 @@ 
    pcre2perform man page
    
 in the
 pcre2api
 documentation.
-
    
-
    
+
    
+
    
 The pcre2test test program has a modifier called "find_limits" which, if
 applied to a subject line, causes it to find the smallest limits that allow a
 pattern to match. This is done by repeatedly matching with different limits.
-
    
+
    
 
    AUTHOR
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    REVISION
    
-
    
+
    
 Last updated: 06 December 2022
 
    
 Copyright © 1997-2022 University of Cambridge.
diff --git a/doc/html/pcre2posix.html b/doc/html/pcre2posix.html
index bc60c3b79..b066949bb 100644
--- a/doc/html/pcre2posix.html
+++ b/doc/html/pcre2posix.html
@@ -25,10 +25,10 @@ 
    pcre2posix man page
    
 
  • REVISION
 
 
    SYNOPSIS
    
-
    
+
    
 #include <pcre2posix.h>
-
    
-
    
+
    
+
    
 int pcre2_regcomp(regex_t *preg, const char *pattern,
      int cflags);
 
    
@@ -42,22 +42,22 @@ 
    pcre2posix man page
    
 
    
 
    
 void pcre2_regfree(regex_t *preg);
-
    
+
    
 
    DESCRIPTION
    
-
    
+
    
 This set of functions provides a POSIX-style API for the PCRE2 regular
 expression 8-bit library. There are no POSIX-style wrappers for PCRE2's 16-bit
 and 32-bit libraries. See the
 pcre2api
 documentation for a description of PCRE2's native API, which contains much
 additional functionality.
-
    
-
    
+
    
+
    
 IMPORTANT NOTE: The functions described here are NOT thread-safe, and
 should not be used in multi-threaded applications. They are also limited to
 processing subjects that are not bigger than 2GB. Use the native API instead.
-
    
-
    
+
    
+
    
 These functions are wrapper functions that ultimately call the PCRE2 native
 API. Their prototypes are defined in the pcre2posix.h header file, and
 they all have unique names starting with pcre2_. However, the
@@ -65,20 +65,20 @@ 
    pcre2posix man page
    
 standard POSIX names such regcomp() into pcre2_regcomp() etc. This
 means that a program can use the usual POSIX names without running the risk of
 accidentally linking with POSIX functions from a different library.
-
    
-
    
+
    
+
    
 On Unix-like systems the PCRE2 POSIX library is called libpcre2-posix, so
 can be accessed by adding -lpcre2-posix to the command for linking an
 application. Because the POSIX functions call the native ones, it is also
 necessary to add -lpcre2-8.
-
    
-
    
+
    
+
    
 On Windows systems, if you are linking to a DLL version of the library, it is
 recommended that PCRE2POSIX_SHARED is defined before including the
 pcre2posix.h header, as it will allow for a more efficient way to
 invoke the functions by adding the __declspec(dllimport) decorator.
-
    
-
    
+
    
+
    
 Although they were not defined as prototypes in pcre2posix.h, releases
 10.33 to 10.36 of the library contained functions with the POSIX names
 regcomp() etc. These simply passed their arguments to the PCRE2
@@ -87,48 +87,48 @@ 
    pcre2posix man page
    
 troublesome in situations where a program links with several libraries, some of
 which use PCRE2's POSIX interface while others use the real POSIX functions.
 For this reason, the POSIX names have been removed since release 10.37.
-
    
-
    
+
    
+
    
 Calling the header file pcre2posix.h avoids any conflict with other POSIX
 libraries. It can, of course, be renamed or aliased as regex.h, which is
 the "correct" name, if there is no clash. It provides two structure types,
 regex_t for compiled internal forms, and regmatch_t for returning
 captured substrings. It also defines some constants whose names start with
 "REG_"; these are used for setting options and identifying error codes.
-
    
+
    
 
    USING THE POSIX FUNCTIONS
    
-
    
+
    
 Note that these functions are just POSIX-style wrappers for PCRE2's native API.
 They do not give POSIX regular expression behaviour, and they are not
 thread-safe or even POSIX compatible.
-
    
-
    
+
    
+
    
 Those POSIX option bits that can reasonably be mapped to PCRE2 native options
 have been implemented. In addition, the option REG_EXTENDED is defined with the
 value zero. This has no effect, but since programs that are written to the
 POSIX interface often use it, this makes it easier to slot in PCRE2 as a
 replacement library. Other POSIX options are not even defined.
-
    
-
    
+
    
+
    
 There are also some options that are not defined by POSIX. These have been
 added at the request of users who want to make use of certain PCRE2-specific
 features via the POSIX calling interface or to add BSD or GNU functionality.
-
    
-
    
+
    
+
    
 When PCRE2 is called via these functions, it is only the API that is POSIX-like
 in style. The syntax and semantics of the regular expressions themselves are
 still those of Perl, subject to the setting of various PCRE2 options, as
 described below. "POSIX-like in style" means that the API approximates to the
 POSIX definition; it is not fully POSIX-compatible, and in multi-unit encoding
 domains it is probably even less compatible.
-
    
-
    
+
    
+
    
 The descriptions below use the actual names of the functions, but, as described
 above, the standard POSIX names (without the pcre2_ prefix) may also be
 used.
-
    
+
    
 
    COMPILING A PATTERN
    
-
    
+
    
 The function pcre2_regcomp() is called to compile a pattern into an
 internal form. By default, the pattern is a C string terminated by a binary
 zero (but see REG_PEND below). The preg argument is a pointer to a
@@ -137,8 +137,8 @@ 
    pcre2posix man page
    
 set. The regex_t structure used by pcre2_regcomp() is defined in
 pcre2posix.h and is not the same as the structure used by other libraries
 that provide POSIX-style matching.
-
    
-
    
+
    
+
    
 The argument cflags is either zero, or contains one or more of the bits
 defined by the following macros:
 
    @@ -204,8 +204,8 @@ 
    pcre2posix man page
    
 compilation to the native function. This causes the pattern itself and all data
 strings used for matching it to be treated as UTF-8 strings. Note that REG_UTF
 is not part of the POSIX standard.
-
    
-
    
+
    
+
    
 In the absence of these flags, no options are passed to the native function.
 This means that the regex is compiled with PCRE2 default semantics. In
 particular, the way it handles newline characters in the subject string is the
@@ -213,22 +213,22 @@ 
    pcre2posix man page
    
 some of the effects specified for REG_NEWLINE. It does not affect the way
 newlines are matched by the dot metacharacter (they are not) or by a negative
 class such as [^a] (they are).
-
    
-
    
+
    
+
    
 The yield of pcre2_regcomp() is zero on success, and non-zero otherwise.
 The preg structure is filled in on success, and one other member of the
 structure (as well as re_endp) is public: re_nsub contains the
 number of capturing subpatterns in the regular expression. Various error codes
 are defined in the header file.
-
    
-
    
+
    
+
    
 NOTE: If the yield of pcre2_regcomp() is non-zero, you must not attempt
 to use the contents of the preg structure. If, for example, you pass it
 to pcre2_regexec(), the result is undefined and your program is likely to
 crash.
-
    
+
    
 
    MATCHING NEWLINE CHARACTERS
    
-
    
+
    
 This area is not simple, because POSIX and Perl take different views of things.
 It is not possible to get PCRE2 to obey POSIX semantics, but then PCRE2 was
 never intended to be a POSIX engine. The following table lists the different
@@ -256,17 +256,17 @@ 
    pcre2posix man page
    
 API. By default, PCRE2's behaviour is the same as Perl's, except that there is
 no equivalent for PCRE2_DOLLAR_ENDONLY in Perl. In both PCRE2 and Perl, there
 is no way to stop newline from matching [^a].
-
    
-
    
+
    
+
    
 Default POSIX newline handling can be obtained by setting PCRE2_DOTALL and
 PCRE2_DOLLAR_ENDONLY when calling pcre2_compile() directly, but there is
 no way to make PCRE2 behave exactly as for the REG_NEWLINE action. When using
 the POSIX API, passing REG_NEWLINE to PCRE2's pcre2_regcomp() function
 causes PCRE2_MULTILINE to be passed to pcre2_compile(), and REG_DOTALL
 passes PCRE2_DOTALL. There is no way to pass PCRE2_DOLLAR_ENDONLY.
-
    
+
    
 
    MATCHING A PATTERN
    
-
    
+
    
 The function pcre2_regexec() is called to match a compiled pattern
 preg against a given string, which is by default terminated by a
 zero byte (but see REG_STARTEND below), subject to the options in eflags.
@@ -295,33 +295,33 @@ 
    pcre2posix man page
    
 should point to the first character beyond the string. There may be binary
 zeros within the subject string, and indeed, using REG_STARTEND is the only
 way to pass a subject string that contains a binary zero.
-
    
-
    
+
    
+
    
 Whatever the value of pmatch[0].rm_so, the offsets of the matched string
 and any captured substrings are still given relative to the start of
 string itself. (Before PCRE2 release 10.30 these were given relative to
 string + pmatch[0].rm_so, but this differs from other
 implementations.)
-
    
-
    
+
    
+
    
 This is a BSD extension, compatible with but not specified by IEEE Standard
 1003.2 (POSIX.2), and should be used with caution in software intended to be
 portable to other systems. Note that a non-zero rm_so does not imply
 REG_NOTBOL; REG_STARTEND affects only the location and length of the string,
 not how it is matched. Setting REG_STARTEND and passing pmatch as NULL
 are mutually exclusive; the error REG_INVARG is returned.
-
    
-
    
+
    
+
    
 If the pattern was compiled with the REG_NOSUB flag, no data about any matched
 strings is returned. The nmatch and pmatch arguments of
 pcre2_regexec() are ignored (except possibly as input for REG_STARTEND).
-
    
-
    
+
    
+
    
 The value of nmatch may be zero, and the value pmatch may be NULL
 (unless REG_STARTEND is set); in both these cases no data about any matched
 strings is returned.
-
    
-
    
+
    
+
    
 Otherwise, the portion of the string that was matched, and also any captured
 substrings, are returned via the pmatch argument, which points to an
 array of nmatch structures of type regmatch_t, containing the
@@ -331,18 +331,18 @@ 
    pcre2posix man page
    
 entire portion of string that was matched; subsequent elements relate to
 the capturing subpatterns of the regular expression. Unused entries in the
 array have both structure members set to -1.
-
    
-
    
+
    
+
    
 regmatch_t as well as the regoff_t typedef it uses are defined in
 pcre2posix.h and are not warranted to have the same size or layout as other
 similarly named types from other libraries that provide POSIX-style matching.
-
    
-
    
+
    
+
    
 A successful match yields a zero return; various error codes are defined in the
 header file, of which REG_NOMATCH is the "expected" failure code.
-
    
+
    
 
    ERROR MESSAGES
    
-
    
+
    
 The pcre2_regerror() function maps a non-zero errorcode from either
 pcre2_regcomp() or pcre2_regexec() to a printable message. If
 preg is not NULL, the error should have arisen from the use of that
@@ -351,25 +351,25 @@ 
    pcre2posix man page
    
 error message are used. The yield of the function is the size of buffer needed
 to hold the whole message, including the terminating zero. This value is
 greater than errbuf_size if the message was truncated.
-
    
+
    
 
    MEMORY USAGE
    
-
    
+
    
 Compiling a regular expression causes memory to be allocated and associated
 with the preg structure. The function pcre2_regfree() frees all
 such memory, after which preg may no longer be used as a compiled
 expression.
-
    
+
    
 
    AUTHOR
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    REVISION
    
-
    
+
    
 Last updated: 27 November 2024
 
    
 Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/html/pcre2sample.html b/doc/html/pcre2sample.html
index 0903f04f9..dcc19de72 100644
--- a/doc/html/pcre2sample.html
+++ b/doc/html/pcre2sample.html
@@ -15,35 +15,35 @@ 
    pcre2sample man page
    
 
    
 PCRE2 SAMPLE PROGRAM
 
    
-
    
+
    
 A simple, complete demonstration program to get you started with using PCRE2 is
 supplied in the file pcre2demo.c in the src directory in the PCRE2
 distribution. A listing of this program is given in the
 pcre2demo
 documentation. If you do not have a copy of the PCRE2 distribution, you can
 save this listing to re-create the contents of pcre2demo.c.
-
    
-
    
+
    
+
    
 The demonstration program compiles the regular expression that is its
 first argument, and matches it against the subject string in its second
 argument. No PCRE2 options are set, and default character tables are used. If
 matching succeeds, the program outputs the portion of the subject that matched,
 together with the contents of any captured substrings.
-
    
-
    
+
    
+
    
 If the -g option is given on the command line, the program then goes on to
 check for further matches of the same regular expression in the same subject
 string. The logic is a little bit tricky because of the possibility of matching
 an empty string. Comments in the code explain what is going on.
-
    
-
    
+
    
+
    
 The code in pcre2demo.c is an 8-bit program that uses the PCRE2 8-bit
 library. It handles strings and characters that are stored in 8-bit code units.
 By default, one character corresponds to one code unit, but if the pattern
 starts with "(*UTF)", both it and the subject are treated as UTF-8 strings,
 where characters may occupy multiple code units.
-
    
-
    
+
    
+
    
 If PCRE2 is installed in the standard include and library directories for your
 operating system, you should be able to compile the demonstration program using
 a command like this:
@@ -70,8 +70,8 @@ 
    pcre2sample man page
    
 installed). The
 pcre2demo
 program is provided as a relatively simple coding example.
-
    
-
    
+
    
+
    
 If you try to run
 pcre2demo
 when PCRE2 is not installed in the standard library directory, you may get an
@@ -85,22 +85,22 @@ 
    pcre2sample man page
    
   -R/usr/local/lib
 
    
 (for example) to the compile command to get round this problem.
-
    
+
    
 
    
 AUTHOR
 
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    
 REVISION
 
    
-
    
+
    
 Last updated: 14 November 2023
 
    
 Copyright © 1997-2016 University of Cambridge.
diff --git a/doc/html/pcre2serialize.html b/doc/html/pcre2serialize.html
index d189bde2b..49c52b535 100644
--- a/doc/html/pcre2serialize.html
+++ b/doc/html/pcre2serialize.html
@@ -21,7 +21,7 @@ 
    pcre2serialize man page
    
 
  • REVISION
 
 
    SAVING AND RE-USING PRECOMPILED PCRE2 PATTERNS
    
-
    
+
    
 int32_t pcre2_serialize_decode(pcre2_code **codes,
   int32_t number_of_codes, const uint8_t *bytes,
   pcre2_general_context *gcontext);
@@ -48,8 +48,8 @@ 
    pcre2serialize man page
    
 and PCRE2_SIZE type. For example, patterns compiled on a 32-bit system using
 PCRE2's 16-bit library cannot be reloaded on a 64-bit system, nor can they be
 reloaded using the 8-bit library.
-
    
-
    
+
    
+
    
 Note that "serialization" in PCRE2 does not convert compiled patterns to an
 abstract format like Java or .NET serialization. The serialized output is
 really just a bytecode dump, which is why it can only be reloaded in the same
@@ -57,9 +57,9 @@ 
    pcre2serialize man page
    
 Applications that are not statically linked with a fixed version of PCRE2 must
 be prepared to recompile patterns from their sources, in order to be immune to
 PCRE2 upgrades.
-
    
+
    
 
    SECURITY CONCERNS
    
-
    
+
    
 The facility for saving and restoring compiled patterns is intended for use
 within individual applications. As such, the data supplied to
 pcre2_serialize_decode() is expected to be trusted data, not data from
@@ -68,9 +68,9 @@ 
    pcre2serialize man page
    
 undefined results. For example, if the length field of a pattern in the
 serialized data is corrupted, the deserializing code may read beyond the end of
 the byte stream that is passed to it.
-
    
+
    
 
    SAVING COMPILED PATTERNS
    
-
    
+
    
 Before compiled patterns can be saved they must be serialized, which in PCRE2
 means converting the pattern to a stream of bytes. A single byte stream may
 contain any number of compiled patterns, but they must all use the same
@@ -80,8 +80,8 @@ 
    pcre2serialize man page
    
 in the
 pcre2api
 documentation.
-
    
-
    
+
    
+
    
 The function pcre2_serialize_encode() creates a serialized byte stream
 from a list of compiled patterns. Its first two arguments specify the list,
 being a pointer to a vector of pointers to compiled patterns, and the length of
@@ -100,8 +100,8 @@ 
    pcre2serialize man page
    
 
    • 
 PCRE2_ERROR_BADMAGIC means either that a pattern's code has been corrupted, or
 that a slot in the vector does not point to a compiled pattern.
-
    
-
    
+
    
+
    
 Once a set of patterns has been serialized you can save the data in any
 appropriate manner. Here is sample code that compiles two patterns and writes
 them to a file. It assumes that the variable fd refers to a file that is
@@ -124,17 +124,17 @@ 
    pcre2serialize man page
    
 Note that the serialized data is binary data that may contain any of the 256
 possible byte values. On systems that make a distinction between binary and
 non-binary data, be sure that the file is opened for binary output.
-
    
-
    
+
    
+
    
 Serializing a set of patterns leaves the original data untouched, so they can
 still be used for matching. Their memory must eventually be freed in the usual
 way by calling pcre2_code_free(). When you have finished with the byte
 stream, it too must be freed by calling pcre2_serialize_free(). If this
 function is called with a NULL argument, it returns immediately without doing
 anything.
-
    
+
    
 
    RE-USING PRECOMPILED PATTERNS
    
-
    
+
    
 In order to re-use a set of saved patterns you must first make the serialized
 byte stream available in main memory (for example, by reading from a file). The
 management of this memory block is up to the application. You can use the
@@ -173,8 +173,8 @@ 
    pcre2serialize man page
    PCRE2_ERROR_BADMAGIC may mean that the data is corrupt, or that it was compiled on a system with different endianness. -

    -

    +

    +

    Decoded patterns can be used for matching in the usual way, and must be freed by calling pcre2_code_free(). However, be aware that there is a potential race issue if you are using multiple patterns that were decoded from a single @@ -185,24 +185,24 @@

    pcre2serialize man page

    to call pcre2_code_free() for these patterns in different threads, you must arrange your own locking, and ensure that pcre2_code_free() cannot be called by two threads at the same time. -

    -

    +

    +

    If a pattern was processed by pcre2_jit_compile() before being serialized, the JIT data is discarded and so is no longer available after a save/restore cycle. You can, however, process a restored pattern with pcre2_jit_compile() if you wish. -

    +


    AUTHOR
    -

    +

    Philip Hazel
    Retired from University Computing Service
    Cambridge, England.
    -

    +


    REVISION
    -

    +

    Last updated: 19 January 2024
    Copyright © 1997-2018 University of Cambridge. diff --git a/doc/html/pcre2syntax.html b/doc/html/pcre2syntax.html index 46da3d71f..a7e7a8b7b 100644 --- a/doc/html/pcre2syntax.html +++ b/doc/html/pcre2syntax.html @@ -50,7 +50,7 @@

    pcre2syntax man page

  • REVISION
    PCRE2 REGULAR EXPRESSION SYNTAX SUMMARY
    -

    +

    The full syntax and semantics of the regular expression patterns that are supported by PCRE2 are described in the pcre2pattern @@ -59,9 +59,9 @@

    pcre2syntax man page

    The full description of the latter is in the pcre2api documentation. -

    +


    QUOTING
    -

    +

       \x         where x is non-alphanumeric is a literal x
   \Q...\E    treat enclosed characters as literal
@@ -71,9 +71,9 @@ 
    pcre2syntax man page
    
 that PCRE2's handling of \Q...\E has some differences from Perl's. See the
 pcre2pattern
 documentation for details.
-
    
+
    
 
    BRACED ITEMS
    
-
    
+
    
 With one exception, wherever brace characters { and } are required to enclose
 data for constructions such as \g{2} or \k{name}, space and/or horizontal tab
 characters that follow { or precede } are allowed and are ignored. In the case
@@ -81,9 +81,9 @@ 
    pcre2syntax man page
    
 is \u{...} which is not Perl-compatible and is recognized only when
 PCRE2_EXTRA_ALT_BSUX is set. This is an ECMAScript compatibility feature, and
 follows ECMAScript's behaviour.
-
    
+
    
 
    ESCAPED CHARACTERS
    
-
    
+
    
 This table applies to ASCII and Unicode environments. An unrecognized escape
 sequence causes an error.
 
    @@ -104,8 +104,8 @@ 
    pcre2syntax man page
    
 \N{U+hh..} is synonymous with \x{hh..} but is not supported in environments
 that use EBCDIC code (mainly IBM mainframes). Note that \N not followed by an
 opening curly bracket has a different meaning (see below).
-
    
-
    
+
    
+
    
 If PCRE2_ALT_BSUX or PCRE2_EXTRA_ALT_BSUX is set ("ALT_BSUX mode"), the
 following are also recognized:
 
    @@ -119,8 +119,8 @@ 
    pcre2syntax man page
    
 Likewise, if \u (in ALT_BSUX mode) is not followed by four hexadecimal digits
 or (in EXTRA_ALT_BSUX mode) a sequence of hex digits in curly brackets, it
 matches a literal "u".
-
    
-
    
+
    
+
    
 Note that \0dd is always an octal code. The treatment of backslash followed by
 a non-zero digit is complicated; for details see the section
 "Non-printing characters"
@@ -128,9 +128,9 @@ 
    pcre2syntax man page
    
 pcre2pattern
 documentation, where details of escape processing in EBCDIC environments are
 also given.
-
    
+
    
 
    CHARACTER TYPES
    
-
    
+
    
 
       .          any character except newline;
                in dotall mode, any character whatsoever
@@ -155,8 +155,8 @@ 
    pcre2syntax man page
    
 of a UTF-8 or UTF-16 character. The application can lock out the use of \C by
 setting the PCRE2_NEVER_BACKSLASH_C option. It is also possible to build PCRE2
 with the use of \C permanently disabled.
-
    
-
    
+
    
+
    
 By default, \d, \s, and \w match only ASCII characters, even in UTF-8 mode
 or in the 16-bit and 32-bit libraries. However, if locale-specific matching is
 happening, \s and \w may also match characters with code points in the range
@@ -164,15 +164,15 @@ 
    pcre2syntax man page
    
 sequences is changed to use Unicode properties and they match many more
 characters, but there are some option settings that can restrict individual
 sequences to matching only ASCII characters.
-
    
-
    
+
    
+
    
 Property descriptions in \p and \P are matched caselessly; hyphens,
 underscores, and ASCII white space characters are ignored, in accordance with
 Unicode's "loose matching" rules. For example, \p{Bidi_Class=al} is the same
 as \p{ bidi class = AL }.
-
    
+
    
 
    GENERAL CATEGORY PROPERTIES FOR \p and \P
    
-
    
+
    
 
       C          Other
   Cc         Control
@@ -222,9 +222,9 @@ 
    pcre2syntax man page
    
 
    
 From release 10.45, when caseless matching is set, Ll, Lu, and Lt are all
 equivalent to Lc.
-
    
+
    
 
    PCRE2 SPECIAL CATEGORY PROPERTIES FOR \p and \P
    
-
    
+
    
 
       Xan        Alphanumeric: union of properties L and N
   Xps        POSIX space: property Z or tab, NL, VT, FF, CR
@@ -235,27 +235,27 @@ 
    pcre2syntax man page
    
 
    
 Perl and POSIX space are now the same. Perl added VT to its space character set
 at release 5.18.
-
    
+
    
 
    BINARY PROPERTIES FOR \p AND \P
    
-
    
+
    
 Unicode defines a number of binary properties, that is, properties whose only
 values are true or false. You can obtain a list of those that are recognized by
 \p and \P, along with their abbreviations, by running this command:
 
       pcre2test -LP
-
    
-
    
+
    
+
    
 
    SCRIPT MATCHING WITH \p AND \P
    
-
    
+
    
 Many script names and their 4-letter abbreviations are recognized in
 \p{sc:...} or \p{scx:...} items, or on their own with \p (and also \P of
 course). You can obtain a list of these scripts by running this command:
 
       pcre2test -LS
-
    
-
    
+
    
+
    
 
    THE BIDI_CLASS PROPERTY FOR \p AND \P
    
-
    
+
    
 
       \p{Bidi_Class:<class>}   matches a character with the given class
   \p{BC:<class>}           matches a character with the given class
@@ -285,10 +285,10 @@ 
    pcre2syntax man page
    
   RLO         right-to-left override
   S           segment separator
   WS          white space
-
    
-
    
+
    
+
    
 
    CHARACTER CLASSES
    
-
    
+
    
 
       [...]       positive character class
   [^...]      negative character class
@@ -314,8 +314,8 @@ 
    pcre2syntax man page
    
 In PCRE2, POSIX character set names recognize only ASCII characters by default,
 but some of them use Unicode properties if PCRE2_UCP is set. You can use
 \Q...\E inside a character class.
-
    
-
    
+
    
+
    
 When PCRE2_ALT_EXTENDED_CLASS is set, UTS#18 extended character classes may be
 used, allowing nested character classes, combined using set operators.
 
    @@ -326,10 +326,10 @@ 
    pcre2syntax man page
    
   x--y        set difference (AND NOT)
   x~~y        set symmetric difference (XOR)
 
-
    
-
    
+
    
+
    
 
    PERL EXTENDED CHARACTER CLASSES
    
-
    
+
    
 
       (?[...])                Perl extended character class
   (?[\p{Thai} & \p{Nd}])  operators; whitespace ignored
@@ -352,9 +352,9 @@ 
    pcre2syntax man page
    
 permitted are backslash-escapes, POSIX sets, operators, and parentheses. Inside
 a nested ordinary class, ^ has its usual meaning (inverts the class when used
 as the first character); outside of a nested class, ^ is the XOR operator.
-
    
+
    
 
    QUANTIFIERS
    
-
    
+
    
 
       ?           0 or 1, greedy
   ?+          0 or 1, possessive
@@ -375,10 +375,10 @@ 
    pcre2syntax man page
    
   {,m}        zero up to m, greedy
   {,m}+       zero up to m, possessive
   {,m}?       zero up to m, lazy
-
    
-
    
+
    
+
    
 
    ANCHORS AND SIMPLE ASSERTIONS
    
-
    
+
    
 
       \b          word boundary
   \B          not a word boundary
@@ -393,10 +393,10 @@ 
    pcre2syntax man page
    
                 also before newline at end of subject
   \z          end of subject
   \G          first matching position in subject
-
    
-
    
+
    +


    REPORTED MATCH POINT SETTING
    -

    +

       \K          set reported start of match
    @@ -404,15 +404,15 @@

    pcre2syntax man page

    for compatibility with Perl. However, if the PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK option is set, the previous behaviour is re-enabled. When this option is set, \K is honoured in positive assertions, but ignored in negative ones. -

    +


    ALTERNATION
    -

    +

       expr|expr|expr...
-
    -

    + +


    CAPTURING
    -

    +

       (...)           capture group
   (?<name>...)    named capture group (Perl)
@@ -425,22 +425,22 @@ 
    pcre2syntax man page
    
 In non-UTF modes, names may contain underscores and ASCII letters and digits;
 in UTF modes, any Unicode letters and Unicode decimal digits are permitted. In
 both cases, a name must not start with a digit.
-
    
+
    
 
    ATOMIC GROUPS
    
-
    
+
    
 
       (?>...)         atomic non-capture group
   (*atomic:...)   atomic non-capture group
-
    
-
    
+
    +


    COMMENT
    -

    +

       (?#....)        comment (not nestable)
-
    -

    + +


    OPTION SETTING
    -

    +

    Changes of these options within a group are automatically cancelled at the end of the group. 

    @@ -465,15 +465,15 @@ 
    pcre2syntax man page
    
 (?aP) implies (?aT) as well, though this has no additional effect. However, it
 means that (?-aP) also implies (?-aT) and disables all ASCII restrictions for
 POSIX classes.
-
    
-
    
+
    
+
    
 Unsetting x or xx unsets both. Several options may be set at once, and a
 mixture of setting and unsetting such as (?i-x) is allowed, but there may be
 only one hyphen. Setting (but no unsetting) is allowed after (?^ for example
 (?^in). An option setting may appear at the start of a non-capture group, for
 example (?i:...).
-
    
-
    
+
    
+
    
 The following are recognized only at the very start of a pattern or after one
 of the newline or \R sequences or options with similar syntax. More than one
 of them may appear. For the first three, d is a decimal number.
@@ -497,9 +497,9 @@ 
    pcre2syntax man page
    
 not increase them. LIMIT_RECURSION is an obsolete synonym for LIMIT_DEPTH. The
 application can lock out the use of (*UTF) and (*UCP) by setting the
 PCRE2_NEVER_UTF or PCRE2_NEVER_UCP options, respectively, at compile time.
-
    
+
    
 
    NEWLINE CONVENTION
    
-
    
+
    
 These are recognized only at the very start of the pattern or after option
 settings with a similar syntax.
 
    @@ -509,19 +509,19 @@ 
    pcre2syntax man page
    
   (*ANYCRLF)      all three of the above
   (*ANY)          any Unicode newline sequence
   (*NUL)          the NUL character (binary zero)
-
    
-
    
+
    +


    WHAT \R MATCHES
    -

    +

    These are recognized only at the very start of the pattern or after option setting with a similar syntax. 

       (*BSR_ANYCRLF)  CR, LF, or CRLF
   (*BSR_UNICODE)  any Unicode newline sequence
-
    -

    + +


    LOOKAHEAD AND LOOKBEHIND ASSERTIONS
    -

    +

       (?=...)                     )
   (*pla:...)                  ) positive lookahead
@@ -545,9 +545,9 @@ 
    pcre2syntax man page
    
 pcre2_compile() or defaulted. The default is set when PCRE2 is built
 (ultimate default 255). If every branch matches a fixed number of characters,
 the limit for each branch is 65535 characters.
-
    
+
    
 
    NON-ATOMIC LOOKAROUND ASSERTIONS
    
-
    
+
    
 These assertions are specific to PCRE2 and are not Perl-compatible.
 
       (?*...)                                )
@@ -557,10 +557,10 @@ 
    pcre2syntax man page
    
   (?<*...)                               )
   (*naplb:...)                           ) synonyms
   (*non_atomic_positive_lookbehind:...)  )
-
    
-
    
+
    +


    SUBSTRING SCAN ASSERTION
    -

    +

    This feature is not Perl-compatible. 

       (*scan_substring:(grouplist)...)  scan captured substring
@@ -574,20 +574,20 @@ 
    pcre2syntax man page
    
   <name>  name
   'name'  name
 
-
    -

    + +


    SCRIPT RUNS
    -

    +

       (*script_run:...)           ) script run, can be backtracked into
   (*sr:...)                   )
 
   (*atomic_script_run:...)    ) atomic script run
   (*asr:...)                  )
-
    -

    + +


    BACKREFERENCES
    -

    +

       \n              reference by number (can be ambiguous)
   \gn             reference by number
@@ -601,10 +601,10 @@ 
    pcre2syntax man page
    
   \g{name}        reference by name (Perl)
   \k{name}        reference by name (.NET)
   (?P=name)       reference by name (Python)
-
    -

    + +


    SUBROUTINE REFERENCES (POSSIBLY RECURSIVE)
    -

    +

       (?R)            recurse whole pattern
   (?n)            call subroutine by absolute number
@@ -620,10 +620,10 @@ 
    pcre2syntax man page
    
   \g'+n'          call subroutine by relative number (PCRE2 extension)
   \g<-n>          call subroutine by relative number (PCRE2 extension)
   \g'-n'          call subroutine by relative number (PCRE2 extension)
-
    -

    + +


    CONDITIONAL PATTERNS
    -

    +

       (?(condition)yes-pattern)
   (?(condition)yes-pattern|no-pattern)
@@ -644,9 +644,9 @@ 
    pcre2syntax man page
    
 Note the ambiguity of (?(R) and (?(Rn) which might be named reference
 conditions or recursion tests. Such a condition is interpreted as a reference
 condition if the relevant named group exists.
-
    
+
    
 
    BACKTRACKING CONTROL
    
-
    
+
    
 All backtracking control verbs may be in the form (*VERB:NAME). For (*MARK) the
 name is mandatory, for the others it is optional. (*SKIP) changes its behaviour
 if :NAME is present. The others just set a name for passing back to the caller,
@@ -671,9 +671,9 @@ 
    pcre2syntax man page
    The effect of one of these verbs in a group called as a subroutine is confined to the subroutine call. -

    +


    CALLOUTS
    -

    +

       (?C)            callout (assumed number 0)
   (?Cn)           callout with numerical data n
@@ -682,9 +682,9 @@ 
    pcre2syntax man page
    
 The allowed string delimiters are ` ' " ^ % # $ (which are the same for the
 start and the end), and the starting delimiter { matched with the ending
 delimiter }. To encode the ending delimiter within the string, double it.
-
    
+
    
 
    REPLACEMENT STRINGS
    
-
    
+
    
 If the PCRE2_SUBSTITUTE_LITERAL option is set, a replacement string for
 pcre2_substitute() is not interpreted. Otherwise, by default, the only
 special character is the dollar character in one of the following forms:
@@ -700,8 +700,8 @@ 
    pcre2syntax man page
    For ${n}, n can be a name or a number. If PCRE2_SUBSTITUTE_EXTENDED is set, there is additional interpretation: -

    -

    +

    +

    1. Backslash is an escape character, and the forms described in "ESCAPED CHARACTERS" above are recognized. Also: 

    @@ -719,8 +719,8 @@ 
    pcre2syntax man page
    
 2. The Python form \g<n>, where the angle brackets are part of the syntax and
 n is either a group name or a number, is recognized as an alternative way
 of inserting the contents of a group, for example \g<3>.
-
    
-
    
+
    
+
    
 3. Capture substitution supports the following additional forms:
 
       ${n:-string}             default for unset group
@@ -728,23 +728,23 @@ 
    pcre2syntax man page
    
 
    
 The substitution strings themselves are expanded. Backslash can be used to
 escape colons and closing curly brackets.
-
    
+
    
 
    SEE ALSO
    
-
    
+
    
 pcre2pattern(3), pcre2api(3), pcre2callout(3),
 pcre2matching(3), pcre2(3).
-
    
+
    
 
    AUTHOR
    
-
    
+
    
 Philip Hazel
 
    
 Retired from University Computing Service
 
    
 Cambridge, England.
 
    
-
    
+
    
 
    REVISION
    
-
    
+
    
 Last updated: 27 November 2024
 
    
 Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/html/pcre2test.html b/doc/html/pcre2test.html
index db9073f0e..13356f338 100644
--- a/doc/html/pcre2test.html
+++ b/doc/html/pcre2test.html
@@ -36,7 +36,7 @@ 
    pcre2test man page
    
 
  • REVISION
 
 
    SYNOPSIS
    
-
    
+
    
 pcre2test [options] [input file [output file]]
 
    
 
    
@@ -49,24 +49,24 @@ 
    pcre2test man page
    
 options, see the
 pcre2api
 documentation.
-
    
-
    
+
    
+
    
 The input for pcre2test is a sequence of regular expression patterns and
 subject strings to be matched. There are also command lines for setting
 defaults and controlling some special actions. The output shows the result of
 each match attempt. Modifiers on external or internal command lines, the
 patterns, and the subject lines specify PCRE2 function options, control how the
 subject is processed, and what output is produced.
-
    
-
    
+
    
+
    
 There are many obscure modifiers, some of which are specifically designed for
 use in conjunction with the test script and data files that are distributed as
 part of PCRE2. All the modifiers are documented here, some without much
 justification, but many of them are unlikely to be of use except when testing
 the libraries.
-
    
+
    
 
    PCRE2's 8-BIT, 16-BIT AND 32-BIT LIBRARIES
    
-
    
+
    
 Different versions of the PCRE2 library can be built to support character
 strings that are encoded in 8-bit, 16-bit, or 32-bit code units. One, two, or
 all three of these libraries may be simultaneously installed. The
@@ -75,21 +75,21 @@ 
    pcre2test man page
    
 libraries, patterns and subject strings are converted to 16-bit or 32-bit
 format before being passed to the library functions. Results are converted back
 to 8-bit code units for output.
-
    
-
    
+
    
+
    
 In the rest of this document, the names of library functions and structures
 are given in generic form, for example, pcre2_compile(). The actual
 names used in the libraries have a suffix _8, _16, or _32, as appropriate.
-
    
+
    
 
    INPUT ENCODING
    
-
    
+
    
 Input to pcre2test is processed line by line, either by calling the C
 library's fgets() function, or via the libreadline or libedit
 library. In some Windows environments character 26 (hex 1A) causes an immediate
 end of file, and no further data is read, so this character should be avoided
 unless you really want that action.
-
    
-
    
+
    
+
    
 The input is processed using C's string functions, so must not contain binary
 zeros, even though in Unix-like environments, fgets() treats any bytes
 other than newline as data characters. An error is generated if a binary zero
@@ -98,11 +98,11 @@ 
    pcre2test man page
    
 the library for matching. For patterns, there is a facility for specifying some
 or all of the 8-bit input characters as hexadecimal pairs, which makes it
 possible to include binary zeros.
-
    
+
    
 
    
 Input for the 16-bit and 32-bit libraries
 
    
-
    
+
    
 When testing the 16-bit or 32-bit libraries, there is a need to be able to
 generate character code points greater than 255 in the strings that are passed
 to the library. For subject lines and some patterns, backslash escapes can be
@@ -110,8 +110,8 @@ 
    pcre2test man page
    
 "Setting compilation options"
 below) is set, the pattern and any following subject lines are interpreted as
 UTF-8 strings and translated to UTF-16 or UTF-32 as appropriate.
-
    
-
    
+
    
+
    
 For non-UTF testing of wide characters, the utf8_input modifier can be
 used. This is mutually exclusive with utf, and is allowed only in 16-bit
 or 32-bit mode. It causes the pattern and following subject lines to be treated
@@ -119,58 +119,58 @@ 
    pcre2test man page
    
 character values up to 0x7fffffff. Each character is placed in one 16-bit or
 32-bit code unit (in the 16-bit case, values greater than 0xffff cause an error
 to occur).
-
    
-
    
+
    
+
    
 UTF-8 (in its original definition) is not capable of encoding values greater
 than 0x7fffffff, but such values can be handled by the 32-bit library. When
 testing this library in non-UTF mode with utf8_input set, if any
 character is preceded by the byte 0xff (which is an invalid byte in UTF-8)
 0x80000000 is added to the character's value. For subject strings, using an
 escape sequence is preferable.
-
    
+
    
 
    COMMAND LINE OPTIONS
    
-
    
+
    
 -8
 If the 8-bit library has been built, this option causes it to be used (this is
 the default). If the 8-bit library has not been built, this option causes an
 error.
-
    
-
    
+
    
+
    
 -16
 If the 16-bit library has been built, this option causes it to be used. If the
 8-bit library has not been built, this is the default. If the 16-bit library
 has not been built, this option causes an error.
-
    
-
    
+
    
+
    
 -32
 If the 32-bit library has been built, this option causes it to be used. If no
 other library has been built, this is the default. If the 32-bit library has
 not been built, this option causes an error.
-
    
-
    
+
    
+
    
 -ac
 Behave as if each pattern has the auto_callout modifier, that is, insert
 automatic callouts into every pattern that is compiled.
-
    
-
    
+
    
+
    
 -AC
 As for -ac, but in addition behave as if each subject line has the
 callout_extra modifier, that is, show additional information from
 callouts.
-
    
-
    
+
    
+
    
 -b
 Behave as if each pattern has the fullbincode modifier; the full
 internal binary form of the pattern is output after compilation.
-
    
-
    
+
    
+
    
 -C
 Output the version number of the PCRE2 library, and all available information
 about the optional features that are included, and then exit with zero exit
 code. All other options are ignored. If both -C and -LM are present, whichever
 is first is recognized.
-
    
-
    
+
    
+
    
 -C option
 Output information about a specific build-time option, then exit. This
 functionality is intended for use in scripts such as RunTest. The
@@ -211,89 +211,89 @@ 
    pcre2test man page
    
   3  Unexpected return from test call to pcre2_jit_compile()
    • If an unknown option is given, an error message is output; the exit code is 0. -

    -

    +

    +

    -d Behave as if each pattern has the debug modifier; the internal form and information about the compiled pattern is output after compilation; -d is equivalent to -b -i. -

    -

    +

    +

    -dfa Behave as if each subject line has the dfa modifier; matching is done using the pcre2_dfa_match() function instead of the default pcre2_match(). -

    -

    +

    +

    -error number[,number,...] Call pcre2_get_error_message() for each of the error numbers in the comma-separated list, display the resulting messages on the standard output, then exit with zero exit code. The numbers may be positive or negative. This is a convenience facility for PCRE2 maintainers. -

    -

    +

    +

    -help Output a brief summary these options and then exit. -

    -

    +

    +

    -i Behave as if each pattern has the info modifier; information about the compiled pattern is given after compilation. -

    -

    +

    +

    -jit Behave as if each pattern line has the jit modifier; after successful compilation, each pattern is passed to the just-in-time compiler, if available. -

    -

    +

    +

    -jitfast Behave as if each pattern line has the jitfast modifier; after successful compilation, each pattern is passed to the just-in-time compiler, if available, and each subject line is passed directly to the JIT matcher via its "fast path". -

    -

    +

    +

    -jitverify Behave as if each pattern line has the jitverify modifier; after successful compilation, each pattern is passed to the just-in-time compiler, if available, and the use of JIT for matching is verified. -

    -

    +

    +

    -LM List modifiers: write a list of available pattern and subject modifiers to the standard output, then exit with zero exit code. All other options are ignored. If both -C and any -Lx options are present, whichever is first is recognized. -

    -

    +

    +

    -LP List properties: write a list of recognized Unicode properties to the standard output, then exit with zero exit code. All other options are ignored. If both -C and any -Lx options are present, whichever is first is recognized. -

    -

    +

    +

    -LS List scripts: write a list of recognized Unicode script names to the standard output, then exit with zero exit code. All other options are ignored. If both -C and any -Lx options are present, whichever is first is recognized. -

    -

    +

    +

    -pattern modifier-list Behave as if each pattern line contains the given modifiers. -

    -

    +

    +

    -q Do not output the version number of pcre2test at the start of execution. -

    -

    +

    +

    -S size On Unix-like systems, set the size of the run-time stack to size mebibytes (units of 1024*1024 bytes). -

    -

    +

    +

    -subject modifier-list Behave as if each subject line contains the given modifiers. -

    -

    +

    +

    -t Run each compile and match many times with a timer, and output the resulting times per compile or match. When JIT is used, separate times are given for the @@ -301,37 +301,37 @@

    pcre2test man page

    that are used for timing by following -t with a number (as a separate item on the command line). For example, "-t 1000" iterates 1000 times. The default is to iterate 500,000 times. -

    -

    +

    +

    -tm This is like -t except that it times only the matching phase, not the compile phase. -

    -

    +

    +

    -T -TM These behave like -t and -tm, but in addition, at the end of a run, the total times for all compiles and matches are output. -

    -

    +

    +

    -version Output the PCRE2 version number and then exit. -

    +


    DESCRIPTION
    -

    +

    If pcre2test is given two filename arguments, it reads from the first and writes to the second. If the first name is "-", input is taken from the standard input. If pcre2test is given only one argument, it reads from that file and writes to stdout. Otherwise, it reads from stdin and writes to stdout. -

    -

    +

    +

    When pcre2test is built, a configuration option can specify that it should be linked with the libreadline or libedit library. When this is done, if the input is from a terminal, it is read using the readline() function. This provides line-editing and history facilities. The output from the -help option states whether or not readline() will be used. -

    -

    +

    +

    The program handles any number of tests, each of which consists of a set of input lines. Each set starts with a regular expression pattern, followed by any number of subject lines to be matched against that pattern. In between sets of @@ -340,14 +340,14 @@

    pcre2test man page

    is distributed with PCRE2 as a means of checking that the behaviour of PCRE2 and Perl is the same. For a specification of perltest.sh, see the comments near its beginning. See also the #perltest command below. -

    -

    +

    +

    When the input is a terminal, pcre2test prompts for each line of input, using "re>" to prompt for regular expression patterns, and "data>" to prompt for subject lines. Command lines starting with # can be entered only in response to the "re>" prompt. -

    -

    +

    +

    Each subject line is matched separately and independently. If you want to do multi-line matches, you have to use the \n escape sequence (or \r or \r\n, etc., depending on the newline setting) in a single line of input to encode the @@ -355,14 +355,14 @@

    pcre2test man page

    buffer is automatically extended if it is too small. There are replication features that makes it possible to generate long repetitive pattern or subject lines without having to supply them explicitly. -

    -

    +

    +

    An empty line or the end of the file signals the end of the subject lines for a test, at which point a new pattern or command line is expected if there is still input to be read. -

    +


    COMMAND LINES
    -

    +

    In between sets of test data, a line that begins with # is interpreted as a command line. If the first character is followed by white space or an exclamation mark, the line is treated as a comment, and ignored. Otherwise, the @@ -376,8 +376,8 @@

    pcre2test man page

    an error if a subsequent pattern contains any occurrences of \P, \p, or \X, which are still supported when PCRE2_UTF is not set, but which require Unicode property support to be included in the library. -

    -

    +

    +

    This is a trigger guard that is used in test files to ensure that UTF or Unicode property tests are not accidentally added to files that are used when Unicode support is not included in the library. Setting PCRE2_NEVER_UTF and @@ -407,8 +407,8 @@

    pcre2test man page

    conventions, but the majority of the tests expect a single linefeed to be recognized as a newline by default. Without special action the tests would fail when PCRE2 is compiled with either CR or CRLF as the default newline. -

    -

    +

    +

    The #newline_default command specifies a list of newline types that are acceptable as the default. The types must be one of CR, LF, CRLF, ANYCRLF, ANY, or NUL (in upper or lower case), for example: @@ -421,8 +421,8 @@

    pcre2test man page

    pattern that does not already have a newline modifier. If the newline list is empty, the feature is turned off. This command is present in a number of the standard test input files. -

    -

    +

    +

    When the POSIX API is being tested there is no way to override the default newline convention, though it is possible to set the newline convention from within the pattern. A warning is given if the posix or posix_nosub @@ -440,8 +440,8 @@

    pcre2test man page

    to confirm that Perl gives the same results as PCRE2. Subsequent tests are checked for the use of pcre2test features that are incompatible with the perltest.sh script. -

    -

    +

    +

    Patterns must use '/' as their delimiter, and only certain modifiers are supported. Comment lines, #pattern commands, and #subject commands that set or unset "mark" are recognized and acted on. The #perltest, #forbid_utf, and @@ -468,9 +468,9 @@

    pcre2test man page

    This command sets a default modifier list that applies to all subsequent subject lines. Modifiers on a subject line can change these settings. -

    +


    MODIFIER SYNTAX
    -

    +

    Modifier lists are used with both pattern and subject lines. Items in a list are separated by commas followed by optional white space. Trailing whitespace in a modifier list is ignored. Some modifiers may be given for both patterns @@ -479,8 +479,8 @@

    pcre2test man page

    followed by an equals sign and a value, for example, "offset=12". Values cannot contain comma characters, but may contain spaces. Modifiers that do not take values may be preceded by a minus sign to turn off a previous setting. -

    -

    +

    +

    A few of the more common modifiers can also be specified as single letters, for example "i" for "caseless". In documentation, following the Perl convention, these are written with a slash ("the /i modifier") for clarity. Abbreviated @@ -492,9 +492,9 @@

    pcre2test man page

    This is a pattern line whose modifier list starts with two one-letter modifiers (/i and /g). The lower-case abbreviated modifiers are the same as used in Perl. -

    +


    PATTERN SYNTAX
    -

    +

    A pattern line must start with one of the following characters (common symbols, excluding pattern meta-characters): 

    @@ -524,12 +524,12 @@ 
    pcre2test man page
    is interpreted as the first line of a pattern that starts with "abc/", causing pcre2test to read the next line as a continuation of the regular expression. -

    -

    +

    +

    A pattern can be followed by a modifier list (details below). -

    +


    SUBJECT LINE SYNTAX
    -

    +

    Before each subject line is passed to pcre2_match(), pcre2_dfa_match(), or pcre2_jit_match(), leading and trailing white space is removed, and the line is scanned for backslash escapes, unless the @@ -558,8 +558,8 @@

    pcre2test man page

    hexadecimal digits inside the braces; invalid values provoke error messages but when using \N{U+hh...} with some invalid unicode characters they will be accepted with a warning instead. -

    -

    +

    +

    Note that even in UTF-8 mode, \xhh (and depending of how large, \ddd) describe one byte rather than one character; this makes it possible to construct invalid UTF-8 sequences for testing purposes. On the other hand, @@ -568,18 +568,18 @@

    pcre2test man page

    it is preferred to use \N{U+hh...} when describing characters. When testing the 8-bit library not in UTF-8 mode, \x{hh} generates one byte for values that could fit on it, and causes an error for greater values. -

    -

    +

    +

    When testing the 16-bit library, not in UTF-16 mode, all 4-digit \x{hhhh} values are accepted. This makes it possible to construct invalid UTF-16 sequences for testing purposes. -

    -

    +

    +

    When testing the 32-bit library, not in UTF-32 mode, all 4 to 8-digit \x{...} values are accepted. This makes it possible to construct invalid UTF-32 sequences for testing purposes. -

    -

    +

    +

    There is a special backslash sequence that specifies replication of one or more characters: 

    @@ -592,8 +592,8 @@ 
    pcre2test man page
    is converted to "abcabcabcabc". This feature does not support nesting. To include a closing square bracket in the characters, code it as \x5D. -

    -

    +

    +

    A backslash followed by an equals sign marks the end of the subject string and the start of a modifier list. For example: 

    @@ -610,24 +610,24 @@ 
    pcre2test man page
    
 the very last character in the line is a backslash (and there is no modifier
 list), it is ignored. This gives a way of passing an empty line as data, since
 a real empty line terminates the data input.
-
    
-
    
+
    
+
    
 If the subject_literal modifier is set for a pattern, all subject lines
 that follow are treated as literals, with no special treatment of backslashes.
 No replication is possible, and any subject modifiers must be set as defaults
 by a #subject command.
-
    
+
    
 
    PATTERN MODIFIERS
    
-
    
+
    
 There are several types of modifier that can appear in pattern lines. Except
 where noted below, they may also be used in #pattern commands. A
 pattern's modifier list can add to or override default modifiers that were set
 by a previous #pattern command.
-
    
+
    
 
    
 Setting compilation options
 
    
-
    
+
    
 The following modifiers set options for pcre2_compile(). Most of them set
 bits in the options argument of that function, but those whose names start with
 PCRE2_EXTRA are additional options that are set in the compile context.
@@ -711,11 +711,11 @@ 
    pcre2test man page
    
 See the
 pcre2_set_optimize
 documentation for details on these optimizations.
-
    
+
    
 
    
 Setting compilation controls
 
    
-
    
+
    
 The following modifiers affect the compilation process or request information
 about the pattern. There are single-letter abbreviations for some that are
 heavily used in the test files.
@@ -758,41 +758,41 @@ 
    pcre2test man page
    
       utf8_input                treat input as UTF-8
    The effects of these modifiers are described in the following sections. -

    +


    Newline and \R handling
    -

    +

    The bsr modifier specifies what \R in a pattern should match. If it is set to "anycrlf", \R matches CR, LF, or CRLF only. If it is set to "unicode", \R matches any Unicode newline sequence. The default can be specified when PCRE2 is built; if it is not, the default is set to Unicode. -

    -

    +

    +

    The newline modifier specifies which characters are to be interpreted as newlines, both in the pattern and in subject lines. The type must be one of CR, LF, CRLF, ANYCRLF, ANY, or NUL (in upper or lower case). -

    +


    Information about a pattern
    -

    +

    The debug modifier is a shorthand for info,fullbincode, requesting all available information. -

    -

    +

    +

    The bincode modifier causes a representation of the compiled code to be output after compilation. This information does not contain length and offset values, which ensures that the same output is generated for different internal link sizes and different code unit widths. By using bincode, the same regression tests can be used in different environments. -

    -

    +

    +

    The fullbincode modifier, by contrast, does include length and offset values. This is used in a few special tests that run only for specific code unit widths and link sizes, and is also useful for one-off tests. -

    -

    +

    +

    The info modifier requests information about the compiled pattern (whether it is anchored, has a fixed first character, and so on). The information is obtained from the pcre2_pattern_info() function. Here are @@ -823,42 +823,42 @@

    pcre2test man page

    ending code units are recorded. The subject length line is omitted when no_start_optimize is set because the minimum length is not calculated when it can never be used. -

    -

    +

    +

    The framesize modifier shows the size, in bytes, of each storage frame used by pcre2_match() for handling backtracking. The size depends on the number of capturing parentheses in the pattern. A vector of these frames is used at matching time; its overall size is shown when the heaframes_size subject modifier is set. -

    -

    +

    +

    The callout_info modifier requests information about all the callouts in the pattern. A list of them is output at the end of any other information that is requested. For each callout, either its number or string is given, followed by the item that follows it in the pattern. -

    +


    Passing a NULL context
    -

    +

    Normally, pcre2test passes a context block to pcre2_compile(). If the null_context modifier is set, however, NULL is passed. This is for testing that pcre2_compile() behaves correctly in this case (it uses default values). -

    +


    Passing a NULL pattern
    -

    +

    The null_pattern modifier is for testing the behaviour of pcre2_compile() when the pattern argument is NULL. The length value passed is the default PCRE2_ZERO_TERMINATED unless use_length is set. Any length other than zero causes an error. -

    +


    Specifying pattern characters in hexadecimal
    -

    +

    The hex modifier specifies that the characters of the pattern, except for substrings enclosed in single or double quotes, are to be interpreted as pairs of hexadecimal digits. This feature is provided as a way of creating patterns @@ -876,37 +876,37 @@

    pcre2test man page

    Either single or double quotes may be used. There is no way of including the delimiter within a substring. The hex and expand modifiers are mutually exclusive. -

    +


    Specifying the pattern's length
    -

    +

    By default, patterns are passed to the compiling functions as zero-terminated strings but can be passed by length instead of being zero-terminated. The use_length modifier causes this to happen. Using a length happens automatically (whether or not use_length is set) when hex is set, because patterns specified in hexadecimal may contain binary zeros. -

    -

    +

    +

    If hex or use_length is used with the POSIX wrapper API (see "Using the POSIX wrapper API" below), the REG_PEND extension is used to pass the pattern's length. -

    +


    Specifying a maximum for variable lookbehinds
    -

    +

    Variable lookbehind assertions are supported only if, for each one, there is a maximum length (in characters) that it can match. There is a limit on this, whose default can be set at build time, with an ultimate default of 255. The max_varlookbehind modifier uses the pcre2_set_max_varlookbehind() function to change the limit. Lookbehinds whose branches each match a fixed length are limited to 65535 characters per branch. -

    +


    Specifying wide characters in 16-bit and 32-bit modes
    -

    +

    In 16-bit and 32-bit modes, all input is automatically treated as UTF-8 and translated to UTF-16 or UTF-32 when the utf modifier is set. For testing the 16-bit and 32-bit libraries in non-UTF mode, the utf8_input modifier @@ -915,11 +915,11 @@

    pcre2test man page

    given in "Input encoding" above. -

    +


    Generating long repetitive patterns
    -

    +

    Some tests use long patterns that are very repetitive. Instead of creating a very long input line for such a pattern, you can use a special repetition feature, similar to the one described for subject lines above. If the @@ -934,21 +934,21 @@

    pcre2test man page

    by decimal digits and "}" is found later in the pattern. If not, the characters remain in the pattern unaltered. The expand and hex modifiers are mutually exclusive. -

    -

    +

    +

    If part of an expanded pattern looks like an expansion, but is really part of the actual pattern, unwanted expansion can be avoided by giving two values in the quantifier. For example, \[AB]{6000,6000} is not recognized as an expansion item. -

    -

    +

    +

    If the info modifier is set on an expanded pattern, the result of the expansion is included in the information that is output. -

    +


    JIT compilation
    -

    +

    Just-in-time (JIT) compiling is a heavyweight optimization that can greatly speed up pattern matching. See the pcre2jit @@ -960,8 +960,8 @@

    pcre2test man page

    modifier in "Subject Modifiers" below for details of how these options are specified for each match attempt. -

    -

    +

    +

    JIT compilation is requested by the jit pattern modifier, which may optionally be followed by an equals sign and a number in the range 0 to 7. The three bits that make up the number specify which of the three JIT operating @@ -989,34 +989,34 @@

    pcre2test man page

    matching (for example, jit=2) but do not set the partial modifier on a subject line, that match will not use JIT code because none was compiled for non-partial matching. -

    -

    +

    +

    If JIT compilation is successful, the compiled JIT code will automatically be used when an appropriate type of match is run, except when incompatible run-time options are specified. For more details, see the pcre2jit documentation. See also the jitstack modifier below for a way of setting the size of the JIT stack. -

    -

    +

    +

    If the jitfast modifier is specified, matching is done using the JIT "fast path" interface, pcre2_jit_match(), which skips some of the sanity checks that are done by pcre2_match(), and of course does not work when JIT is not supported. If jitfast is specified without jit, jit=7 is assumed. -

    -

    +

    +

    If the jitverify modifier is specified, information about the compiled pattern shows whether JIT compilation was or was not successful. If jitverify is specified without jit, jit=7 is assumed. If JIT compilation is successful when jitverify is set, the text "(JIT)" is added to the first output line after a match or non match when JIT-compiled code was actually used in the match. -

    +


    Setting a locale
    -

    +

    The locale modifier must specify the name of a locale, for example: 

       /pattern/locale=fr_FR
@@ -1028,11 +1028,11 @@ 
    pcre2test man page
    
 applies only to the pattern on which it appears, but can be given in a
 #pattern command if a default is needed. Setting a locale and alternate
 character tables are mutually exclusive.
-
    
+
    
 
    
 Showing pattern memory
 
    
-
    
+
    
 The memory modifier causes the size in bytes of the memory used to hold
 the compiled pattern to be output. This does not include the size of the
 pcre2_code block; it is just the actual compiled data. If the pattern is
@@ -1043,40 +1043,40 @@ 
    pcre2test man page
    
   Memory allocation (code space): 21
   Memory allocation (JIT code): 1910
 
-
    -

    + +


    Limiting nested parentheses
    -

    +

    The parens_nest_limit modifier sets a limit on the depth of nested parentheses in a pattern. Breaching the limit causes a compilation error. The default for the library is set when PCRE2 is built, but pcre2test sets its own default of 220, which is required for running the standard test suite. -

    +


    Limiting the pattern length
    -

    +

    The max_pattern_length modifier sets a limit, in code units, to the length of pattern that pcre2_compile() will accept. Breaching the limit causes a compilation error. The default is the largest number a PCRE2_SIZE variable can hold (essentially unlimited). -

    +


    Limiting the size of a compiled pattern
    -

    +

    The max_pattern_compiled_length modifier sets a limit, in bytes, to the amount of memory used by a compiled pattern. Breaching the limit causes a compilation error. The default is the largest number a PCRE2_SIZE variable can hold (essentially unlimited). -

    +


    Using the POSIX wrapper API
    -

    +

    The posix and posix_nosub modifiers cause pcre2test to call PCRE2 via the POSIX wrapper API rather than its native API. When posix_nosub is used, the POSIX option REG_NOSUB is passed to @@ -1101,21 +1101,21 @@

    pcre2test man page

    This provides a means of testing the behaviour of regerror() when the buffer is too small for the error message. If this modifier has not been set, a large buffer is used. -

    -

    +

    +

    The aftertext and allaftertext subject modifiers work as described below. All other modifiers are either ignored, with a warning message, or cause an error. -

    -

    +

    +

    The pattern is passed to regcomp() as a zero-terminated string by default, but if the use_length or hex modifiers are set, the REG_PEND extension is used to pass it by length. -

    +


    Testing the stack guard feature
    -

    +

    The stackguard modifier is used to test the use of pcre2_set_compile_recursion_guard(), a function that is provided to enable stack availability to be checked during compilation (see the @@ -1126,11 +1126,11 @@

    pcre2test man page

    receives is the current nesting parenthesis depth; if this is greater than the value given by the modifier, non-zero is returned, causing the compilation to be aborted. -

    +


    Using alternative character tables
    -

    +

    The value specified for the tables modifier must be one of the digits 0, 1, 2, or 3. It causes a specific set of built-in character tables to be passed to pcre2_compile(). This is used in the PCRE2 tests to check behaviour @@ -1146,11 +1146,11 @@

    pcre2test man page

    letters, digits, spaces, etc. Tables 3 can be used only after a #loadtables command has loaded them from a binary file. Setting alternate character tables and a locale are mutually exclusive. -

    +


    Setting certain match controls
    -

    +

    The following modifiers are really subject modifiers, and are described under "Subject Modifiers" below. However, they may be included in a pattern's modifier list, in which case they are applied to every subject line that is @@ -1183,20 +1183,20 @@

    pcre2test man page

    These modifiers may not appear in a #pattern command. If you want them as defaults, set them in a #subject command. -

    +


    Specifying literal subject lines
    -

    +

    If the subject_literal modifier is present on a pattern, all the subject lines that it matches are taken as literal strings, with no interpretation of backslashes. It is not possible to set subject modifiers on such lines, but any that are set as defaults by a #subject command are recognized. -

    +


    Saving a compiled pattern
    -

    +

    When a pattern with the push modifier is successfully compiled, it is pushed onto a stack of compiled patterns, and pcre2test expects the next line to contain a new pattern (or a command) instead of a subject line. This @@ -1213,11 +1213,11 @@

    pcre2test man page

    replace, which causes an error. Note that jitverify, which is allowed, does not carry through to any subsequent matching that uses a stacked pattern. -

    +


    Testing foreign pattern conversion
    -

    +

    The experimental foreign pattern conversion functions in PCRE2 can be tested by setting the convert modifier. Its argument is a colon-separated list of options, which set the equivalent option for the pcre2_pattern_convert() @@ -1237,27 +1237,27 @@

    pcre2test man page

    normal utf and no_utf_check options, if set, cause the PCRE2_CONVERT_UTF and PCRE2_CONVERT_NO_UTF_CHECK options to be passed to pcre2_pattern_convert(). -

    -

    +

    +

    By default, the conversion function is allowed to allocate a buffer for its output. However, if the convert_length modifier is set to a value greater than zero, pcre2test passes a buffer of the given length. This makes it possible to test the length check. -

    -

    +

    +

    The convert_glob_escape and convert_glob_separator modifiers can be used to specify the escape and separator characters for glob processing, overriding the defaults, which are operating-system dependent. -

    +


    SUBJECT MODIFIERS
    -

    +

    The modifiers that can appear in subject lines and the #subject command are of two types. -

    +


    Setting match options
    -

    +

    The following modifiers set options for pcre2_match() or pcre2_dfa_match(). See pcre2api @@ -1280,15 +1280,15 @@

    pcre2test man page

    The partial matching modifiers are provided with abbreviations because they appear frequently in tests. -

    -

    +

    +

    If the posix or posix_nosub modifier was present on the pattern, causing the POSIX wrapper API to be used, the only option-setting modifiers that have any effect are notbol, notempty, and noteol, causing REG_NOTBOL, REG_NOTEMPTY, and REG_NOTEOL, respectively, to be passed to regexec(). The other modifiers are ignored, with a warning message. -

    -

    +

    +

    There is one additional modifier that can be used with the POSIX wrapper. It is ignored (with a warning) if used for non-POSIX matching. 

    @@ -1302,11 +1302,11 @@ 
    pcre2test man page
    
 documentation. If the subject string contains binary zeros (coded as escapes
 such as \x{00} because pcre2test does not support actual binary zeros in
 its input), you must use posix_startend to specify its length.
-
    
+
    
 
    
 Setting match controls
 
    
-
    
+
    
 The following modifiers affect the matching process or request additional
 information. Some of them may also be specified on a pattern line (see above),
 in which case they apply to every subject line that is matched against that
@@ -1366,11 +1366,11 @@ 
    pcre2test man page
    
 matching via the POSIX wrapper API, the aftertext, allaftertext,
 and ovector subject modifiers work as described below. All other
 modifiers are either ignored, with a warning message, or cause an error.
-
    
+
    
 
    
 Showing more text
 
    
-
    
+
    
 The aftertext modifier requests that as well as outputting the part of
 the subject string that matched the entire pattern, pcre2test should in
 addition output the remainder of the subject string. This is useful for tests
@@ -1378,8 +1378,8 @@ 
    pcre2test man page
    
 allaftertext modifier requests the same action for captured substrings as
 well as the main matched substring. In each case the remainder is output on the
 following line with a plus character following the capture number.
-
    
-
    
+
    
+
    
 The allusedtext modifier requests that all the text that was consulted
 during a successful pattern match by the interpreter should be shown, for both
 full and partial matches. This feature is not supported for JIT matching, and
@@ -1402,8 +1402,8 @@ 
    pcre2test man page
    
 preceding and following strings "pqr" and "xyz" having been consulted during
 the match (when processing the assertions). The partial match can indicate only
 the preceding string.
-
    
-
    
+
    
+
    
 The startchar modifier requests that the starting character for the match
 be indicated, if it is different to the start of the matched string. The only
 time when this occurs is when \K has been processed as part of the match. In
@@ -1418,11 +1418,11 @@ 
    pcre2test man page
    Unlike allusedtext, the startchar modifier can be used with JIT. However, these two modifiers are mutually exclusive. -

    +


    Showing the value of all capture groups
    -

    +

    The allcaptures modifier requests that the values of all potential captured parentheses be output after a match. By default, only those up to the highest one actually used in the match are output (corresponding to the return @@ -1430,11 +1430,11 @@

    pcre2test man page

    are output as "<unset>". This modifier is not relevant for DFA matching (which does no capturing) and does not apply when replace is specified; it is ignored, with a warning message, if present. -

    +


    Showing the entire ovector, for all outcomes
    -

    +

    The allvector modifier requests that the entire ovector be shown, whatever the outcome of the match. Compare allcaptures, which shows only up to the maximum number of capture groups for the pattern, and then only for a @@ -1447,11 +1447,11 @@

    pcre2test man page

    cases it applies to the entire ovector. After a partial match, the first two elements are the only ones that should be set. After a DFA match, the amount of ovector that is used depends on the number of matches that were found. -

    +


    Testing pattern callouts
    -

    +

    A callout function is supplied when pcre2test calls the library matching functions, unless callout_none is specified. Its behaviour can be controlled by various modifiers listed above whose names begin with @@ -1460,11 +1460,11 @@

    pcre2test man page

    Testing callouts from pcre2_substitute() is described separately in "Testing the substitution function" below. -

    +


    Finding all matches in a string
    -

    +

    Searching for all possible matches within a subject can be requested by the global or altglobal modifier. After finding a match, the matching function is called again to search the remainder of the subject. The difference @@ -1474,8 +1474,8 @@

    pcre2test man page

    does), whereas the latter passes over a shortened subject. This makes a difference to the matching process if the pattern begins with a lookbehind assertion (including \b or \B). -

    -

    +

    +

    If an empty string is matched, the next match is done with the PCRE2_NOTEMPTY_ATSTART and PCRE2_ANCHORED flags set, in order to search for another, non-empty, match at the same point in the subject. If this match @@ -1484,11 +1484,11 @@

    pcre2test man page

    the split() function. Normally, the start offset is advanced by one character, but if the newline convention recognizes CRLF as a newline, and the current character is CR followed by LF, an advance of two characters occurs. -

    +


    Testing substring extraction functions
    -

    +

    The copy and get modifiers can be used to test the pcre2_substring_copy_xxx() and pcre2_substring_get_xxx() functions. They can be given more than once, and each can specify a capture group name or @@ -1499,43 +1499,43 @@

    pcre2test man page

    If the #subject command is used to set default copy and/or get lists, these can be unset by specifying a negative number to cancel all numbered groups and an empty name to cancel all named groups. -

    -

    +

    +

    The getall modifier tests pcre2_substring_list_get(), which extracts all captured substrings. -

    -

    +

    +

    If the subject line is successfully matched, the substrings extracted by the convenience functions are output with C, G, or L after the string number instead of a colon. This is in addition to the normal full list. The string length (that is, the return from the extraction function) is given in parentheses after each substring, followed by the name when the extraction was by name. -

    +


    Testing the substitution function
    -

    +

    If the replace modifier is set, the pcre2_substitute() function is called instead of one of the matching functions (or after one call of pcre2_match() in the case of PCRE2_SUBSTITUTE_MATCHED). Note that replacement strings cannot contain commas, because a comma signifies the end of a modifier. This is not thought to be an issue in a test program. -

    -

    +

    +

    Specifying a completely empty replacement string disables this modifier. However, it is possible to specify an empty replacement by providing a buffer length, as described below, for an otherwise empty replacement. -

    -

    +

    +

    Unlike subject strings, pcre2test does not process replacement strings for escape sequences. In UTF mode, a replacement string is checked to see if it is a valid UTF-8 string. If so, it is correctly converted to a UTF string of the appropriate code unit width. If it is not a valid UTF-8 string, the individual code units are copied directly. This provides a means of passing an invalid UTF-8 string for testing purposes. -

    -

    +

    +

    The following modifiers set options (in additional to the normal match options) for pcre2_substitute(): 

    @@ -1551,8 +1551,8 @@ 
    pcre2test man page
    
 See the
 pcre2api
 documentation for details of these options.
-
    
-
    
+
    
+
    
 After a successful substitution, the modified string is output, preceded by the
 number of replacements. This may be zero if there were no matches. Here is a
 simple example of a substitution test:
@@ -1592,11 +1592,11 @@ 
    pcre2test man page
    
 A replacement string is ignored with POSIX and DFA matching. Specifying partial
 matching provokes an error return ("bad option value") from
 pcre2_substitute().
-
    
+
    
 
    
 Testing substitute callouts
 
    
-
    
+
    
 If the substitute_callout modifier is set, a substitution callout
 function is set up. The null_context modifier must not be set, because
 the address of the callout function is passed in a match context. When the
@@ -1614,8 +1614,8 @@ 
    pcre2test man page
    
 is, one more than the number of capturing groups that were set). Then are
 listed the offsets of the old substring, its contents, and the same for the
 replacement.
-
    
-
    
+
    
+
    
 By default, the substitution callout function returns zero, which accepts the
 replacement and causes matching to continue if /g was used. Two further
 modifiers can be used to test other return values. If substitute_skip is
@@ -1635,26 +1635,26 @@ 
    pcre2test man page
    If both are set for the same number, stop takes precedence. Only a single skip or stop is supported, which is sufficient for testing that the feature works. -

    +


    Testing substitute case callouts
    -

    +

    If the substitute_case_callout modifier is set, a substitution case callout function is set up. The callout function is called for each substituted chunk which is to be case-transformed. -

    -

    +

    +

    The callout function passed is a fixed function with implementation for certain behaviours: inputs which shrink when case-transformed; inputs which grow; inputs with distinct upper/lower/titlecase forms. The characters which are not special-cased for testing purposes are left unmodified, as if they are caseless characters. -

    +


    Setting the JIT stack size
    -

    +

    The jitstack modifier provides a way of setting the maximum stack size that is used by the just-in-time optimization code. It is ignored if JIT optimization is not being used. The value is a number of kibibytes (units of @@ -1662,19 +1662,19 @@

    pcre2test man page

    that is larger than the default is necessary only for very complicated patterns. If jitstack is set non-zero on a subject line it overrides any value that was set on the pattern. -

    +


    Setting heap, match, and depth limits
    -

    +

    The heap_limit, match_limit, and depth_limit modifiers set the appropriate limits in the match context. These values are ignored when the find_limits or find_limits_noheap modifier is specified. -

    +


    Finding minimum limits
    -

    +

    If the find_limits modifier is present on a subject line, pcre2test calls the relevant matching function several times, setting different values in the match context via pcre2_set_heap_limit(), @@ -1685,22 +1685,22 @@

    pcre2test man page

    standard tests, because the minimum heap limit varies between systems. If JIT is being used, only the match limit is relevant, and the other two are automatically omitted. -

    -

    +

    +

    When using this modifier, the pattern should not contain any limit settings such as (*LIMIT_MATCH=...) within it. If such a setting is present and is lower than the minimum matching value, the minimum value cannot be found because pcre2_set_match_limit() etc. are only able to reduce the value of an in-pattern limit; they cannot increase it. -

    -

    +

    +

    For non-DFA matching, the minimum depth_limit number is a measure of how much nested backtracking happens (that is, how deeply the pattern's tree is searched). In the case of DFA matching, depth_limit controls the depth of recursive calls of the internal function that is used for handling pattern recursion, lookaround assertions, and atomic groups. -

    -

    +

    +

    For non-DFA matching, the match_limit number is a measure of the amount of backtracking that takes place, and learning the minimum value can be instructive. For most simple matches, the number is quite small, but for @@ -1709,25 +1709,25 @@

    pcre2test man page

    matching, match_limit controls the total number of calls, both recursive and non-recursive, to the internal matching function, thus controlling the overall amount of computing resource that is used. -

    -

    +

    +

    For both kinds of matching, the heap_limit number, which is in kibibytes (units of 1024 bytes), limits the amount of heap memory used for matching. -

    +


    Showing MARK names
    -

    +

    The mark modifier causes the names from backtracking control verbs that are returned from calls to pcre2_match() to be displayed. If a mark is returned for a match, non-match, or partial match, pcre2test shows it. For a match, it is on a line by itself, tagged with "MK:". Otherwise, it is added to the non-match message. -

    +


    Showing memory usage
    -

    +

    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() or pcre2_dfa_match(). In the latter case, heap memory @@ -1736,52 +1736,52 @@

    pcre2test man page

    memory is allocated during matching with JIT. 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. -

    +


    Showing the heap frame overall vector size
    -

    +

    The heapframes_size modifier is relevant for matches using pcre2_match() without JIT. After a match has run (whether successful or not) the size, in bytes, of the allocated heap frames vector that is left attached to the match data block is shown. If the matching action involved several calls to pcre2_match() (for example, global matching or for timing) only the final value is shown. -

    -

    +

    +

    This modifier is ignored, with a warning, for POSIX or DFA matching. JIT matching does not use the heap frames vector, so the size is always zero, unless there was a previous non-JIT match. Note that specifing a size of zero for the output vector (see below) causes pcre2test to free its match data block (and associated heap frames vector) and allocate a new one. -

    +


    Setting a starting offset
    -

    +

    The offset modifier sets an offset in the subject string at which matching starts. Its value is a number of code units, not characters. -

    +


    Setting an offset limit
    -

    +

    The offset_limit modifier sets a limit for unanchored matches. If a match cannot be found starting at or before this offset in the subject, a "no match" return is given. The data value is a number of code units, not characters. When this modifier is used, the use_offset_limit modifier must have been set for the pattern; if not, an error is generated. -

    +


    Setting the size of the output vector
    -

    +

    The ovector modifier applies only to the subject line in which it appears, though of course it can also be used to set a default in a #subject command. It specifies the number of pairs of offsets that are available for storing matching information. The default is 15. -

    -

    +

    +

    A value of zero is useful when testing the POSIX API because it causes regexec() to be called with a NULL capture vector. When not testing the POSIX API, a value of zero is used to cause @@ -1789,25 +1789,25 @@

    pcre2test man page

    new match block of exactly the right size for the pattern. (It is not possible to create a match block with a zero-length ovector; there is always at least one pair of offsets.) The old match data block is freed. -

    +


    Passing the subject as zero-terminated
    -

    +

    By default, the subject string is passed to a native API matching function with its correct length. In order to test the facility for passing a zero-terminated string, the zero_terminate modifier is provided. It causes the length to be passed as PCRE2_ZERO_TERMINATED. When matching via the POSIX interface, this modifier is ignored, with a warning. -

    -

    +

    +

    When testing pcre2_substitute(), this modifier also has the effect of passing the replacement string as zero-terminated. -

    +


    Passing a NULL context, subject, or replacement
    -

    +

    Normally, pcre2test passes a context block to pcre2_match(), pcre2_dfa_match(), pcre2_jit_match() or pcre2_substitute(). If the null_context modifier is set, however, NULL is passed. This is for @@ -1815,14 +1815,14 @@

    pcre2test man page

    case (they use default values). This modifier cannot be used with the find_limits, find_limits_noheap, or substitute_callout modifiers. -

    -

    +

    +

    Similarly, for testing purposes, if the null_subject or null_replacement modifier is set, the subject or replacement string pointers are passed as NULL, respectively, to the relevant functions. -

    +


    THE ALTERNATIVE MATCHING FUNCTION
    -

    +

    By default, pcre2test uses the standard PCRE2 matching function, pcre2_match() to match each subject line. PCRE2 also supports an alternative matching function, pcre2_dfa_match(), which operates in a @@ -1830,19 +1830,19 @@

    pcre2test man page

    functions are described in the pcre2matching documentation. -

    -

    +

    +

    If the dfa modifier is set, the alternative matching function is used. This function finds all possible matches at a given point in the subject. If, however, the dfa_shortest modifier is set, processing stops after the first match is found. This is always the shortest possible match. -

    +


    DEFAULT OUTPUT FROM pcre2test
    -

    +

    This section describes the output when the normal matching function, pcre2_match(), is being used. -

    -

    +

    +

    When a match succeeds, pcre2test outputs the list of captured substrings, starting with number 0 for the string that matched the whole pattern. Otherwise, it outputs "No match" when the return is PCRE2_ERROR_NOMATCH, or @@ -1851,8 +1851,8 @@

    pcre2test man page

    entire substring that was inspected during the partial match; it may include characters before the actual match start if a lookbehind assertion, \K, \b, or \B was involved.) -

    -

    +

    +

    For any other return, pcre2test outputs the PCRE2 negative error number and a short descriptive phrase. If the error is a failed UTF string check, the code unit offset of the start of the failing character is also output. Here is @@ -1913,16 +1913,16 @@

    pcre2test man page

    re> /xyz/ data> xyz\=offset=4 Error -24 (bad offset value) - -

    -

    + +

    +

    Note that whereas patterns can be continued over several lines (a plain ">" prompt is used for continuations), subject lines may not. However newlines can be included in a subject by means of the \n escape (or \r, \r\n, etc., depending on the newline sequence setting). -

    +


    OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION
    -

    +

    When the alternative matching function, pcre2_dfa_match(), is used, the output consists of a list of all the matches that start at the first point in the subject where there is at least one match. For example: @@ -1940,8 +1940,8 @@

    pcre2test man page

    inspected during the partial match; it may include characters before the actual match start if a lookbehind assertion, \b, or \B was involved. (\K is not supported for DFA matching.) -

    -

    +

    +

    If global matching is requested, the search for further matches resumes at the end of the longest match. For example: 

    @@ -1956,9 +1956,9 @@ 
    pcre2test man page
    The alternative matching function does not support substring capture, so the modifiers that are concerned with captured substrings are not relevant. -

    +


    RESTARTING AFTER A PARTIAL MATCH
    -

    +

    When the alternative matching function has given the PCRE2_ERROR_PARTIAL return, indicating that the subject partially matched the pattern, you can restart the match with additional subject data by means of the @@ -1973,19 +1973,19 @@

    pcre2test man page

    For further information about partial matching, see the pcre2partial documentation. -

    +


    CALLOUTS
    -

    +

    If the pattern contains any callout requests, pcre2test's callout function is called during matching unless callout_none is specified. This works with both matching functions, and with JIT, though there are some differences in behaviour. The output for callouts with numerical arguments and those with string arguments is slightly different. -

    +


    Callouts with numerical arguments
    -

    +

    By default, the callout function displays the callout number, the start and current positions in the subject text at the callout time, and the next pattern item to be tested. For example: @@ -1999,8 +1999,8 @@

    pcre2test man page

    one circumflex is output if the start and current positions are the same, or if the current position precedes the start position, which can happen if the callout is in a lookbehind assertion. -

    -

    +

    +

    Callouts numbered 255 are assumed to be automatic callouts, inserted as a result of the auto_callout pattern modifier. In this case, instead of showing the callout number, the offset in the pattern, preceded by a plus, is @@ -2032,11 +2032,11 @@

    pcre2test man page

    The mark changes between matching "a" and "b", but stays the same for the rest of the match, so nothing more is output. If, as a result of backtracking, the mark reverts to being unset, the text "<unset>" is output. -

    +


    Callouts with string arguments
    -

    +

    The output for a callout with a string argument is similar, except that instead of outputting a callout number before the position indicators, the callout string and its offset in the pattern string are output before the reflection of @@ -2053,27 +2053,27 @@

    pcre2test man page

    ^ ^ e 0: abcdef - -

    + +


    Callout modifiers
    -

    +

    The callout function in pcre2test returns zero (carry on matching) by default, but you can use a callout_fail modifier in a subject line to change this and other parameters of the callout (see below). -

    -

    +

    +

    If the callout_capture modifier is set, the current captured groups are output when a callout occurs. This is useful only for non-DFA matching, as pcre2_dfa_match() does not support capturing, so no captures are ever shown. -

    -

    +

    +

    The normal callout output, showing the callout number or pattern offset (as described above) is suppressed if the callout_no_where modifier is set. -

    -

    +

    +

    When using the interpretive matching function pcre2_match() without JIT, setting the callout_extra modifier causes additional output from pcre2test's callout function to be generated. For the first callout in a @@ -2123,15 +2123,15 @@

    pcre2test man page

    optimization fails to find "b" in the subject, which it knows must be present for any match. If no_auto_possess is not used, the "a+" item is turned into "a++", which reduces the number of backtracks. -

    -

    +

    +

    The callout_extra modifier has no effect if used with the DFA matching function, or with JIT. -

    +


    Return values from callouts
    -

    +

    The default return from the callout function is zero, which allows matching to continue. The callout_fail modifier can be given one or two numbers. If there is only one number, 1 is returned instead of 0 (causing matching to @@ -2142,35 +2142,35 @@

    pcre2test man page

    aborted. If both these modifiers are set for the same callout number, callout_error takes precedence. Note that callouts with string arguments are always given the number zero. -

    -

    +

    +

    The callout_data modifier can be given an unsigned or a negative number. This is set as the "user data" that is passed to the matching function, and passed back when the callout function is invoked. Any value other than zero is used as a return from pcre2test's callout function. -

    -

    +

    +

    Inserting callouts can be helpful when using pcre2test to check complicated regular expressions. For further information about callouts, see the pcre2callout documentation. -

    +


    NON-PRINTING CHARACTERS
    -

    +

    When pcre2test is outputting text in the compiled version of a pattern, bytes other than 32-126 are always treated as non-printing characters and are therefore shown as hex escapes. -

    -

    +

    +

    When pcre2test is outputting text that is a matched part of a subject string, it behaves in the same way, unless a different locale has been set for the pattern (using the locale modifier). In this case, the isprint() function is used to distinguish printing and non-printing characters. -

    +


    SAVING AND RESTORING COMPILED PATTERNS
    -

    +

    It is possible to save compiled patterns on disc or elsewhere, and reload them later, subject to a number of restrictions. JIT data cannot be saved. The host on which the patterns are reloaded must be running the same version of PCRE2, @@ -2180,20 +2180,20 @@

    pcre2test man page

    contain any number of compiled patterns, but they must all use the same character tables. A single copy of the tables is included in the byte stream (its size is 1088 bytes). -

    -

    +

    +

    The functions whose names begin with pcre2_serialize_ are used for serializing and de-serializing. They are described in the pcre2serialize documentation. In this section we describe the features of pcre2test that can be used to test these functions. -

    -

    +

    +

    Note that "serialization" in PCRE2 does not convert compiled patterns to an abstract format like Java or .NET. It just makes a reloadable byte code stream. Hence the restrictions on reloading mentioned above. -

    -

    +

    +

    In pcre2test, when a pattern with push modifier is successfully compiled, it is pushed onto a stack of compiled patterns, and pcre2test expects the next line to contain a new pattern (or command) instead of a @@ -2204,8 +2204,8 @@

    pcre2test man page

    and control modifiers that act at match time are ignored (with a message) for the stacked patterns. The jitverify modifier applies only at compile time. -

    -

    +

    +

    The command 

       #save <filename>
@@ -2241,29 +2241,29 @@ 
    pcre2test man page
    If jitverify is used with #pop, it does not automatically imply jit, which is different behaviour from when it is used on a pattern. -

    -

    +

    +

    The #popcopy command is analogous to the pushcopy modifier in that it makes current a copy of the topmost stack pattern, leaving the original still on the stack. -

    +


    SEE ALSO
    -

    +

    pcre2(3), pcre2api(3), pcre2callout(3), pcre2jit, pcre2matching(3), pcre2partial(d), pcre2pattern(3), pcre2serialize(3). -

    +


    AUTHOR
    -

    +

    Philip Hazel
    Retired from University Computing Service
    Cambridge, England.
    -

    +


    REVISION
    -

    +

    Last updated: 26 December 2024
    Copyright © 1997-2024 University of Cambridge. diff --git a/doc/html/pcre2unicode.html b/doc/html/pcre2unicode.html index 5b425329f..a4429b302 100644 --- a/doc/html/pcre2unicode.html +++ b/doc/html/pcre2unicode.html @@ -15,15 +15,15 @@

    pcre2unicode man page


    UNICODE AND UTF SUPPORT
    -

    +

    PCRE2 is normally built with Unicode support, though if you do not need it, you can build it without, in which case the library will be smaller. With Unicode support, PCRE2 has knowledge of Unicode character properties and can process strings of text in UTF-8, UTF-16, and UTF-32 format (depending on the code unit width), but this is not the default. Unless specifically requested, PCRE2 treats each code unit in a string as one character. -

    -

    +

    +

    There are two ways of telling PCRE2 to switch to UTF mode, where characters may consist of more than one code unit and the range of values is constrained. The program can call @@ -32,22 +32,22 @@

    pcre2unicode man page

    However, the latter facility can be locked out by the PCRE2_NEVER_UTF option. That is, the programmer can prevent the supplier of the pattern from switching to UTF mode. -

    -

    +

    +

    Note that the PCRE2_MATCH_INVALID_UTF option (see below) forces PCRE2_UTF to be set. -

    -

    +

    +

    In UTF mode, both the pattern and any subject strings that are matched against it are treated as UTF strings instead of strings of individual one-code-unit characters. There are also some other changes to the way characters are handled, as documented below. -

    +


    UNICODE PROPERTY SUPPORT
    -

    +

    When PCRE2 is built with Unicode support, the escape sequences \p{..}, \P{..}, and \X can be used. This is not dependent on the PCRE2_UTF setting. The Unicode properties that can be tested are a subset of those that Perl @@ -55,8 +55,8 @@

    pcre2unicode man page

    Lu for an upper case letter or Nd for a decimal number, the derived properties Any and Lc (synonym L&), the Unicode script names such as Arabic or Han, Bidi_Class, Bidi_Control, and a few binary properties. -

    -

    +

    +

    The full lists are given in the pcre2pattern and @@ -65,34 +65,34 @@

    pcre2unicode man page

    For example, \p{L} matches a letter. Its longer synonym, \p{Letter}, is not supported. Furthermore, in Perl, many properties may optionally be prefixed by "Is", for compatibility with Perl 5.6. PCRE2 does not support this. -

    +


    WIDE CHARACTERS AND UTF MODES
    -

    +

    Code points less than 256 can be specified in patterns by either braced or unbraced hexadecimal escape sequences (for example, \x{b3} or \xb3). Larger values have to use braced sequences. Unbraced octal code points up to \777 are also recognized; larger ones can be coded using \o{...}. -

    -

    +

    +

    The escape sequence \N{U+<hex digits>} is recognized as another way of specifying a Unicode character by code point in a UTF mode. It is not allowed in non-UTF mode. -

    -

    +

    +

    In UTF mode, repeat quantifiers apply to complete UTF characters, not to individual code units. -

    -

    +

    +

    In UTF mode, the dot metacharacter matches one UTF character instead of a single code unit. -

    -

    +

    +

    In UTF mode, capture group names are not restricted to ASCII, and may contain any Unicode letters and decimal digits, as well as underscore. -

    -

    +

    +

    The escape sequence \C can be used to match a single code unit in UTF mode, but its use can lead to some strange effects because it breaks up multi-unit characters (see the description of \C in the @@ -100,8 +100,8 @@

    pcre2unicode man page

    documentation). For this reason, there is a build-time option that disables support for \C completely. There is also a less draconian compile-time option for locking out the use of \C when a pattern is compiled. -

    -

    +

    +

    The use of \C is not supported by the alternative matching function pcre2_dfa_match() when in UTF-8 or UTF-16 mode, that is, when a character may consist of more than one code unit. The use of \C in these modes provokes @@ -109,8 +109,8 @@

    pcre2unicode man page

    modes. If JIT optimization is requested for a UTF-8 or UTF-16 pattern that contains \C, it will not succeed, and so when pcre2_match() is called, the matching will be carried out by the interpretive function. -

    -

    +

    +

    The character escapes \b, \B, \d, \D, \s, \S, \w, and \W correctly test characters of any code value, but, by default, the characters that PCRE2 recognizes as digits, spaces, or word characters remain the same set as in @@ -127,21 +127,21 @@

    pcre2unicode man page

    in the pcre2pattern documentation. -

    -

    +

    +

    Like the escapes, characters that match the POSIX named character classes are all low-valued characters unless the PCRE2_UCP option is set, but there is an option to override this. -

    -

    +

    +

    In contrast to the character escapes and character classes, the special horizontal and vertical white space escapes (\h, \H, \v, and \V) do match all the appropriate Unicode characters, whether or not PCRE2_UCP is set. -

    +


    UNICODE CASE-EQUIVALENCE
    -

    +

    If either PCRE2_UTF or PCRE2_UCP is set, upper/lower case processing makes use of Unicode properties except for characters whose code points are less than 128 and that have at most two case-equivalent values. For these, a direct table @@ -149,8 +149,8 @@

    pcre2unicode man page

    more than two code points that are case-equivalent, and these are treated specially. Setting PCRE2_UCP without PCRE2_UTF allows Unicode-style case processing for non-UTF character encodings such as UCS-2. -

    -

    +

    +

    There are two ASCII characters (S and K) that, in addition to their ASCII lower case equivalents, have a non-ASCII one as well (long S and Kelvin sign). Recognition of these non-ASCII characters as case-equivalent to their ASCII @@ -166,9 +166,9 @@

    pcre2unicode man page

    U+212A (Kelvin sign) only case-equivalent to itself 's' = 'S' U+017F (long S) only case-equivalent to itself - -

    -

    + +

    +

    One language family, Turkish and Azeri, has its own case-insensitivity rules, which can be selected by setting PCRE2_EXTRA_TURKISH_CASING. This alters the behaviour of the 'i', 'I', U+0130 (capital I with dot above), and U+0131 @@ -181,50 +181,50 @@

    pcre2unicode man page

    With PCRE2_EXTRA_TURKISH_CASING: 'i' = U+0130 (capital I with dot above) U+0131 (small dotless i) = 'I' - -

    -

    + +

    +

    It is not allowed to specify both PCRE2_EXTRA_CASELESS_RESTRICT and PCRE2_EXTRA_TURKISH_CASING together. -

    -

    +

    +

    From release 10.45 the Unicode letter properties Lu (upper case), Ll (lower case), and Lt (title case) are all treated as Lc (cased letter) when caseless matching is set by the PCRE2_CASELESS option or (?i) within the pattern. -

    +


    SCRIPT RUNS
    -

    +

    The pattern constructs (*script_run:...) and (*atomic_script_run:...), with synonyms (*sr:...) and (*asr:...), verify that the string matched within the parentheses is a script run. In concept, a script run is a sequence of characters that are all from the same Unicode script. However, because some scripts are commonly used together, and because some diacritical and other marks are used with multiple scripts, it is not that simple. -

    -

    +

    +

    Every Unicode character has a Script property, mostly with a value corresponding to the name of a script, such as Latin, Greek, or Cyrillic. There are also three special values: -

    -

    +

    +

    "Unknown" is used for code points that have not been assigned, and also for the surrogate code points. In the PCRE2 32-bit library, characters whose code points are greater than the Unicode maximum (U+10FFFF), which are accessible only in non-UTF mode, are assigned the Unknown script. -

    -

    +

    +

    "Common" is used for characters that are used with many scripts. These include punctuation, emoji, mathematical, musical, and currency symbols, and the ASCII digits 0 to 9. -

    -

    +

    +

    "Inherited" is used for characters such as diacritical marks that modify a previous character. These are considered to take on the script of the character that they modify. -

    -

    +

    +

    Some Inherited characters are used with many scripts, but many of them are only normally used with a small number of scripts. For example, U+102E0 (Coptic Epact thousands mark) is used only with Arabic and Coptic. In order to make it @@ -234,37 +234,37 @@

    pcre2unicode man page

    property. However, for characters such as U+102E0 more than one Script is listed. There are also some Common characters that have a single, non-Common script in their Script Extension list. -

    -

    +

    +

    The next section describes the basic rules for deciding whether a given string of characters is a script run. Note, however, that there are some special cases involving the Chinese Han script, and an additional constraint for decimal digits. These are covered in subsequent sections. -

    +


    Basic script run rules
    -

    +

    A string that is less than two characters long is a script run. This is the only case in which an Unknown character can be part of a script run. Longer strings are checked using only the Script Extensions property, not the basic Script property. -

    -

    +

    +

    If a character's Script Extension property is the single value "Inherited", it is always accepted as part of a script run. This is also true for the property "Common", subject to the checking of decimal digits described below. All the remaining characters in a script run must have at least one script in common in their Script Extension lists. In set-theoretic terminology, the intersection of all the sets of scripts must not be empty. -

    -

    +

    +

    A simple example is an Internet name such as "google.com". The letters are all in the Latin script, and the dot is Common, so this string is a script run. However, the Cyrillic letter "o" looks exactly the same as the Latin "o"; a string that looks the same, but with Cyrillic "o"s is not a script run. -

    -

    +

    +

    More interesting examples involve characters with more than one script in their Script Extension. Consider the following characters: 

    @@ -275,11 +275,11 @@ 
    pcre2unicode man page
    
 Thaana; the second has just Arabic and Hanifi Rohingya. Both of them could
 appear in script runs of either Arabic or Hanifi Rohingya. The first could also
 appear in Syriac or Thaana script runs, but the second could not.
-
    
+
    
 
    
 The Chinese Han script
 
    
-
    
+
    
 The Chinese Han script is commonly used in conjunction with other scripts for
 writing certain languages. Japanese uses the Hiragana and Katakana scripts
 together with Han; Korean uses Hangul and Han; Taiwanese Mandarin uses Bopomofo
@@ -290,57 +290,57 @@ 
    pcre2unicode man page
    
 Hangul and Bopomofo and Han. PCRE2 (like Perl) follows Unicode's Technical
 Standard 39 ("Unicode Security Mechanisms", http://unicode.org/reports/tr39/)
 in allowing such mixtures.
-
    
+
    
 
    
 Decimal digits
 
    
-
    
+
    
 Unicode contains many sets of 10 decimal digits in different scripts, and some
 scripts (including the Common script) contain more than one set. Some of these
 decimal digits them are visually indistinguishable from the common ASCII
 digits. In addition to the script checking described above, if a script run
 contains any decimal digits, they must all come from the same set of 10
 adjacent characters.
-
    
+
    
 
    
 VALIDITY OF UTF STRINGS
 
    
-
    
+
    
 When the PCRE2_UTF option is set, the strings passed as patterns and subjects
 are (by default) checked for validity on entry to the relevant functions. If an
 invalid UTF string is passed, a negative error code is returned. The code unit
 offset to the offending character can be extracted from the match data block by
 calling pcre2_get_startchar(), which is used for this purpose after a UTF
 error.
-
    
-
    
+
    
+
    
 In some situations, you may already know that your strings are valid, and
 therefore want to skip these checks in order to improve performance, for
 example in the case of a long subject string that is being scanned repeatedly.
 If you set the PCRE2_NO_UTF_CHECK option at compile time or at match time,
 PCRE2 assumes that the pattern or subject it is given (respectively) contains
 only valid UTF code unit sequences.
-
    
-
    
+
    
+
    
 If you pass an invalid UTF string when PCRE2_NO_UTF_CHECK is set, the result
 is undefined and your program may crash or loop indefinitely or give incorrect
 results. There is, however, one mode of matching that can handle invalid UTF
 subject strings. This is enabled by passing PCRE2_MATCH_INVALID_UTF to
 pcre2_compile() and is discussed below in the next section. The rest of
 this section covers the case when PCRE2_MATCH_INVALID_UTF is not set.
-
    
-
    
+
    
+
    
 Passing PCRE2_NO_UTF_CHECK to pcre2_compile() just disables the UTF check
 for the pattern; it does not also apply to subject strings. If you want to
 disable the check for a subject string you must pass this same option to
 pcre2_match() or pcre2_dfa_match().
-
    
-
    
+
    
+
    
 UTF-16 and UTF-32 strings can indicate their endianness by special code knows
 as a byte-order mark (BOM). The PCRE2 functions do not handle this, expecting
 strings to be in host byte order.
-
    
-
    
+
    
+
    
 Unless PCRE2_NO_UTF_CHECK is set, a UTF string is checked before any other
 processing takes place. In the case of pcre2_match() and
 pcre2_dfa_match() calls with a non-zero starting offset, the check is
@@ -352,33 +352,33 @@ 
    pcre2unicode man page
    
 starting offset, or at the start of the subject if there are not that many
 characters before the starting offset. Note that the sequences \b and \B are
 one-character lookbehinds.
-
    
-
    
+
    
+
    
 In addition to checking the format of the string, there is a check to ensure
 that all code points lie in the range U+0 to U+10FFFF, excluding the surrogate
 area. The so-called "non-character" code points are not excluded because
 Unicode corrigendum #9 makes it clear that they should not be.
-
    
-
    
+
    
+
    
 Characters in the "Surrogate Area" of Unicode are reserved for use by UTF-16,
 where they are used in pairs to encode code points with values greater than
 0xFFFF. The code points that are encoded by UTF-16 pairs are available
 independently in the UTF-8 and UTF-32 encodings. (In other words, the whole
 surrogate thing is a fudge for UTF-16 which unfortunately messes up UTF-8 and
 UTF-32.)
-
    
-
    
+
    
+
    
 Setting PCRE2_NO_UTF_CHECK at compile time does not disable the error that is
 given if an escape sequence for an invalid Unicode code point is encountered in
 the pattern. If you want to allow escape sequences such as \x{d800} (a
 surrogate code point) you can set the PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES extra
 option. However, this is possible only in UTF-8 and UTF-32 modes, because these
 values are not representable in UTF-16.
-
    
+
    
 
    
 Errors in UTF-8 strings
 
    
-
    
+
    
 The following negative error codes are given for invalid UTF-8 strings:
 
       PCRE2_ERROR_UTF8_ERR1
@@ -442,111 +442,111 @@ 
    pcre2unicode man page
    
 
    
 The first byte of a character has the value 0xfe or 0xff. These values can
 never occur in a valid UTF-8 string.
-
    
+
    
 
    
 Errors in UTF-16 strings
 
    
-
    
+
    
 The following negative error codes are given for invalid UTF-16 strings:
 
       PCRE2_ERROR_UTF16_ERR1  Missing low surrogate at end of string
   PCRE2_ERROR_UTF16_ERR2  Invalid low surrogate follows high surrogate
   PCRE2_ERROR_UTF16_ERR3  Isolated low surrogate
 
-
    
-
    
+
    +


    Errors in UTF-32 strings
    -

    +

    The following negative error codes are given for invalid UTF-32 strings: 

       PCRE2_ERROR_UTF32_ERR1  Surrogate character (0xd800 to 0xdfff)
   PCRE2_ERROR_UTF32_ERR2  Code point is greater than 0x10ffff
 
-
    -

    + +


    MATCHING IN INVALID UTF STRINGS
    -

    +

    You can run pattern matches on subject strings that may contain invalid UTF sequences if you call pcre2_compile() with the PCRE2_MATCH_INVALID_UTF option. This is supported by pcre2_match(), including JIT matching, but not by pcre2_dfa_match(). When PCRE2_MATCH_INVALID_UTF is set, it forces PCRE2_UTF to be set as well. Note, however, that the pattern itself must be a valid UTF string. -

    -

    +

    +

    If you do not set PCRE2_MATCH_INVALID_UTF when calling pcre2_compile, and you are not certain that your subject strings are valid UTF sequences, you should not make use of the JIT "fast path" function pcre2_jit_match() because it bypasses sanity checks, including the one for UTF validity. An invalid string may cause undefined behaviour, including looping, crashing, or giving the wrong answer. -

    -

    +

    +

    Setting PCRE2_MATCH_INVALID_UTF does not affect what pcre2_compile() generates, but if pcre2_jit_compile() is subsequently called, it does generate different code. If JIT is not used, the option affects the behaviour of the interpretive code in pcre2_match(). When PCRE2_MATCH_INVALID_UTF is set at compile time, PCRE2_NO_UTF_CHECK is ignored at match time. -

    -

    +

    +

    In this mode, an invalid code unit sequence in the subject never matches any pattern item. It does not match dot, it does not match \p{Any}, it does not even match negative items such as [^X]. A lookbehind assertion fails if it encounters an invalid sequence while moving the current point backwards. In other words, an invalid UTF code unit sequence acts as a barrier which no match can cross. -

    -

    +

    +

    You can also think of this as the subject being split up into fragments of valid UTF, delimited internally by invalid code unit sequences. The pattern is matched fragment by fragment. The result of a successful match, however, is given as code unit offsets in the entire subject string in the usual way. There are a few points to consider: -

    -

    +

    +

    The internal boundaries are not interpreted as the beginnings or ends of lines and so do not match circumflex or dollar characters in the pattern. -

    -

    +

    +

    If pcre2_match() is called with an offset that points to an invalid UTF-sequence, that sequence is skipped, and the match starts at the next valid UTF character, or the end of the subject. -

    -

    +

    +

    At internal fragment boundaries, \b and \B behave in the same way as at the beginning and end of the subject. For example, a sequence such as \bWORD\b would match an instance of WORD that is surrounded by invalid UTF code units. -

    -

    +

    +

    Using PCRE2_MATCH_INVALID_UTF, an application can run matches on arbitrary data, knowing that any matched strings that are returned are valid UTF. This can be useful when searching for UTF text in executable or other binary files. -

    -

    +

    +

    Note, however, that the 16-bit and 32-bit PCRE2 libraries process strings as sequences of uint16_t or uint32_t code points. They cannot find valid UTF sequences within an arbitrary string of bytes unless such sequences are suitably aligned. -

    +


    AUTHOR
    -

    +

    Philip Hazel
    Retired from University Computing Service
    Cambridge, England.
    -

    +


    REVISION
    -

    +

    Last updated: 27 November 2024
    Copyright © 1997-2024 University of Cambridge. diff --git a/doc/index.html.src b/doc/index.html.src index 2d81b678f..43b0d595b 100644 --- a/doc/index.html.src +++ b/doc/index.html.src @@ -7,6 +7,22 @@ --> PCRE2 specification +

    Perl-compatible Regular Expressions (revised API: PCRE2)

    @@ -18,67 +34,67 @@ first. - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - +
    pcre2  Introductory page
    Introductory page
    pcre2-config  Information about the installation configuration
    Information about the installation configuration
    pcre2api  PCRE2's native API
    PCRE2's native API
    pcre2build  Building PCRE2
    Building PCRE2
    pcre2callout  The callout facility
    The callout facility
    pcre2compat  Compability with Perl
    Compability with Perl
    pcre2convert  Experimental foreign pattern conversion functions
    Experimental foreign pattern conversion functions
    pcre2demo  A demonstration C program that uses the PCRE2 library
    A demonstration C program that uses the PCRE2 library
    pcre2grep  The pcre2grep command
    The pcre2grep command
    pcre2jit  Discussion of the just-in-time optimization support
    Discussion of the just-in-time optimization support
    pcre2limits  Details of size and other limits
    Details of size and other limits
    pcre2matching  Discussion of the two matching algorithms
    Discussion of the two matching algorithms
    pcre2partial  Using PCRE2 for partial matching
    Using PCRE2 for partial matching
    pcre2pattern  Specification of the regular expressions supported by PCRE2
    Specification of the regular expressions supported by PCRE2
    pcre2perform  Some comments on performance
    Some comments on performance
    pcre2posix  The POSIX API to the PCRE2 8-bit library
    The POSIX API to the PCRE2 8-bit library
    pcre2sample  Discussion of the pcre2demo program
    Discussion of the pcre2demo program
    pcre2serialize  Serializing functions for saving precompiled patterns
    Serializing functions for saving precompiled patterns
    pcre2syntax  Syntax quick-reference summary
    Syntax quick-reference summary
    pcre2test  The pcre2test command for testing PCRE2
    The pcre2test command for testing PCRE2
    pcre2unicode  Discussion of Unicode and UTF-8/UTF-16/UTF-32 support
    Discussion of Unicode and UTF-8/UTF-16/UTF-32 support

    @@ -89,238 +105,238 @@ in the library. - + - + - + - + - + - + - + - + - + - + - + - + - + - - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - + - + - + - + - + - + - + - + - + - + - +
    pcre2_callout_enumerate  Enumerate callouts in a compiled pattern
    Enumerate callouts in a compiled pattern
    pcre2_code_copy  Copy a compiled pattern
    Copy a compiled pattern
    pcre2_code_copy_with_tables  Copy a compiled pattern and its character tables
    Copy a compiled pattern and its character tables
    pcre2_code_free  Free a compiled pattern
    Free a compiled pattern
    pcre2_compile  Compile a regular expression pattern
    Compile a regular expression pattern
    pcre2_compile_context_copy  Copy a compile context
    Copy a compile context
    pcre2_compile_context_create  Create a compile context
    Create a compile context
    pcre2_compile_context_free  Free a compile context
    Free a compile context
    pcre2_config  Show build-time configuration options
    Show build-time configuration options
    pcre2_convert_context_copy  Copy a convert context
    Copy a convert context
    pcre2_convert_context_create  Create a convert context
    Create a convert context
    pcre2_convert_context_free  Free a convert context
    Free a convert context
    pcre2_converted_pattern_free  Free converted foreign pattern
    Free converted foreign pattern
    pcre2_dfa_match  Match a compiled pattern to a subject string + Match a compiled pattern to a subject string (DFA algorithm; not Perl compatible)
    pcre2_general_context_copy  Copy a general context
    Copy a general context
    pcre2_general_context_create  Create a general context
    Create a general context
    pcre2_general_context_free  Free a general context
    Free a general context
    pcre2_get_error_message  Get textual error message for error number
    Get textual error message for error number
    pcre2_get_mark  Get a (*MARK) name
    Get a (*MARK) name
    pcre2_get_match_data_size  Get the size of a match data block
    Get the size of a match data block
    pcre2_get_ovector_count  Get the ovector count
    Get the ovector count
    pcre2_get_ovector_pointer  Get a pointer to the ovector
    Get a pointer to the ovector
    pcre2_get_startchar  Get the starting character offset
    Get the starting character offset
    pcre2_jit_compile  Process a compiled pattern with the JIT compiler
    Process a compiled pattern with the JIT compiler
    pcre2_jit_free_unused_memory  Free unused JIT memory
    Free unused JIT memory
    pcre2_jit_match  Fast path interface to JIT matching
    Fast path interface to JIT matching
    pcre2_jit_stack_assign  Assign stack for JIT matching
    Assign stack for JIT matching
    pcre2_jit_stack_create  Create a stack for JIT matching
    Create a stack for JIT matching
    pcre2_jit_stack_free  Free a JIT matching stack
    Free a JIT matching stack
    pcre2_maketables  Build character tables in current locale
    Build character tables in current locale
    pcre2_maketables_free  Free character tables
    Free character tables
    pcre2_match  Match a compiled pattern to a subject string + Match a compiled pattern to a subject string (Perl compatible)
    pcre2_match_context_copy  Copy a match context
    Copy a match context
    pcre2_match_context_create  Create a match context
    Create a match context
    pcre2_match_context_free  Free a match context
    Free a match context
    pcre2_match_data_create  Create a match data block
    Create a match data block
    pcre2_match_data_create_from_pattern  Create a match data block getting size from pattern
    Create a match data block getting size from pattern
    pcre2_match_data_free  Free a match data block
    Free a match data block
    pcre2_pattern_convert  Experimental foreign pattern converter
    Experimental foreign pattern converter
    pcre2_pattern_info  Extract information about a pattern
    Extract information about a pattern
    pcre2_serialize_decode  Decode serialized compiled patterns
    Decode serialized compiled patterns
    pcre2_serialize_encode  Serialize compiled patterns for save/restore
    Serialize compiled patterns for save/restore
    pcre2_serialize_free  Free serialized compiled patterns
    Free serialized compiled patterns
    pcre2_serialize_get_number_of_codes  Get number of serialized compiled patterns
    Get number of serialized compiled patterns
    pcre2_set_bsr  Set \R convention
    Set \R convention
    pcre2_set_callout  Set up a callout function
    Set up a callout function
    pcre2_set_character_tables  Set character tables
    Set character tables
    pcre2_set_compile_extra_options  Set compile time extra options
    Set compile time extra options
    pcre2_set_compile_recursion_guard  Set up a compile recursion guard function
    Set up a compile recursion guard function
    pcre2_set_depth_limit  Set the match backtracking depth limit
    Set the match backtracking depth limit
    pcre2_set_glob_escape  Set glob escape character
    Set glob escape character
    pcre2_set_glob_separator  Set glob separator character
    Set glob separator character
    pcre2_set_heap_limit  Set the match backtracking heap limit
    Set the match backtracking heap limit
    pcre2_set_match_limit  Set the match limit
    Set the match limit
    pcre2_set_max_pattern_compiled_length  Set the maximum length of a compiled pattern
    Set the maximum length of a compiled pattern
    pcre2_set_max_pattern_length  Set the maximum length of a pattern
    Set the maximum length of a pattern
    pcre2_set_max_varlookbehind  Set the maximum match length for a variable-length lookbehind
    Set the maximum match length for a variable-length lookbehind
    pcre2_set_newline  Set the newline convention
    Set the newline convention
    pcre2_set_offset_limit  Set the offset limit
    Set the offset limit
    pcre2_set_optimize  Set an optimization directive
    Set an optimization directive
    pcre2_set_parens_nest_limit  Set the parentheses nesting limit
    Set the parentheses nesting limit
    pcre2_set_recursion_limit  Obsolete: use pcre2_set_depth_limit
    Obsolete: use pcre2_set_depth_limit
    pcre2_set_recursion_memory_management  Obsolete function that (from 10.30 onwards) does nothing
    Obsolete function that (from 10.30 onwards) does nothing
    pcre2_set_substitute_callout  Set a substitution callout function
    Set a substitution callout function
    pcre2_set_substitute_case_callout  Set a substitution case callout function
    Set a substitution case callout function
    pcre2_substitute  Match a compiled pattern to a subject string and do + Match a compiled pattern to a subject string and do substitutions
    pcre2_substring_copy_byname  Extract named substring into given buffer
    Extract named substring into given buffer
    pcre2_substring_copy_bynumber  Extract numbered substring into given buffer
    Extract numbered substring into given buffer
    pcre2_substring_free  Free extracted substring
    Free extracted substring
    pcre2_substring_get_byname  Extract named substring into new memory
    Extract named substring into new memory
    pcre2_substring_get_bynumber  Extract numbered substring into new memory
    Extract numbered substring into new memory
    pcre2_substring_length_byname  Find length of named substring
    Find length of named substring
    pcre2_substring_length_bynumber  Find length of numbered substring
    Find length of numbered substring
    pcre2_substring_list_free  Free list of extracted substrings
    Free list of extracted substrings
    pcre2_substring_list_get  Extract all substrings into new memory
    Extract all substrings into new memory
    pcre2_substring_nametable_scan  Find table entries for given string name
    Find table entries for given string name
    pcre2_substring_number_from_name  Convert captured string name to number
    Convert captured string name to number
    diff --git a/doc/pcre2.3 b/doc/pcre2.3 index 180410c93..8f9ed8f7d 100644 --- a/doc/pcre2.3 +++ b/doc/pcre2.3 @@ -87,7 +87,7 @@ found in the and .\" HTML .\" -\fBNON-AUTOTOOLS_BUILD\fP +\fBNON-AUTOTOOLS-BUILD\fP .\" files in the source distribution. .P diff --git a/doc/pcre2.txt b/doc/pcre2.txt index a67546fe4..5773b38bf 100644 --- a/doc/pcre2.txt +++ b/doc/pcre2.txt @@ -76,7 +76,7 @@ INTRODUCTION client to discover which features are available. The features them- selves are described in the pcre2build page. Documentation about build- ing PCRE2 for various operating systems can be found in the README and - NON-AUTOTOOLS_BUILD files in the source distribution. + NON-AUTOTOOLS-BUILD files in the source distribution. The libraries contains a number of undocumented internal functions and data tables that are used by more than one of the exported external @@ -5567,12 +5567,12 @@ DIFFERENCES BETWEEN PCRE2 AND PERL (m) The scan substring assertion (syntax (*scs:(n)...)) is a PCRE2 ex- tension that is not available in Perl. - 20. Perl has different limits than PCRE2. See the pcre2limit documenta- - tion for details. Perl went with 5.10 from recursion to iteration keep- - ing the intermediate matches on the heap, which is ~10% slower but does - not fall into any stack-overflow limit. PCRE2 made a similar change at - release 10.30, and also has many build-time and run-time customizable - limits. + 20. Perl has different limits than PCRE2. See the pcre2limits documen- + tation for details. Perl went with 5.10 from recursion to iteration + keeping the intermediate matches on the heap, which is ~10% slower but + does not fall into any stack-overflow limit. PCRE2 made a similar + change at release 10.30, and also has many build-time and run-time cus- + tomizable limits. 21. Unlike Perl, PCRE2 doesn't have character set modifiers and spe- cially no way to set characters by context just like Perl's "/d". A diff --git a/doc/pcre2compat.3 b/doc/pcre2compat.3 index 61d5dcd85..ff0a760c3 100644 --- a/doc/pcre2compat.3 +++ b/doc/pcre2compat.3 @@ -209,7 +209,7 @@ that is not available in Perl. .P 20. Perl has different limits than PCRE2. See the .\" HREF -\fBpcre2limit\fP +\fBpcre2limits\fP .\" documentation for details. Perl went with 5.10 from recursion to iteration keeping the intermediate matches on the heap, which is ~10% slower but does not diff --git a/doc/pcre2pattern.3 b/doc/pcre2pattern.3 index 44382a533..51763166d 100644 --- a/doc/pcre2pattern.3 +++ b/doc/pcre2pattern.3 @@ -1360,7 +1360,7 @@ it matches any character except one that signifies the end of a line. .P When \eN is followed by an opening brace it has a different meaning. See the section entitled -.\" HTML +.\" HTML .\" "Non-printing characters" .\" diff --git a/index.md b/index.md deleted file mode 100644 index d3fff179e..000000000 --- a/index.md +++ /dev/null @@ -1,56 +0,0 @@ -# PCRE2 - Perl-Compatible Regular Expressions - -The PCRE2 library is a set of C functions that implement regular expression -pattern matching using the same syntax and semantics as Perl 5. PCRE2 has its -own native API, as well as a set of wrapper functions that correspond to the -POSIX regular expression API. The PCRE2 library is free, even for building -proprietary software. It comes in three forms, for processing 8-bit, 16-bit, -or 32-bit code units, in either literal or UTF encoding. - -PCRE2 was first released in 2015 to replace the API in the original PCRE -library, which is now obsolete and no longer maintained. As well as a more -flexible API, the code of PCRE2 has been much improved since the fork. - -## Download - -As well as downloading from the -[GitHub site](https://github.com/PCRE2Project/pcre2), you can download PCRE2 -or the older, unmaintained PCRE1 library from an -[*unofficial* mirror](https://sourceforge.net/projects/pcre/files/) at SourceForge. - -You can check out the PCRE2 source code via Git or Subversion: - - git clone https://github.com/PCRE2Project/pcre2.git - svn co https://github.com/PCRE2Project/pcre2.git - -## Contributed Ports - -If you just need the command-line PCRE2 tools on Windows, precompiled binary -versions are available at this -[Rexegg page](http://www.rexegg.com/pcregrep-pcretest.html). - -A PCRE2 port for z/OS, a mainframe operating system which uses EBCDIC as its -default character encoding, can be found at -[http://www.cbttape.org](http://www.cbttape.org/) (File 939). - -## Documentation - -You can read the PCRE2 documentation -[here](https://PCRE2Project.github.io/pcre2/doc/html/index.html). - -Comparisons to Perl's regular expression semantics can be found in the -community authored Wikipedia entry for PCRE. - -There is a curated summary of changes for each PCRE release, copies of -documentation from older releases, and other useful information from the third -party authored -[RexEgg PCRE Documentation and Change Log page](http://www.rexegg.com/pcre-documentation.html). - -## Contact - -To report a problem with the PCRE2 library, or to make a feature request, please -use the PCRE2 GitHub issues tracker. There is a mailing list for discussion of - PCRE2 issues and development at pcre2-dev@googlegroups.com, which is where any -announcements will be made. You can browse the -[list archives](https://groups.google.com/g/pcre2-dev). - diff --git a/maint/132html b/maint/132html index 8d05e9d5c..a8c705050 100755 --- a/maint/132html +++ b/maint/132html @@ -23,8 +23,8 @@ $s; sub end_para { if ($inpara) { - print TEMP "\n" if ($inpre); - print TEMP "

    \n"; + print TEMP "\n" if ($inpre); + print TEMP "

    \n"; } $inpara = $inpre = 0; $wrotetext = 0; @@ -34,7 +34,7 @@ $wrotetext = 0; sub new_para { &end_para(); -print TEMP "

    \n"; +print TEMP "

    \n"; $inpara = 1; } @@ -46,17 +46,21 @@ $inpara = 0; $inpre = 0; $wrotetext = 0; $toc = 0; +$header = 1; $ref = 1; while ($#ARGV >= 0 && $ARGV[0] =~ /^-/) { $toc = 1 if $ARGV[0] eq "-toc"; + $header = 0 if $ARGV[0] eq "-noheader"; shift; } # Initial output to STDOUT -print < $ARGV[0] specification @@ -72,6 +76,7 @@ automatically from the original man page. If there is any nonsense in it, please consult the man page, in case the conversion went wrong.
    End + } print "

      \n" if ($toc); @@ -242,7 +247,7 @@ while () elsif (/^\.EX\s*$/) { - print TEMP "
      \n";
+      print TEMP "
      \n";
       while ()
         {
         last if /^\.EE\s*$/;
@@ -306,11 +311,14 @@ open(TEMP, "/tmp/$$") || die "Can't open /tmp/$$ for input\n";
 
 print while ();
 
-print <
 Return to the PCRE2 index page.
 
      
 End
+  }
 
 close(TEMP);
 unlink("/tmp/$$");
diff --git a/maint/PrepareRelease b/maint/PrepareRelease
index ee85594af..5bc52fe7c 100755
--- a/maint/PrepareRelease
+++ b/maint/PrepareRelease
@@ -184,6 +184,7 @@ for file in *.1 ; do
   base=`basename $file .1`
   echo "  Making $base.html"
   perl ../maint/132html -toc $base <$file >html/$base.html
+  if [ $? != 0 ] ; then exit 1; fi
 done
 
 # Exclude table of contents for function summaries. It seems that expr
diff --git a/maint/UpdateCommon.py b/maint/UpdateCommon.py
index 0420bb327..88d3aa030 100644
--- a/maint/UpdateCommon.py
+++ b/maint/UpdateCommon.py
@@ -1,9 +1,12 @@
 # Common helpers for UpdateRelease.py and UpdateDates.py.
 
 import re
+import os
+
+script_dir = os.path.dirname(os.path.abspath(__file__))
 
 def get_current_release():
-    with open('configure.ac', 'r') as file:
+    with open(f"{script_dir}/../configure.ac", 'r') as file:
         content = file.read()
 
     matches = [match[1] for match in re.findall(r"m4_define\(pcre2_(major|minor|prerelease), \[(.*?)\]\)", content)]