--- /dev/null
+.TH PCRE2API 3 "07 September 2018" "PCRE2 10.32"
+.SH NAME
+PCRE2 - Perl-compatible regular expressions (revised API)
+.sp
+.B #include <pcre2.h>
+.sp
+PCRE2 is a new API for PCRE, starting at release 10.0. This document contains a
+description of all its native functions. See the
+.\" HREF
+\fBpcre2\fP
+.\"
+document for an overview of all the PCRE2 documentation.
+.
+.
+.SH "PCRE2 NATIVE API BASIC FUNCTIONS"
+.rs
+.sp
+.nf
+.B pcre2_code *pcre2_compile(PCRE2_SPTR \fIpattern\fP, PCRE2_SIZE \fIlength\fP,
+.B " uint32_t \fIoptions\fP, int *\fIerrorcode\fP, PCRE2_SIZE *\fIerroroffset,\fP"
+.B " pcre2_compile_context *\fIccontext\fP);"
+.sp
+.B void pcre2_code_free(pcre2_code *\fIcode\fP);
+.sp
+.B pcre2_match_data *pcre2_match_data_create(uint32_t \fIovecsize\fP,
+.B " pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B pcre2_match_data *pcre2_match_data_create_from_pattern(
+.B " const pcre2_code *\fIcode\fP, pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B int pcre2_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP,
+.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP,"
+.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP,"
+.B " pcre2_match_context *\fImcontext\fP);"
+.sp
+.B int pcre2_dfa_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP,
+.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP,"
+.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP,"
+.B " pcre2_match_context *\fImcontext\fP,"
+.B " int *\fIworkspace\fP, PCRE2_SIZE \fIwscount\fP);"
+.sp
+.B void pcre2_match_data_free(pcre2_match_data *\fImatch_data\fP);
+.fi
+.
+.
+.SH "PCRE2 NATIVE API AUXILIARY MATCH FUNCTIONS"
+.rs
+.sp
+.nf
+.B PCRE2_SPTR pcre2_get_mark(pcre2_match_data *\fImatch_data\fP);
+.sp
+.B uint32_t pcre2_get_ovector_count(pcre2_match_data *\fImatch_data\fP);
+.sp
+.B PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *\fImatch_data\fP);
+.sp
+.B PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *\fImatch_data\fP);
+.fi
+.
+.
+.SH "PCRE2 NATIVE API GENERAL CONTEXT FUNCTIONS"
+.rs
+.sp
+.nf
+.B pcre2_general_context *pcre2_general_context_create(
+.B " void *(*\fIprivate_malloc\fP)(PCRE2_SIZE, void *),"
+.B " void (*\fIprivate_free\fP)(void *, void *), void *\fImemory_data\fP);"
+.sp
+.B pcre2_general_context *pcre2_general_context_copy(
+.B " pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B void pcre2_general_context_free(pcre2_general_context *\fIgcontext\fP);
+.fi
+.
+.
+.SH "PCRE2 NATIVE API COMPILE CONTEXT FUNCTIONS"
+.rs
+.sp
+.nf
+.B pcre2_compile_context *pcre2_compile_context_create(
+.B " pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B pcre2_compile_context *pcre2_compile_context_copy(
+.B " pcre2_compile_context *\fIccontext\fP);"
+.sp
+.B void pcre2_compile_context_free(pcre2_compile_context *\fIccontext\fP);
+.sp
+.B int pcre2_set_bsr(pcre2_compile_context *\fIccontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.sp
+.B int pcre2_set_character_tables(pcre2_compile_context *\fIccontext\fP,
+.B " const unsigned char *\fItables\fP);"
+.sp
+.B int pcre2_set_compile_extra_options(pcre2_compile_context *\fIccontext\fP,
+.B " uint32_t \fIextra_options\fP);"
+.sp
+.B int pcre2_set_max_pattern_length(pcre2_compile_context *\fIccontext\fP,
+.B " PCRE2_SIZE \fIvalue\fP);"
+.sp
+.B int pcre2_set_newline(pcre2_compile_context *\fIccontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.sp
+.B int pcre2_set_parens_nest_limit(pcre2_compile_context *\fIccontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.sp
+.B int pcre2_set_compile_recursion_guard(pcre2_compile_context *\fIccontext\fP,
+.B " int (*\fIguard_function\fP)(uint32_t, void *), void *\fIuser_data\fP);"
+.fi
+.
+.
+.SH "PCRE2 NATIVE API MATCH CONTEXT FUNCTIONS"
+.rs
+.sp
+.nf
+.B pcre2_match_context *pcre2_match_context_create(
+.B " pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B pcre2_match_context *pcre2_match_context_copy(
+.B " pcre2_match_context *\fImcontext\fP);"
+.sp
+.B void pcre2_match_context_free(pcre2_match_context *\fImcontext\fP);
+.sp
+.B int pcre2_set_callout(pcre2_match_context *\fImcontext\fP,
+.B " int (*\fIcallout_function\fP)(pcre2_callout_block *, void *),"
+.B " void *\fIcallout_data\fP);"
+.sp
+.B int pcre2_set_offset_limit(pcre2_match_context *\fImcontext\fP,
+.B " PCRE2_SIZE \fIvalue\fP);"
+.sp
+.B int pcre2_set_heap_limit(pcre2_match_context *\fImcontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.sp
+.B int pcre2_set_match_limit(pcre2_match_context *\fImcontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.sp
+.B int pcre2_set_depth_limit(pcre2_match_context *\fImcontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.fi
+.
+.
+.SH "PCRE2 NATIVE API STRING EXTRACTION FUNCTIONS"
+.rs
+.sp
+.nf
+.B int pcre2_substring_copy_byname(pcre2_match_data *\fImatch_data\fP,
+.B " PCRE2_SPTR \fIname\fP, PCRE2_UCHAR *\fIbuffer\fP, PCRE2_SIZE *\fIbufflen\fP);"
+.sp
+.B int pcre2_substring_copy_bynumber(pcre2_match_data *\fImatch_data\fP,
+.B " uint32_t \fInumber\fP, PCRE2_UCHAR *\fIbuffer\fP,"
+.B " PCRE2_SIZE *\fIbufflen\fP);"
+.sp
+.B void pcre2_substring_free(PCRE2_UCHAR *\fIbuffer\fP);
+.sp
+.B int pcre2_substring_get_byname(pcre2_match_data *\fImatch_data\fP,
+.B " PCRE2_SPTR \fIname\fP, PCRE2_UCHAR **\fIbufferptr\fP, PCRE2_SIZE *\fIbufflen\fP);"
+.sp
+.B int pcre2_substring_get_bynumber(pcre2_match_data *\fImatch_data\fP,
+.B " uint32_t \fInumber\fP, PCRE2_UCHAR **\fIbufferptr\fP,"
+.B " PCRE2_SIZE *\fIbufflen\fP);"
+.sp
+.B int pcre2_substring_length_byname(pcre2_match_data *\fImatch_data\fP,
+.B " PCRE2_SPTR \fIname\fP, PCRE2_SIZE *\fIlength\fP);"
+.sp
+.B int pcre2_substring_length_bynumber(pcre2_match_data *\fImatch_data\fP,
+.B " uint32_t \fInumber\fP, PCRE2_SIZE *\fIlength\fP);"
+.sp
+.B int pcre2_substring_nametable_scan(const pcre2_code *\fIcode\fP,
+.B " PCRE2_SPTR \fIname\fP, PCRE2_SPTR *\fIfirst\fP, PCRE2_SPTR *\fIlast\fP);"
+.sp
+.B int pcre2_substring_number_from_name(const pcre2_code *\fIcode\fP,
+.B " PCRE2_SPTR \fIname\fP);"
+.sp
+.B void pcre2_substring_list_free(PCRE2_SPTR *\fIlist\fP);
+.sp
+.B int pcre2_substring_list_get(pcre2_match_data *\fImatch_data\fP,
+.B " PCRE2_UCHAR ***\fIlistptr\fP, PCRE2_SIZE **\fIlengthsptr\fP);
+.fi
+.
+.
+.SH "PCRE2 NATIVE API STRING SUBSTITUTION FUNCTION"
+.rs
+.sp
+.nf
+.B int pcre2_substitute(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP,
+.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP,"
+.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP,"
+.B " pcre2_match_context *\fImcontext\fP, PCRE2_SPTR \fIreplacementzfP,"
+.B " PCRE2_SIZE \fIrlength\fP, PCRE2_UCHAR *\fIoutputbuffer\fP,"
+.B " PCRE2_SIZE *\fIoutlengthptr\fP);"
+.fi
+.
+.
+.SH "PCRE2 NATIVE API JIT FUNCTIONS"
+.rs
+.sp
+.nf
+.B int pcre2_jit_compile(pcre2_code *\fIcode\fP, uint32_t \fIoptions\fP);
+.sp
+.B int pcre2_jit_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP,
+.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP,"
+.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP,"
+.B " pcre2_match_context *\fImcontext\fP);"
+.sp
+.B void pcre2_jit_free_unused_memory(pcre2_general_context *\fIgcontext\fP);
+.sp
+.B pcre2_jit_stack *pcre2_jit_stack_create(PCRE2_SIZE \fIstartsize\fP,
+.B " PCRE2_SIZE \fImaxsize\fP, pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B void pcre2_jit_stack_assign(pcre2_match_context *\fImcontext\fP,
+.B " pcre2_jit_callback \fIcallback_function\fP, void *\fIcallback_data\fP);"
+.sp
+.B void pcre2_jit_stack_free(pcre2_jit_stack *\fIjit_stack\fP);
+.fi
+.
+.
+.SH "PCRE2 NATIVE API SERIALIZATION FUNCTIONS"
+.rs
+.sp
+.nf
+.B int32_t pcre2_serialize_decode(pcre2_code **\fIcodes\fP,
+.B " int32_t \fInumber_of_codes\fP, const uint8_t *\fIbytes\fP,"
+.B " pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B int32_t pcre2_serialize_encode(const pcre2_code **\fIcodes\fP,
+.B " int32_t \fInumber_of_codes\fP, uint8_t **\fIserialized_bytes\fP,"
+.B " PCRE2_SIZE *\fIserialized_size\fP, pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B void pcre2_serialize_free(uint8_t *\fIbytes\fP);
+.sp
+.B int32_t pcre2_serialize_get_number_of_codes(const uint8_t *\fIbytes\fP);
+.fi
+.
+.
+.SH "PCRE2 NATIVE API AUXILIARY FUNCTIONS"
+.rs
+.sp
+.nf
+.B pcre2_code *pcre2_code_copy(const pcre2_code *\fIcode\fP);
+.sp
+.B pcre2_code *pcre2_code_copy_with_tables(const pcre2_code *\fIcode\fP);
+.sp
+.B int pcre2_get_error_message(int \fIerrorcode\fP, PCRE2_UCHAR *\fIbuffer\fP,
+.B " PCRE2_SIZE \fIbufflen\fP);"
+.sp
+.B const unsigned char *pcre2_maketables(pcre2_general_context *\fIgcontext\fP);
+.sp
+.B int pcre2_pattern_info(const pcre2 *\fIcode\fP, uint32_t \fIwhat\fP, void *\fIwhere\fP);
+.sp
+.B int pcre2_callout_enumerate(const pcre2_code *\fIcode\fP,
+.B " int (*\fIcallback\fP)(pcre2_callout_enumerate_block *, void *),"
+.B " void *\fIuser_data\fP);"
+.sp
+.B int pcre2_config(uint32_t \fIwhat\fP, void *\fIwhere\fP);
+.fi
+.
+.
+.SH "PCRE2 NATIVE API OBSOLETE FUNCTIONS"
+.rs
+.sp
+.nf
+.B int pcre2_set_recursion_limit(pcre2_match_context *\fImcontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.sp
+.B int pcre2_set_recursion_memory_management(
+.B " pcre2_match_context *\fImcontext\fP,"
+.B " void *(*\fIprivate_malloc\fP)(PCRE2_SIZE, void *),"
+.B " void (*\fIprivate_free\fP)(void *, void *), void *\fImemory_data\fP);"
+.fi
+.sp
+These functions became obsolete at release 10.30 and are retained only for
+backward compatibility. They should not be used in new code. The first is
+replaced by \fBpcre2_set_depth_limit()\fP; the second is no longer needed and
+has no effect (it always returns zero).
+.
+.
+.SH "PCRE2 EXPERIMENTAL PATTERN CONVERSION FUNCTIONS"
+.rs
+.sp
+.nf
+.B pcre2_convert_context *pcre2_convert_context_create(
+.B " pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B pcre2_convert_context *pcre2_convert_context_copy(
+.B " pcre2_convert_context *\fIcvcontext\fP);"
+.sp
+.B void pcre2_convert_context_free(pcre2_convert_context *\fIcvcontext\fP);
+.sp
+.B int pcre2_set_glob_escape(pcre2_convert_context *\fIcvcontext\fP,
+.B " uint32_t \fIescape_char\fP);"
+.sp
+.B int pcre2_set_glob_separator(pcre2_convert_context *\fIcvcontext\fP,
+.B " uint32_t \fIseparator_char\fP);"
+.sp
+.B int pcre2_pattern_convert(PCRE2_SPTR \fIpattern\fP, PCRE2_SIZE \fIlength\fP,
+.B " uint32_t \fIoptions\fP, PCRE2_UCHAR **\fIbuffer\fP,"
+.B " PCRE2_SIZE *\fIblength\fP, pcre2_convert_context *\fIcvcontext\fP);"
+.sp
+.B void pcre2_converted_pattern_free(PCRE2_UCHAR *\fIconverted_pattern\fP);
+.fi
+.sp
+These functions provide a way of converting non-PCRE2 patterns into
+patterns that can be processed by \fBpcre2_compile()\fP. This facility is
+experimental and may be changed in future releases. At present, "globs" and
+POSIX basic and extended patterns can be converted. Details are given in the
+.\" HREF
+\fBpcre2convert\fP
+.\"
+documentation.
+.
+.
+.SH "PCRE2 8-BIT, 16-BIT, AND 32-BIT LIBRARIES"
+.rs
+.sp
+There are three PCRE2 libraries, supporting 8-bit, 16-bit, and 32-bit code
+units, respectively. However, there is just one header file, \fBpcre2.h\fP.
+This contains the function prototypes and other definitions for all three
+libraries. One, two, or all three can be installed simultaneously. On Unix-like
+systems the libraries are called \fBlibpcre2-8\fP, \fBlibpcre2-16\fP, and
+\fBlibpcre2-32\fP, and they can also co-exist with the original PCRE libraries.
+.P
+Character strings are passed to and from a PCRE2 library as a sequence of
+unsigned integers in code units of the appropriate width. Every PCRE2 function
+comes in three different forms, one for each library, for example:
+.sp
+ \fBpcre2_compile_8()\fP
+ \fBpcre2_compile_16()\fP
+ \fBpcre2_compile_32()\fP
+.sp
+There are also three different sets of data types:
+.sp
+ \fBPCRE2_UCHAR8, PCRE2_UCHAR16, PCRE2_UCHAR32\fP
+ \fBPCRE2_SPTR8, PCRE2_SPTR16, PCRE2_SPTR32\fP
+.sp
+The UCHAR types define unsigned code units of the appropriate widths. For
+example, PCRE2_UCHAR16 is usually defined as `uint16_t'. The SPTR types are
+constant pointers to the equivalent UCHAR types, that is, they are pointers to
+vectors of unsigned code units.
+.P
+Many applications use only one code unit width. For their convenience, macros
+are defined whose names are the generic forms such as \fBpcre2_compile()\fP and
+PCRE2_SPTR. These macros use the value of the macro PCRE2_CODE_UNIT_WIDTH to
+generate the appropriate width-specific function and macro names.
+PCRE2_CODE_UNIT_WIDTH is not defined by default. An application must define it
+to be 8, 16, or 32 before including \fBpcre2.h\fP in order to make use of the
+generic names.
+.P
+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 \fBpcre2.h\fP, 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.)
+.P
+If PCRE2_CODE_UNIT_WIDTH is not defined before including \fBpcre2.h\fP, a
+compiler error occurs.
+.P
+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
+\fBpcre2_compile_16()\fP, you must do so with \fBpcre2_match_16()\fP, not
+\fBpcre2_match_8()\fP or \fBpcre2_match_32()\fP.
+.P
+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.
+.
+.
+.SH "PCRE2 API OVERVIEW"
+.rs
+.sp
+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. They are described in the
+.\" HREF
+\fBpcre2posix\fP
+.\"
+documentation. Both these APIs define a set of C function calls.
+.P
+The native API C data types, function prototypes, option values, and error
+codes are defined in the header file \fBpcre2.h\fP, 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.
+.P
+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
+\fBpcre2.h\fP.
+.P
+The functions \fBpcre2_compile()\fP and \fBpcre2_match()\fP 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
+the file called \fIpcre2demo.c\fP in the PCRE2 source distribution. A listing
+of this program is given in the
+.\" HREF
+\fBpcre2demo\fP
+.\"
+documentation, and the
+.\" HREF
+\fBpcre2sample\fP
+.\"
+documentation describes how to compile and run it.
+.P
+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.
+.P
+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 \fBpcre2_jit_compile()\fP after a pattern has been
+successfully compiled by \fBpcre2_compile()\fP. This does nothing if JIT
+support is not available.
+.P
+More complicated programs might need to make use of the specialist functions
+\fBpcre2_jit_stack_create()\fP, \fBpcre2_jit_stack_free()\fP, and
+\fBpcre2_jit_stack_assign()\fP in order to control the JIT code's memory usage.
+.P
+JIT matching is automatically used by \fBpcre2_match()\fP 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
+.\" HREF
+\fBpcre2jit\fP
+.\"
+documentation.
+.P
+A second matching function, \fBpcre2_dfa_match()\fP, 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
+point in the subject), and scans the subject just once (unless there are
+lookaround assertions). However, this algorithm does not return captured
+substrings. A description of the two matching algorithms and their advantages
+and disadvantages is given in the
+.\" HREF
+\fBpcre2matching\fP
+.\"
+documentation. There is no JIT support for \fBpcre2_dfa_match()\fP.
+.P
+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 \fBpcre2_match()\fP. They are:
+.sp
+ \fBpcre2_substring_copy_byname()\fP
+ \fBpcre2_substring_copy_bynumber()\fP
+ \fBpcre2_substring_get_byname()\fP
+ \fBpcre2_substring_get_bynumber()\fP
+ \fBpcre2_substring_list_get()\fP
+ \fBpcre2_substring_length_byname()\fP
+ \fBpcre2_substring_length_bynumber()\fP
+ \fBpcre2_substring_nametable_scan()\fP
+ \fBpcre2_substring_number_from_name()\fP
+.sp
+\fBpcre2_substring_free()\fP and \fBpcre2_substring_list_free()\fP are also
+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.
+.P
+The function \fBpcre2_substitute()\fP can be called to match a pattern and
+return a copy of the subject string with substitutions for parts that were
+matched.
+.P
+Functions whose names begin with \fBpcre2_serialize_\fP are used for saving
+compiled patterns on disc or elsewhere, and reloading them later.
+.P
+Finally, there are functions for finding out information about a compiled
+pattern (\fBpcre2_pattern_info()\fP) and about the configuration with which
+PCRE2 was built (\fBpcre2_config()\fP).
+.P
+Functions with names ending with \fB_free()\fP 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.
+.
+.
+.SH "STRING LENGTHS AND OFFSETS"
+.rs
+.sp
+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 \fIsize_t\fP. The largest
+value that can be stored in such a type (that is ~(PCRE2_SIZE)0) is reserved
+as a special indicator for zero-terminated strings and unset offsets.
+Therefore, the longest string that can be handled is one less than this
+maximum.
+.
+.
+.\" HTML <a name="newlines"></a>
+.SH NEWLINES
+.rs
+.sp
+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
+Unicode newline sequence. The Unicode newline sequences are the three just
+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).
+.P
+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,
+the newline convention can be changed by an application when calling
+\fBpcre2_compile()\fP, or it can be specified by special text at the start of
+the pattern itself; this overrides any other settings. See the
+.\" HREF
+\fBpcre2pattern\fP
+.\"
+page for details of the special character sequences.
+.P
+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
+metacharacters, the handling of #-comments in /x mode, and, when CRLF is a
+recognized line ending sequence, the match position advancement for a
+non-anchored pattern. There is more detail about this in the
+.\" HTML <a href="#matchoptions">
+.\" </a>
+section on \fBpcre2_match()\fP options
+.\"
+below.
+.P
+The choice of newline convention does not affect the interpretation of
+the \en or \er escape sequences, nor does it affect what \eR matches; this has
+its own separate convention.
+.
+.
+.SH MULTITHREADING
+.rs
+.sp
+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.
+.P
+There are several different blocks of data that are used to pass information
+between the application and the PCRE2 libraries.
+.
+.
+.SS "The compiled pattern"
+.rs
+.sp
+A pointer to the compiled form of a pattern is returned to the user when
+\fBpcre2_compile()\fP is successful. The data in the compiled pattern is fixed,
+and does not change when the pattern is matched. Therefore, it is thread-safe,
+that is, the same compiled pattern can be used by more than one thread
+simultaneously. For example, an application can compile all its patterns at the
+start, before forking off multiple threads that use them. However, if the
+just-in-time (JIT) optimization feature is being used, it needs separate memory
+stack areas for each thread. See the
+.\" HREF
+\fBpcre2jit\fP
+.\"
+documentation for more details.
+.P
+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, at
+least until a pattern has been compiled. The logic can be something like this:
+.sp
+ Get a read-only (shared) lock (mutex) for pointer
+ if (pointer == NULL)
+ {
+ Get a write (unique) lock for pointer
+ pointer = pcre2_compile(...
+ }
+ Release the lock
+ Use pointer in pcre2_match()
+.sp
+Of course, testing for compilation errors should also be included in the code.
+.P
+If JIT is being used, but the JIT compilation is not being done immediately,
+(perhaps waiting to see if the pattern is used often enough) similar logic is
+required. JIT compilation updates a pointer within the compiled code block, so
+a thread must gain unique write access to the pointer before calling
+\fBpcre2_jit_compile()\fP. Alternatively, \fBpcre2_code_copy()\fP or
+\fBpcre2_code_copy_with_tables()\fP can be used to obtain a private copy of the
+compiled code before calling the JIT compiler.
+.
+.
+.SS "Context blocks"
+.rs
+.sp
+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
+in a context is a convenient way of passing them to a PCRE2 function without
+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.
+.P
+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.
+.
+.
+.SS "Match blocks"
+.rs
+.sp
+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.
+.
+.
+.SH "PCRE2 CONTEXTS"
+.rs
+.sp
+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
+reasonable size, and at the same time to keep the API extensible, "uncommon"
+parameters are passed to certain functions in a \fBcontext\fP instead of
+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.
+.P
+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.
+.
+.
+.SS "The general context"
+.rs
+.sp
+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'
+because in future other fields may be added. If you do not want to supply your
+own custom memory management functions, you do not need to bother with a
+general context. A general context is created by:
+.sp
+.nf
+.B pcre2_general_context *pcre2_general_context_create(
+.B " void *(*\fIprivate_malloc\fP)(PCRE2_SIZE, void *),"
+.B " void (*\fIprivate_free\fP)(void *, void *), void *\fImemory_data\fP);"
+.fi
+.sp
+The two function pointers specify custom memory management functions, whose
+prototypes are:
+.sp
+ \fBvoid *private_malloc(PCRE2_SIZE, void *);\fP
+ \fBvoid private_free(void *, void *);\fP
+.sp
+Whenever code in PCRE2 calls these functions, the final argument is the value
+of \fImemory_data\fP. Either of the first two arguments of the creation
+function may be NULL, in which case the system memory management functions
+\fImalloc()\fP and \fIfree()\fP are used. (This is not currently useful, as
+there are no other fields in a general context, but in future there might be.)
+The \fIprivate_malloc()\fP function is used (if supplied) to obtain memory for
+storing the context, and all three values are saved as part of the context.
+.P
+Whenever PCRE2 creates a data block of any kind, the block contains a pointer
+to the \fIfree()\fP function that matches the \fImalloc()\fP function that was
+used. When the time comes to free the block, this function is called.
+.P
+A general context can be copied by calling:
+.sp
+.nf
+.B pcre2_general_context *pcre2_general_context_copy(
+.B " pcre2_general_context *\fIgcontext\fP);"
+.fi
+.sp
+The memory used for a general context should be freed by calling:
+.sp
+.nf
+.B void pcre2_general_context_free(pcre2_general_context *\fIgcontext\fP);
+.fi
+.sp
+If this function is passed a NULL argument, it returns immediately without
+doing anything.
+.
+.
+.\" HTML <a name="compilecontext"></a>
+.SS "The compile context"
+.rs
+.sp
+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:
+.sp
+ What \eR matches (Unicode newlines or CR, LF, CRLF only)
+ PCRE2's character tables
+ The newline character sequence
+ The compile time nested parentheses limit
+ The maximum length of the pattern string
+ The extra options bits (none set by default)
+.sp
+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
+\fIpcre2_compile()\fP.
+.P
+A compile context is created, copied, and freed by the following functions:
+.sp
+.nf
+.B pcre2_compile_context *pcre2_compile_context_create(
+.B " pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B pcre2_compile_context *pcre2_compile_context_copy(
+.B " pcre2_compile_context *\fIccontext\fP);"
+.sp
+.B void pcre2_compile_context_free(pcre2_compile_context *\fIccontext\fP);
+.fi
+.sp
+A compile context is created with default values for its parameters. These can
+be changed by calling the following functions, which return 0 on success, or
+PCRE2_ERROR_BADDATA if invalid data is detected.
+.sp
+.nf
+.B int pcre2_set_bsr(pcre2_compile_context *\fIccontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.fi
+.sp
+The value must be PCRE2_BSR_ANYCRLF, to specify that \eR matches only CR, LF,
+or CRLF, or PCRE2_BSR_UNICODE, to specify that \eR matches any Unicode line
+ending sequence. The value is used by the JIT compiler and by the two
+interpreted matching functions, \fIpcre2_match()\fP and
+\fIpcre2_dfa_match()\fP.
+.sp
+.nf
+.B int pcre2_set_character_tables(pcre2_compile_context *\fIccontext\fP,
+.B " const unsigned char *\fItables\fP);"
+.fi
+.sp
+The value must be the result of a call to \fIpcre2_maketables()\fP, whose only
+argument is a general context. This function builds a set of character tables
+in the current locale.
+.sp
+.nf
+.B int pcre2_set_compile_extra_options(pcre2_compile_context *\fIccontext\fP,
+.B " uint32_t \fIextra_options\fP);"
+.fi
+.sp
+As PCRE2 has developed, almost all the 32 option bits that are available in
+the \fIoptions\fP argument of \fBpcre2_compile()\fP have been used up. To avoid
+running out, the compile context contains a set of extra option bits which are
+used for some newer, assumed rarer, options. This function sets those bits. It
+always sets all the bits (either on or off). It does not modify any existing
+setting. The available options are defined in the section entitled "Extra
+compile options"
+.\" HTML <a href="#extracompileoptions">
+.\" </a>
+below.
+.\"
+.sp
+.nf
+.B int pcre2_set_max_pattern_length(pcre2_compile_context *\fIccontext\fP,
+.B " PCRE2_SIZE \fIvalue\fP);"
+.fi
+.sp
+This sets a maximum length, in code units, for any pattern string that is
+compiled with this context. If the pattern is longer, an error is generated.
+This facility is provided so that applications that accept patterns from
+external sources can limit their size. The default is the largest number that a
+PCRE2_SIZE variable can hold, which is effectively unlimited.
+.sp
+.nf
+.B int pcre2_set_newline(pcre2_compile_context *\fIccontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.fi
+.sp
+This specifies which characters or character sequences are to be recognized as
+newlines. The value must be one of PCRE2_NEWLINE_CR (carriage return only),
+PCRE2_NEWLINE_LF (linefeed only), PCRE2_NEWLINE_CRLF (the two-character
+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).
+.P
+A pattern can override the value set in the compile context by starting with a
+sequence such as (*CRLF). See the
+.\" HREF
+\fBpcre2pattern\fP
+.\"
+page for details.
+.P
+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
+subsequent use by the JIT compiler and by the two interpreted matching
+functions, \fIpcre2_match()\fP and \fIpcre2_dfa_match()\fP.
+.sp
+.nf
+.B int pcre2_set_parens_nest_limit(pcre2_compile_context *\fIccontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.fi
+.sp
+This parameter ajusts the limit, set when PCRE2 is built (default 250), on the
+depth of parenthesis nesting in a pattern. This limit stops rogue patterns
+using up too much system stack when being compiled. The limit applies to
+parentheses of all kinds, not just capturing parentheses.
+.sp
+.nf
+.B int pcre2_set_compile_recursion_guard(pcre2_compile_context *\fIccontext\fP,
+.B " int (*\fIguard_function\fP)(uint32_t, void *), void *\fIuser_data\fP);"
+.fi
+.sp
+There is at least one application that runs PCRE2 in threads with very limited
+system stack, where running out of stack is to be avoided at all costs. The
+parenthesis limit above cannot take account of how much stack is actually
+available during compilation. For a finer control, you can supply a function
+that is called whenever \fBpcre2_compile()\fP 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).
+.P
+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
+\fBpcre2_set_compile_recursion_guard()\fP. The callout function should return
+zero if all is well, or non-zero to force an error.
+.
+.
+.\" HTML <a name="matchcontext"></a>
+.SS "The match context"
+.rs
+.sp
+A match context is required if you want to:
+.sp
+ Set up a callout function
+ Set an offset limit for matching an unanchored pattern
+ Change the limit on the amount of heap used when matching
+ Change the backtracking match limit
+ Change the backtracking depth limit
+ Set custom memory management specifically for the match
+.sp
+If none of these apply, just pass NULL as the context argument of
+\fBpcre2_match()\fP, \fBpcre2_dfa_match()\fP, or \fBpcre2_jit_match()\fP.
+.P
+A match context is created, copied, and freed by the following functions:
+.sp
+.nf
+.B pcre2_match_context *pcre2_match_context_create(
+.B " pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B pcre2_match_context *pcre2_match_context_copy(
+.B " pcre2_match_context *\fImcontext\fP);"
+.sp
+.B void pcre2_match_context_free(pcre2_match_context *\fImcontext\fP);
+.fi
+.sp
+A match context is created with default values for its parameters. These can
+be changed by calling the following functions, which return 0 on success, or
+PCRE2_ERROR_BADDATA if invalid data is detected.
+.sp
+.nf
+.B int pcre2_set_callout(pcre2_match_context *\fImcontext\fP,
+.B " int (*\fIcallout_function\fP)(pcre2_callout_block *, void *),"
+.B " void *\fIcallout_data\fP);"
+.fi
+.sp
+This sets up a "callout" function for PCRE2 to call at specified points
+during a matching operation. Details are given in the
+.\" HREF
+\fBpcre2callout\fP
+.\"
+documentation.
+.sp
+.nf
+.B int pcre2_set_offset_limit(pcre2_match_context *\fImcontext\fP,
+.B " PCRE2_SIZE \fIvalue\fP);"
+.fi
+.sp
+The \fIoffset_limit\fP parameter limits how far an unanchored search can
+advance in the subject string. The default value is PCRE2_UNSET. The
+\fBpcre2_match()\fP and \fBpcre2_dfa_match()\fP functions return
+PCRE2_ERROR_NOMATCH if a match with a starting point before or at the given
+offset is not found. The \fBpcre2_substitute()\fP function makes no more
+substitutions.
+.P
+For example, if the pattern /abc/ is matched against "123abc" with an offset
+limit less than 3, the result is PCRE2_ERROR_NO_MATCH. A match can never be
+found if the \fIstartoffset\fP argument of \fBpcre2_match()\fP,
+\fBpcre2_dfa_match()\fP, or \fBpcre2_substitute()\fP is greater than the offset
+limit set in the match context.
+.P
+When using this facility, you must set the PCRE2_USE_OFFSET_LIMIT option when
+calling \fBpcre2_compile()\fP 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.
+.P
+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
+newline that follows the start of matching in the subject. If this is set with
+an offset limit, a match must occur in the first line and also within the
+offset limit. In other words, whichever limit comes first is used.
+.sp
+.nf
+.B int pcre2_set_heap_limit(pcre2_match_context *\fImcontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.fi
+.sp
+The \fIheap_limit\fP parameter specifies, in units of kibibytes (1024 bytes),
+the maximum amount of heap memory that \fBpcre2_match()\fP may use to hold
+backtracking information when running an interpretive match. This limit also
+applies to \fBpcre2_dfa_match()\fP, which may use the heap when processing
+patterns with a lot of nested pattern recursion or lookarounds or atomic
+groups. This limit does not apply to matching with the JIT optimization, which
+has its own memory control arrangements (see the
+.\" HREF
+\fBpcre2jit\fP
+.\"
+documentation for more details). If the limit is reached, the negative error
+code PCRE2_ERROR_HEAPLIMIT is returned. The default limit can be set when PCRE2
+is built; if it is not, the default is set very large and is essentially
+"unlimited".
+.P
+A value for the heap limit may also be supplied by an item at the start of a
+pattern of the form
+.sp
+ (*LIMIT_HEAP=ddd)
+.sp
+where ddd is a decimal number. However, such a setting is ignored unless ddd is
+less than the limit set by the caller of \fBpcre2_match()\fP or, if no such
+limit is set, less than the default.
+.P
+The \fBpcre2_match()\fP function starts out using a 20KiB vector on the system
+stack for recording backtracking points. The more nested backtracking points
+there are (that is, the deeper the search tree), the more memory is needed.
+Heap memory is used only if the initial vector is too small. If the heap limit
+is set to a value less than 21 (in particular, zero) no heap memory will be
+used. In this case, only patterns that do not have a lot of nested backtracking
+can be successfully processed.
+.P
+Similarly, for \fBpcre2_dfa_match()\fP, a vector on the system stack is used
+when processing pattern recursions, lookarounds, or atomic groups, and only if
+this is not big enough is heap memory used. In this case, too, setting a value
+of zero disables the use of the heap.
+.sp
+.nf
+.B int pcre2_set_match_limit(pcre2_match_context *\fImcontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.fi
+.sp
+The \fImatch_limit\fP parameter provides a means of preventing PCRE2 from using
+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.
+.P
+There is an internal counter in \fBpcre2_match()\fP that is incremented each
+time round its main matching loop. If this value reaches the match limit,
+\fBpcre2_match()\fP returns the negative value PCRE2_ERROR_MATCHLIMIT. This has
+the effect of limiting the amount of backtracking that can take place. For
+patterns that are not anchored, the count restarts from zero for each position
+in the subject string. This limit also applies to \fBpcre2_dfa_match()\fP,
+though the counting is done in a different way.
+.P
+When \fBpcre2_match()\fP is called with a pattern that was successfully
+processed by \fBpcre2_jit_compile()\fP, 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 \fImatch_limit\fP value
+is also used in this case (but in a different way) to limit how long the
+matching can continue.
+.P
+The default value for the limit can be set when PCRE2 is built; the default
+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
+.sp
+ (*LIMIT_MATCH=ddd)
+.sp
+where ddd is a decimal number. However, such a setting is ignored unless ddd is
+less than the limit set by the caller of \fBpcre2_match()\fP or
+\fBpcre2_dfa_match()\fP or, if no such limit is set, less than the default.
+.sp
+.nf
+.B int pcre2_set_depth_limit(pcre2_match_context *\fImcontext\fP,
+.B " uint32_t \fIvalue\fP);"
+.fi
+.sp
+This parameter limits the depth of nested backtracking in \fBpcre2_match()\fP.
+Each time a nested backtracking point is passed, a new memory "frame" is used
+to remember the state of matching at that point. Thus, this parameter
+indirectly limits the amount of memory that is used in a match. However,
+because the size of each memory "frame" depends on the number of capturing
+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.
+.P
+The depth limit is not relevant, and is ignored, when matching is done using
+JIT compiled code. However, it is supported by \fBpcre2_dfa_match()\fP, which
+uses it to limit the depth of nested internal recursive function calls that
+implement atomic groups, lookaround assertions, and pattern recursions. This
+limits, indirectly, the amount of system stack that is used. It was more useful
+in versions before 10.32, when stack memory was used for local workspace
+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.
+.P
+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
+recursive pattern such as /(.(?2))((?1)|)/, when matched to a very long string
+using \fBpcre2_dfa_match()\fP, can use a great deal of memory. However, it is
+probably better to limit heap usage directly by calling
+\fBpcre2_set_heap_limit()\fP.
+.P
+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, \fBpcre2_match()\fP or \fBpcre2_dfa_match()\fP
+returns PCRE2_ERROR_DEPTHLIMIT. A value for the depth limit may also be
+supplied by an item at the start of a pattern of the form
+.sp
+ (*LIMIT_DEPTH=ddd)
+.sp
+where ddd is a decimal number. However, such a setting is ignored unless ddd is
+less than the limit set by the caller of \fBpcre2_match()\fP or
+\fBpcre2_dfa_match()\fP or, if no such limit is set, less than the default.
+.
+.
+.SH "CHECKING BUILD-TIME OPTIONS"
+.rs
+.sp
+.B int pcre2_config(uint32_t \fIwhat\fP, void *\fIwhere\fP);
+.P
+The function \fBpcre2_config()\fP makes it possible for a PCRE2 client to
+discover which optional features have been compiled into the PCRE2 library. The
+.\" HREF
+\fBpcre2build\fP
+.\"
+documentation has more details about these optional features.
+.P
+The first argument for \fBpcre2_config()\fP 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
+needed for the requested information. For calls that return numerical values,
+the value is in bytes; when requesting these values, \fIwhere\fP should point
+to appropriately aligned memory. For calls that return strings, the required
+length is given in code units, not counting the terminating zero.
+.P
+When requesting information, the returned value from \fBpcre2_config()\fP 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
+available:
+.sp
+ PCRE2_CONFIG_BSR
+.sp
+The output is a uint32_t integer whose value indicates what character
+sequences the \eR escape sequence matches by default. A value of
+PCRE2_BSR_UNICODE means that \eR matches any Unicode line ending sequence; a
+value of PCRE2_BSR_ANYCRLF means that \eR matches only CR, LF, or CRLF. The
+default can be overridden when a pattern is compiled.
+.sp
+ PCRE2_CONFIG_COMPILED_WIDTHS
+.sp
+The output is a uint32_t integer whose lower bits indicate which code unit
+widths were selected when PCRE2 was built. The 1-bit indicates 8-bit support,
+and the 2-bit and 4-bit indicate 16-bit and 32-bit support, respectively.
+.sp
+ PCRE2_CONFIG_DEPTHLIMIT
+.sp
+The output is a uint32_t integer that gives the default limit for the depth of
+nested backtracking in \fBpcre2_match()\fP or the depth of nested recursions,
+lookarounds, and atomic groups in \fBpcre2_dfa_match()\fP. Further details are
+given with \fBpcre2_set_depth_limit()\fP above.
+.sp
+ PCRE2_CONFIG_HEAPLIMIT
+.sp
+The output is a uint32_t integer that gives, in kibibytes, the default limit
+for the amount of heap memory used by \fBpcre2_match()\fP or
+\fBpcre2_dfa_match()\fP. Further details are given with
+\fBpcre2_set_heap_limit()\fP above.
+.sp
+ PCRE2_CONFIG_JIT
+.sp
+The output is a uint32_t integer that is set to one if support for just-in-time
+compiling is available; otherwise it is set to zero.
+.sp
+ PCRE2_CONFIG_JITTARGET
+.sp
+The \fIwhere\fP argument should point to a buffer that is at least 48 code
+units long. (The exact length required can be found by calling
+\fBpcre2_config()\fP with \fBwhere\fP set to NULL.) The buffer is filled with a
+string that contains the name of the architecture for which the JIT compiler is
+configured, for example "x86 32bit (little endian + unaligned)". If JIT support
+is not available, PCRE2_ERROR_BADOPTION is returned, otherwise the number of
+code units used is returned. This is the length of the string, plus one unit
+for the terminating zero.
+.sp
+ PCRE2_CONFIG_LINKSIZE
+.sp
+The output is a uint32_t integer that contains the number of bytes used for
+internal linkage in compiled regular expressions. When PCRE2 is configured, the
+value can be set to 2, 3, or 4, with the default being 2. This is the value
+that is returned by \fBpcre2_config()\fP. However, when the 16-bit library is
+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.
+.P
+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
+be compiled by those two libraries, but at the expense of slower matching.
+.sp
+ PCRE2_CONFIG_MATCHLIMIT
+.sp
+The output is a uint32_t integer that gives the default match limit for
+\fBpcre2_match()\fP. Further details are given with
+\fBpcre2_set_match_limit()\fP above.
+.sp
+ PCRE2_CONFIG_NEWLINE
+.sp
+The output is a uint32_t integer whose value specifies the default character
+sequence that is recognized as meaning "newline". The values are:
+.sp
+ PCRE2_NEWLINE_CR Carriage return (CR)
+ PCRE2_NEWLINE_LF Linefeed (LF)
+ PCRE2_NEWLINE_CRLF Carriage return, linefeed (CRLF)
+ PCRE2_NEWLINE_ANY Any Unicode line ending
+ PCRE2_NEWLINE_ANYCRLF Any of CR, LF, or CRLF
+ PCRE2_NEWLINE_NUL The NUL character (binary zero)
+.sp
+The default should normally correspond to the standard sequence for your
+operating system.
+.sp
+ PCRE2_CONFIG_NEVER_BACKSLASH_C
+.sp
+The output is a uint32_t integer that is set to one if the use of \eC was
+permanently disabled when PCRE2 was built; otherwise it is set to zero.
+.sp
+ PCRE2_CONFIG_PARENSLIMIT
+.sp
+The output is a uint32_t integer that gives the maximum depth of nesting
+of parentheses (of any kind) in a pattern. This limit is imposed to cap the
+amount of system stack used when a pattern is compiled. It is specified when
+PCRE2 is built; the default is 250. This limit does not take into account the
+stack that may already be used by the calling application. For finer control
+over compilation stack usage, see \fBpcre2_set_compile_recursion_guard()\fP.
+.sp
+ PCRE2_CONFIG_STACKRECURSE
+.sp
+This parameter is obsolete and should not be used in new code. The output is a
+uint32_t integer that is always set to zero.
+.sp
+ PCRE2_CONFIG_UNICODE_VERSION
+.sp
+The \fIwhere\fP argument should point to a buffer that is at least 24 code
+units long. (The exact length required can be found by calling
+\fBpcre2_config()\fP with \fBwhere\fP set to NULL.) If PCRE2 has been compiled
+without Unicode support, the buffer is filled with the text "Unicode not
+supported". Otherwise, the Unicode version string (for example, "8.0.0") is
+inserted. The number of code units used is returned. This is the length of the
+string plus one unit for the terminating zero.
+.sp
+ PCRE2_CONFIG_UNICODE
+.sp
+The output is a uint32_t integer that is set to one if Unicode support is
+available; otherwise it is set to zero. Unicode support implies UTF support.
+.sp
+ PCRE2_CONFIG_VERSION
+.sp
+The \fIwhere\fP argument should point to a buffer that is at least 24 code
+units long. (The exact length required can be found by calling
+\fBpcre2_config()\fP with \fBwhere\fP set to NULL.) The buffer is filled with
+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.
+.
+.
+.\" HTML <a name="compiling"></a>
+.SH "COMPILING A PATTERN"
+.rs
+.sp
+.nf
+.B pcre2_code *pcre2_compile(PCRE2_SPTR \fIpattern\fP, PCRE2_SIZE \fIlength\fP,
+.B " uint32_t \fIoptions\fP, int *\fIerrorcode\fP, PCRE2_SIZE *\fIerroroffset,\fP"
+.B " pcre2_compile_context *\fIccontext\fP);"
+.sp
+.B void pcre2_code_free(pcre2_code *\fIcode\fP);
+.sp
+.B pcre2_code *pcre2_code_copy(const pcre2_code *\fIcode\fP);
+.sp
+.B pcre2_code *pcre2_code_copy_with_tables(const pcre2_code *\fIcode\fP);
+.fi
+.P
+The \fBpcre2_compile()\fP 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
+PCRE2_ZERO_TERMINATED. The function returns a pointer to a block of memory that
+contains the compiled pattern and related data, or NULL if an error occurred.
+.P
+If the compile context argument \fIccontext\fP is NULL, memory for the compiled
+pattern is obtained by calling \fBmalloc()\fP. Otherwise, it is obtained from
+the same memory function that was used for the compile context. The caller must
+free the memory by calling \fBpcre2_code_free()\fP when it is no longer needed.
+If \fBpcre2_code_free()\fP is called with a NULL argument, it returns
+immediately, without doing anything.
+.P
+The function \fBpcre2_code_copy()\fP 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
+.\" HTML <a href="#jitcompiling">
+.\" </a>
+below),
+.\"
+the JIT information cannot be copied (because it is position-dependent).
+The new copy can initially be used only for non-JIT matching, though it can be
+passed to \fBpcre2_jit_compile()\fP if required. If \fBpcre2_code_copy()\fP is
+called with a NULL argument, it returns NULL.
+.P
+The \fBpcre2_code_copy()\fP 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
+pattern; the new pattern code points to the same tables as the original code.
+(See
+.\" HTML <a href="#jitcompiling">
+.\" </a>
+"Locale Support"
+.\"
+below for details of these character tables.) In many applications the same
+tables are used throughout, so this behaviour is appropriate. Nevertheless,
+there are occasions when a copy of a compiled pattern and the relevant tables
+are needed. The \fBpcre2_code_copy_with_tables()\fP provides this facility.
+Copies of both the code and the tables are made, with the new code pointing to
+the new tables. The memory for the new tables is automatically freed when
+\fBpcre2_code_free()\fP is called for the new copy of the compiled code. If
+\fBpcre2_code_copy_withy_tables()\fP is called with a NULL argument, it returns
+NULL.
+.P
+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 running a match, you
+must not free a compiled pattern (or a subject string) until after all
+operations on the
+.\" HTML <a href="#matchdatablock">
+.\" </a>
+match data block
+.\"
+have taken place.
+.P
+The \fIoptions\fP argument for \fBpcre2_compile()\fP contains various bit
+settings that affect the compilation. It should be zero if no options are
+required. The available options are described below. Some of them (in
+particular, those that are compatible with Perl, but some others as well) can
+also be set and unset from within the pattern (see the detailed description in
+the
+.\" HREF
+\fBpcre2pattern\fP
+.\"
+documentation).
+.P
+For those options that can be different in different parts of the pattern, the
+contents of the \fIoptions\fP 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.
+.P
+Other, less frequently required compile-time parameters (for example, the
+newline setting) can be provided in a compile context (as described
+.\" HTML <a href="#compilecontext">
+.\" </a>
+above).
+.\"
+.P
+If \fIerrorcode\fP or \fIerroroffset\fP is NULL, \fBpcre2_compile()\fP returns
+NULL immediately. Otherwise, the variables to which these point are set to an
+error code and an offset (number of code units) within the pattern,
+respectively, when \fBpcre2_compile()\fP returns NULL because a compilation
+error has occurred. The values are not defined when compilation is successful
+and \fBpcre2_compile()\fP returns a non-NULL value.
+.P
+There are nearly 100 positive error codes that \fBpcre2_compile()\fP may return
+if it finds an error in the pattern. There are also some negative error codes
+that are used for invalid UTF strings. These are the same as given by
+\fBpcre2_match()\fP and \fBpcre2_dfa_match()\fP, and are described in the
+.\" HREF
+\fBpcre2unicode\fP
+.\"
+page. There is no separate documentation for the positive error codes, because
+the textual error messages that are obtained by calling the
+\fBpcre2_get_error_message()\fP function (see "Obtaining a textual error
+message"
+.\" HTML <a href="#geterrormessage">
+.\" </a>
+below)
+.\"
+should be self-explanatory. Macro names starting with PCRE2_ERROR_ are defined
+for both positive and negative error codes in \fBpcre2.h\fP.
+.P
+The value returned in \fIerroroffset\fP is an indication of where in the
+pattern the error occurred. It is not necessarily the furthest point in the
+pattern that was read. For example, after the error "lookbehind assertion is
+not fixed length", the error offset points to the start of the failing
+assertion. For an invalid UTF-8 or UTF-16 string, the offset is that of the
+first code unit of the failing character.
+.P
+Some errors are not detected until the whole pattern has been scanned; in these
+cases, the offset passed back is the length of the pattern. Note that the
+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.
+.P
+This code fragment shows a typical straightforward call to
+\fBpcre2_compile()\fP:
+.sp
+ pcre2_code *re;
+ PCRE2_SIZE erroffset;
+ int errorcode;
+ re = pcre2_compile(
+ "^A.*Z", /* the pattern */
+ PCRE2_ZERO_TERMINATED, /* the pattern is zero-terminated */
+ 0, /* default options */
+ &errorcode, /* for error code */
+ &erroffset, /* for error offset */
+ NULL); /* no compile context */
+.sp
+The following names for option bits are defined in the \fBpcre2.h\fP header
+file:
+.sp
+ PCRE2_ANCHORED
+.sp
+If this bit is set, the pattern is forced to be "anchored", that is, it is
+constrained to match only at the first matching point in the string that is
+being searched (the "subject string"). This effect can also be achieved by
+appropriate constructs in the pattern itself, which is the only way to do it in
+Perl.
+.sp
+ PCRE2_ALLOW_EMPTY_CLASS
+.sp
+By default, for compatibility with Perl, a closing square bracket that
+immediately follows an opening one is treated as a data character for the
+class. When PCRE2_ALLOW_EMPTY_CLASS is set, it terminates the class, which
+therefore contains no characters and so can never match.
+.sp
+ PCRE2_ALT_BSUX
+.sp
+This option request alternative handling of three escape sequences, which
+makes PCRE2's behaviour more like ECMAscript (aka JavaScript). When it is set:
+.P
+(1) \eU matches an upper case "U" character; by default \eU causes a compile
+time error (Perl uses \eU to upper case subsequent characters).
+.P
+(2) \eu 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, \eu causes a compile time error (Perl uses it to upper
+case the following character).
+.P
+(3) \ex 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
+\ex, but it may have zero, one, or two digits (so, for example, \exz matches a
+binary zero character followed by z).
+.sp
+ PCRE2_ALT_CIRCUMFLEX
+.sp
+In multiline mode (when PCRE2_MULTILINE is set), the circumflex metacharacter
+matches at the start of the subject (unless PCRE2_NOTBOL is set), and also
+after any internal newline. However, it does not match after a newline at the
+end of the subject, for compatibility with Perl. If you want a multiline
+circumflex also to match after a terminating newline, you must set
+PCRE2_ALT_CIRCUMFLEX.
+.sp
+ PCRE2_ALT_VERBNAMES
+.sp
+By default, for compatibility with Perl, the name in any verb sequence such as
+(*MARK: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. However, if the PCRE2_ALT_VERBNAMES
+option is set, normal backslash processing is applied to verb names and only an
+unescaped closing parenthesis terminates the name. A closing parenthesis can be
+included in a name either as \e) or between \eQ and \eE. If the PCRE2_EXTENDED
+or PCRE2_EXTENDED_MORE option is set with PCRE2_ALT_VERBNAMES, unescaped
+whitespace in verb names is skipped and #-comments are recognized, exactly as
+in the rest of the pattern.
+.sp
+ PCRE2_AUTO_CALLOUT
+.sp
+If this bit is set, \fBpcre2_compile()\fP automatically inserts callout items,
+all with number 255, before each pattern item, except immediately before or
+after an explicit callout in the pattern. For discussion of the callout
+facility, see the
+.\" HREF
+\fBpcre2callout\fP
+.\"
+documentation.
+.sp
+ PCRE2_CASELESS
+.sp
+If this bit is set, letters in the pattern match both upper and lower case
+letters in the subject. It is equivalent to Perl's /i option, and it can be
+changed within a pattern by a (?i) option setting. If PCRE2_UTF 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. For lower valued
+characters with only one other case, a lookup table is used for speed. When
+PCRE2_UTF is not 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.
+.sp
+ PCRE2_DOLLAR_ENDONLY
+.sp
+If this bit is set, a dollar metacharacter in the pattern matches only at the
+end of the subject string. Without this option, a dollar also matches
+immediately before a newline at the end of the string (but not before any other
+newlines). The PCRE2_DOLLAR_ENDONLY option is ignored if PCRE2_MULTILINE is
+set. There is no equivalent to this option in Perl, and no way to set it within
+a pattern.
+.sp
+ PCRE2_DOTALL
+.sp
+If this bit is set, a dot metacharacter in the pattern matches any character,
+including one that indicates a newline. However, it only ever matches one
+character, even if newlines are coded as CRLF. Without this option, a dot does
+not match when the current position in the subject is at a newline. This option
+is equivalent to Perl's /s option, and it can be changed within a pattern by a
+(?s) option setting. A negative class such as [^a] always matches newline
+characters, and the \eN escape sequence always matches a non-newline character,
+independent of the setting of PCRE2_DOTALL.
+.sp
+ PCRE2_DUPNAMES
+.sp
+If this bit is set, names used to identify capturing subpatterns need not be
+unique. This can be helpful for certain types of pattern when it is known that
+only one instance of the named subpattern can ever be matched. There are more
+details of named subpatterns below; see also the
+.\" HREF
+\fBpcre2pattern\fP
+.\"
+documentation.
+.sp
+ PCRE2_ENDANCHORED
+.sp
+If this bit is set, the end of any pattern match must be right at the end of
+the string being searched (the "subject string"). If the pattern match
+succeeds by reaching (*ACCEPT), but does not reach the end of the subject, the
+match fails at the current starting point. For unanchored patterns, a new match
+is then tried at the next starting point. However, if the match succeeds by
+reaching the end of the pattern, but not the end of the subject, backtracking
+occurs and an alternative match may be found. Consider these two patterns:
+.sp
+ .(*ACCEPT)|..
+ .|..
+.sp
+If matched against "abc" with PCRE2_ENDANCHORED set, the first matches "c"
+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.
+.P
+For DFA matching with \fBpcre2_dfa_match()\fP, 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
+the end of the subject.
+.sp
+ PCRE2_EXTENDED
+.sp
+If this bit is set, most white space characters in the pattern are totally
+ignored except when escaped or inside a character class. However, white space
+is not allowed within sequences such as (?> that introduce various
+parenthesized subpatterns, nor within numerical quantifiers such as {1,3}.
+Ignorable white space is permitted between an item and a following 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.
+.P
+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
+created by
+.\" HREF
+\fBpcre2_maketables()\fP,
+.\"
+which uses the \fBisspace()\fP function to identify space characters. In most
+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).
+.P
+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),
+U+200F (right-to-left mark), U+2028 (line separator), and U+2029 (paragraph
+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 \eh and \ev escapes in patterns are a much bigger set.
+.P
+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.
+.P
+Which characters are interpreted as newlines can be specified by a setting in
+the compile context that is passed to \fBpcre2_compile()\fP or by a special
+sequence at the start of the pattern, as described in the section entitled
+.\" HTML <a href="pcre2pattern.html#newlines">
+.\" </a>
+"Newline conventions"
+.\"
+in the \fBpcre2pattern\fP documentation. A default is defined when PCRE2 is
+built.
+.sp
+ PCRE2_EXTENDED_MORE
+.sp
+This option has the effect of PCRE2_EXTENDED, but, in addition, unescaped space
+and horizontal tab characters are ignored inside a character class. Note: only
+these two characters are ignored, not the full set of pattern white space
+characters that are ignored outside a character class. PCRE2_EXTENDED_MORE is
+equivalent to Perl's /xx option, and it can be changed within a pattern by a
+(?xx) option setting.
+.sp
+ PCRE2_FIRSTLINE
+.sp
+If this option is set, the start of an unanchored pattern match must be before
+or at the first newline in the subject string following the start of matching,
+though the matched text may continue over the newline. If \fIstartoffset\fP is
+non-zero, the limiting newline is not necessarily the first newline in the
+subject. For example, if the subject string is "abc\enxyz" (where \en
+represents a single-character newline) a pattern match for "yz" succeeds with
+PCRE2_FIRSTLINE if \fIstartoffset\fP is greater than 3. See also
+PCRE2_USE_OFFSET_LIMIT, which provides a more general limiting facility. If
+PCRE2_FIRSTLINE is set with an offset limit, a match must occur in the first
+line and also within the offset limit. In other words, whichever limit comes
+first is used.
+.sp
+ PCRE2_LITERAL
+.sp
+If this option is set, all meta-characters in the pattern are disabled, and it
+is treated as a literal string. Matching literal strings with a regular
+expression engine is not the most efficient way of doing it. If you are doing a
+lot of literal matching and are worried about efficiency, you should consider
+using other approaches. The only other main options that are allowed with
+PCRE2_LITERAL are: PCRE2_ANCHORED, PCRE2_ENDANCHORED, PCRE2_AUTO_CALLOUT,
+PCRE2_CASELESS, PCRE2_FIRSTLINE, PCRE2_NO_START_OPTIMIZE, PCRE2_NO_UTF_CHECK,
+PCRE2_UTF, and PCRE2_USE_OFFSET_LIMIT. The extra options PCRE2_EXTRA_MATCH_LINE
+and PCRE2_EXTRA_MATCH_WORD are also supported. Any other options cause an
+error.
+.sp
+ PCRE2_MATCH_UNSET_BACKREF
+.sp
+If this option is set, a backreference to an unset subpattern group matches an
+empty string (by default this causes the current matching alternative to fail).
+A pattern such as (\e1)(a) succeeds when this option is set (assuming it can
+find an "a" in the subject), whereas it fails by default, for Perl
+compatibility. Setting this option makes PCRE2 behave more like ECMAscript (aka
+JavaScript).
+.sp
+ PCRE2_MULTILINE
+.sp
+By default, for the purposes of matching "start of line" and "end of line",
+PCRE2 treats the subject string as consisting of a single line of characters,
+even if it actually contains newlines. The "start of line" metacharacter (^)
+matches only at the start of the string, and the "end of line" metacharacter
+($) matches only at the end of the string, or before a terminating newline
+(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.
+.P
+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
+is equivalent to Perl's /m option, and it can be changed within a pattern by a
+(?m) option setting. Note that the "start of line" metacharacter does not match
+after a newline at the end of the subject, for compatibility with Perl.
+However, you can change this by setting the PCRE2_ALT_CIRCUMFLEX option. If
+there are no newlines in a subject string, or no occurrences of ^ or $ in a
+pattern, setting PCRE2_MULTILINE has no effect.
+.sp
+ PCRE2_NEVER_BACKSLASH_C
+.sp
+This option locks out the use of \eC in the pattern that is being compiled.
+This escape can cause unpredictable behaviour in UTF-8 or UTF-16 modes, because
+it may leave the current matching point in the middle of a multi-code-unit
+character. This option may be useful in applications that process patterns from
+external sources. Note that there is also a build-time option that permanently
+locks out the use of \eC.
+.sp
+ PCRE2_NEVER_UCP
+.sp
+This option locks out the use of Unicode properties for handling \eB, \eb, \eD,
+\ed, \eS, \es, \eW, \ew, and some of the POSIX character classes, as described
+for the PCRE2_UCP option below. In particular, it prevents the creator of the
+pattern from enabling this facility by starting the pattern with (*UCP). This
+option may be useful in applications that process patterns from external
+sources. The option combination PCRE_UCP and PCRE_NEVER_UCP causes an error.
+.sp
+ PCRE2_NEVER_UTF
+.sp
+This option locks out interpretation of the pattern as UTF-8, UTF-16, or
+UTF-32, depending on which library is in use. In particular, it prevents the
+creator of the pattern from switching to UTF interpretation by starting the
+pattern with (*UTF). This option may be useful in applications that process
+patterns from external sources. The combination of PCRE2_UTF and
+PCRE2_NEVER_UTF causes an error.
+.sp
+ PCRE2_NO_AUTO_CAPTURE
+.sp
+If this option is set, it disables the use of numbered capturing parentheses in
+the pattern. Any opening parenthesis that is not followed by ? behaves as if it
+were followed by ?: but named parentheses can still be used for capturing (and
+they acquire numbers in the usual way). This is the same as Perl's /n option.
+Note that, when this option is set, references to capturing groups
+(backreferences or recursion/subroutine calls) may only refer to named groups,
+though the reference can be by name or by number.
+.sp
+ PCRE2_NO_AUTO_POSSESS
+.sp
+If this option is set, it disables "auto-possessification", which is an
+optimization that, for example, turns a+b into a++b in order to avoid
+backtracks into a+ that can never be successful. However, if callouts are in
+use, auto-possessification means that some callouts are never taken. You can
+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.
+.sp
+ PCRE2_NO_DOTSTAR_ANCHOR
+.sp
+If this option is set, it disables an optimization that is applied when .* is
+the first significant item in a top-level branch of a pattern, and all the
+other branches also start with .* or with \eA or \eG or ^. The optimization is
+automatically disabled for .* if it is inside an atomic group or a capturing
+group that is the subject of a backreference, or if the pattern contains
+(*PRUNE) or (*SKIP). When the optimization is not disabled, such a pattern is
+automatically anchored if PCRE2_DOTALL is set for all the .* items and
+PCRE2_MULTILINE is not set for any ^ 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.
+.sp
+ PCRE2_NO_START_OPTIMIZE
+.sp
+This is an option whose main effect is at matching time. It does not change
+what \fBpcre2_compile()\fP generates, but it does affect the output of the JIT
+compiler.
+.P
+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. This means that a special item
+such as (*COMMIT) at the start of a pattern is not considered until after a
+suitable starting point for the match has been found. Also, when callouts or
+(*MARK) items are in use, these "start-up" optimizations 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.
+.P
+The PCRE2_NO_START_OPTIMIZE option disables the start-up optimizations,
+possibly causing performance to suffer, but ensuring 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.
+.P
+Setting PCRE2_NO_START_OPTIMIZE may change the outcome of a matching operation.
+Consider the pattern
+.sp
+ (*COMMIT)ABC
+.sp
+When this is compiled, PCRE2 records the fact that a match must start with the
+character "A". Suppose the subject string is "DEFABC". The start-up
+optimization scans along the subject, finds "A" and runs the first match
+attempt from there. The (*COMMIT) item means that the pattern must match the
+current starting position, which in this case, it does. However, if the same
+match is run with PCRE2_NO_START_OPTIMIZE set, the initial scan along the
+subject 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".
+.P
+There are also other start-up optimizations. For example, a minimum length for
+the subject may be recorded. Consider the pattern
+.sp
+ (*MARK:A)(X|Y)
+.sp
+The minimum length for a match is one character. If the subject is "ABC", there
+will be attempts to match "ABC", "BC", and "C". An attempt to match an empty
+string at the end of the subject does not take place, because PCRE2 knows that
+the subject is now too short, and so the (*MARK) is never encountered. In this
+case, the optimization does not affect the overall match result, which is still
+"no match", but it does affect the auxiliary information that is returned.
+.sp
+ PCRE2_NO_UTF_CHECK
+.sp
+When PCRE2_UTF is set, the validity of the pattern as a UTF string is
+automatically checked. There are discussions about the validity of
+.\" HTML <a href="pcre2unicode.html#utf8strings">
+.\" </a>
+UTF-8 strings,
+.\"
+.\" HTML <a href="pcre2unicode.html#utf16strings">
+.\" </a>
+UTF-16 strings,
+.\"
+and
+.\" HTML <a href="pcre2unicode.html#utf32strings">
+.\" </a>
+UTF-32 strings
+.\"
+in the
+.\" HREF
+\fBpcre2unicode\fP
+.\"
+document. If an invalid UTF sequence is found, \fBpcre2_compile()\fP returns a
+negative error code.
+.P
+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.
+.P
+Note that this option can also be passed to \fBpcre2_match()\fP and
+\fBpcre_dfa_match()\fP, to suppress UTF validity checking of the subject
+string.
+.P
+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
+points (0xd800 to 0xdfff) are invalid. If you want to allow escape sequences
+such as \ex{d800} you can set the PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES extra
+option, as described in the section entitled "Extra compile options"
+.\" HTML <a href="#extracompileoptions">
+.\" </a>
+below.
+.\"
+However, this is possible only in UTF-8 and UTF-32 modes, because these values
+are not representable in UTF-16.
+.sp
+ PCRE2_UCP
+.sp
+This option changes the way PCRE2 processes \eB, \eb, \eD, \ed, \eS, \es, \eW,
+\ew, and some of the POSIX character classes. By default, only ASCII characters
+are recognized, but if PCRE2_UCP is set, Unicode properties are used instead to
+classify characters. More details are given in the section on
+.\" HTML <a href="pcre2pattern.html#genericchartypes">
+.\" </a>
+generic character types
+.\"
+in the
+.\" HREF
+\fBpcre2pattern\fP
+.\"
+page. If you set PCRE2_UCP, matching one of the items it affects takes much
+longer. The option is available only if PCRE2 has been compiled with Unicode
+support (which is the default).
+.sp
+ PCRE2_UNGREEDY
+.sp
+This option inverts the "greediness" of the quantifiers so that they are not
+greedy by default, but become greedy if followed by "?". It is not compatible
+with Perl. It can also be set by a (?U) option setting within the pattern.
+.sp
+ PCRE2_USE_OFFSET_LIMIT
+.sp
+This option must be set for \fBpcre2_compile()\fP if
+\fBpcre2_set_offset_limit()\fP is going to be used to set a non-default offset
+limit in a match context for matches that use this pattern. An error is
+generated if an offset limit is set without this option. For more details, see
+the description of \fBpcre2_set_offset_limit()\fP in the
+.\" HTML <a href="#matchcontext">
+.\" </a>
+section
+.\"
+that describes match contexts. See also the PCRE2_FIRSTLINE
+option above.
+.sp
+ PCRE2_UTF
+.sp
+This option causes PCRE2 to regard both the pattern and the subject strings
+that are subsequently processed as strings of UTF characters instead of
+single-code-unit strings. It is available when PCRE2 is built to include
+Unicode support (which is the default). If Unicode support is not available,
+the use of this option provokes an error. Details of how PCRE2_UTF changes the
+behaviour of PCRE2 are given in the
+.\" HREF
+\fBpcre2unicode\fP
+.\"
+page. In particular, note that it changes the way PCRE2_CASELESS handles
+characters with code points greater than 127.
+.
+.
+.\" HTML <a name="extracompileoptions"></a>
+.SS "Extra compile options"
+.rs
+.sp
+Unlike the main compile-time options, the extra options are not saved with the
+compiled pattern. The option bits that can be set in a compile context by
+calling the \fBpcre2_set_compile_extra_options()\fP function are as follows:
+.sp
+ PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES
+.sp
+This option applies when compiling a pattern in UTF-8 or UTF-32 mode. It is
+forbidden in UTF-16 mode, and ignored in non-UTF modes. Unicode "surrogate"
+code points in the range 0xd800 to 0xdfff are used in pairs in UTF-16 to encode
+code points with values in the range 0x10000 to 0x10ffff. The surrogates cannot
+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.
+.P
+These values also cause errors if encountered in escape sequences such as
+\ex{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.
+.P
+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
+characters if the matching function is called with PCRE2_NO_UTF_CHECK set.
+.sp
+ PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL
+.sp
+This is a dangerous option. Use with care. By default, an unrecognized escape
+such as \ej or a malformed one such as \ex{2z} causes a compile-time error when
+detected by \fBpcre2_compile()\fP. Perl is somewhat inconsistent in handling
+such items: for example, \ej is treated as a literal "j", and non-hexadecimal
+digits in \ex{} are just ignored, though warnings are given in both cases if
+Perl's warning switch is enabled. However, a malformed octal number after \eo{
+always causes an error in Perl.
+.P
+If the PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL extra option is passed to
+\fBpcre2_compile()\fP, all unrecognized or erroneous escape sequences are
+treated as single-character escapes. For example, \ej is a literal "j" and
+\ex{2z} is treated as the literal string "x{2z}". Setting this option means
+that typos in patterns may go undetected and have unexpected results. This is a
+dangerous option. Use with care.
+.sp
+ PCRE2_EXTRA_MATCH_LINE
+.sp
+This option is provided for use by the \fB-x\fP option of \fBpcre2grep\fP. It
+causes the pattern only to match complete lines. This is achieved by
+automatically inserting the code for "^(?:" at the start of the compiled
+pattern and ")$" at the end. Thus, when PCRE2_MULTILINE is set, the matched
+line may be in the middle of the subject string. This option can be used with
+PCRE2_LITERAL.
+.sp
+ PCRE2_EXTRA_MATCH_WORD
+.sp
+This option is provided for use by the \fB-w\fP option of \fBpcre2grep\fP. It
+causes the pattern only to match strings that have a word boundary at the start
+and the end. This is achieved by automatically inserting the code for "\eb(?:"
+at the start of the compiled pattern and ")\eb" at the end. The option may be
+used with PCRE2_LITERAL. However, it is ignored if PCRE2_EXTRA_MATCH_LINE is
+also set.
+.
+.
+.\" HTML <a name="jitcompiling"></a>
+.SH "JUST-IN-TIME (JIT) COMPILATION"
+.rs
+.sp
+.nf
+.B int pcre2_jit_compile(pcre2_code *\fIcode\fP, uint32_t \fIoptions\fP);
+.sp
+.B int pcre2_jit_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP,
+.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP,"
+.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP,"
+.B " pcre2_match_context *\fImcontext\fP);"
+.sp
+.B void pcre2_jit_free_unused_memory(pcre2_general_context *\fIgcontext\fP);
+.sp
+.B pcre2_jit_stack *pcre2_jit_stack_create(PCRE2_SIZE \fIstartsize\fP,
+.B " PCRE2_SIZE \fImaxsize\fP, pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B void pcre2_jit_stack_assign(pcre2_match_context *\fImcontext\fP,
+.B " pcre2_jit_callback \fIcallback_function\fP, void *\fIcallback_data\fP);"
+.sp
+.B void pcre2_jit_stack_free(pcre2_jit_stack *\fIjit_stack\fP);
+.fi
+.P
+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 \fBpcre2_match()\fP interpretive matching
+function. Full details are given in the
+.\" HREF
+\fBpcre2jit\fP
+.\"
+documentation.
+.P
+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.
+.
+.
+.\" HTML <a name="localesupport"></a>
+.SH "LOCALE SUPPORT"
+.rs
+.sp
+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. This applies only to characters whose code points are less than 256. By
+default, higher-valued code points never match escapes such as \ew or \ed.
+However, if PCRE2 is built with Unicode support, all characters can be tested
+with \ep and \eP, or, alternatively, the PCRE2_UCP option can be set when a
+pattern is compiled; this causes \ew and friends to use Unicode property
+support instead of the built-in tables.
+.P
+The use of locales with Unicode is discouraged. If you are handling characters
+with code points greater than 128, you should either use Unicode support, or
+use locales, but not try to mix the two.
+.P
+PCRE2 contains an internal 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.
+.P
+The internal 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.
+.P
+External tables are built by calling the \fBpcre2_maketables()\fP function, in
+the relevant locale. The result can be passed to \fBpcre2_compile()\fP as often
+as necessary, by creating a compile context and calling
+\fBpcre2_set_character_tables()\fP 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 128 are treated as
+letters), the following code could be used:
+.sp
+ setlocale(LC_CTYPE, "fr_FR");
+ tables = pcre2_maketables(NULL);
+ ccontext = pcre2_compile_context_create(NULL);
+ pcre2_set_character_tables(ccontext, tables);
+ re = pcre2_compile(..., ccontext);
+.sp
+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". It is the
+caller's responsibility to ensure that the memory containing the tables remains
+available for as long as it is needed.
+.P
+The pointer that is passed (via the compile context) to \fBpcre2_compile()\fP
+is saved with the compiled pattern, and the same tables are used by
+\fBpcre2_match()\fP and \fBpcre_dfa_match()\fP. Thus, for any single pattern,
+compilation and matching both happen in the same locale, but different patterns
+can be processed in different locales.
+.
+.
+.\" HTML <a name="infoaboutpattern"></a>
+.SH "INFORMATION ABOUT A COMPILED PATTERN"
+.rs
+.sp
+.nf
+.B int pcre2_pattern_info(const pcre2 *\fIcode\fP, uint32_t \fIwhat\fP, void *\fIwhere\fP);
+.fi
+.P
+The \fBpcre2_pattern_info()\fP function returns general information about a
+compiled pattern. For information about callouts, see the
+.\" HTML <a href="pcre2pattern.html#infoaboutcallouts">
+.\" </a>
+next section.
+.\"
+The first argument for \fBpcre2_pattern_info()\fP is a pointer to the compiled
+pattern. The second argument specifies which piece of information is required,
+and the third argument is a pointer to a variable to receive the data. If the
+third argument is NULL, the first argument is ignored, and the function returns
+the size in bytes of the variable that is required for the information
+requested. Otherwise, the yield of the function is zero for success, or one of
+the following negative numbers:
+.sp
+ PCRE2_ERROR_NULL the argument \fIcode\fP was NULL
+ PCRE2_ERROR_BADMAGIC the "magic number" was not found
+ PCRE2_ERROR_BADOPTION the value of \fIwhat\fP was invalid
+ PCRE2_ERROR_UNSET the requested field is not set
+.sp
+The "magic number" is placed at the start of each compiled pattern as an simple
+check against passing an arbitrary memory pointer. Here is a typical call of
+\fBpcre2_pattern_info()\fP, to obtain the length of the compiled pattern:
+.sp
+ int rc;
+ size_t length;
+ rc = pcre2_pattern_info(
+ re, /* result of pcre2_compile() */
+ PCRE2_INFO_SIZE, /* what is required */
+ &length); /* where to put the data */
+.sp
+The possible values for the second argument are defined in \fBpcre2.h\fP, and
+are as follows:
+.sp
+ PCRE2_INFO_ALLOPTIONS
+ PCRE2_INFO_ARGOPTIONS
+ PCRE2_INFO_EXTRAOPTIONS
+.sp
+Return copies of the pattern's options. The third argument should point to a
+\fBuint32_t\fP variable. PCRE2_INFO_ARGOPTIONS returns exactly the options that
+were passed to \fBpcre2_compile()\fP, whereas PCRE2_INFO_ALLOPTIONS returns
+the compile options as modified by any top-level (*XXX) option settings such as
+(*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.
+.P
+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.)
+.P
+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:
+.sp
+ ^ unless PCRE2_MULTILINE is set
+ \eA always
+ \eG always
+ .* sometimes - see below
+.sp
+When .* is the first significant item, anchoring is possible only when all the
+following are true:
+.sp
+ .* is not in an atomic group
+.\" JOIN
+ .* is not in a capturing group that is the subject
+ of a backreference
+ PCRE2_DOTALL is in force for .*
+ Neither (*PRUNE) nor (*SKIP) appears in the pattern
+ PCRE2_NO_DOTSTAR_ANCHOR is not set
+.sp
+For patterns that are auto-anchored, the PCRE2_ANCHORED bit is set in the
+options returned for PCRE2_INFO_ALLOPTIONS.
+.sp
+ PCRE2_INFO_BACKREFMAX
+.sp
+Return the number of the highest backreference in the pattern. The third
+argument should point to an \fBuint32_t\fP variable. Named subpatterns acquire
+numbers as well as names, and these count towards the highest backreference.
+Backreferences such as \e4 or \eg{12} match the captured characters of the
+given group, but in addition, the check that a capturing group is set in a
+conditional subpattern such as (?(3)a|b) is also a backreference. Zero is
+returned if there are no backreferences.
+.sp
+ PCRE2_INFO_BSR
+.sp
+The output is a uint32_t integer whose value indicates what character sequences
+the \eR escape sequence matches. A value of PCRE2_BSR_UNICODE means that \eR
+matches any Unicode line ending sequence; a value of PCRE2_BSR_ANYCRLF means
+that \eR matches only CR, LF, or CRLF.
+.sp
+ PCRE2_INFO_CAPTURECOUNT
+.sp
+Return the highest capturing subpattern number in the pattern. In patterns
+where (?| is not used, this is also the total number of capturing subpatterns.
+The third argument should point to an \fBuint32_t\fP variable.
+.sp
+ PCRE2_INFO_DEPTHLIMIT
+.sp
+If the pattern set a backtracking depth limit by including an item of the form
+(*LIMIT_DEPTH=nnnn) at the start, the value is returned. The third argument
+should point to a uint32_t integer. If no such value has been set, the call to
+\fBpcre2_pattern_info()\fP returns the error PCRE2_ERROR_UNSET. Note that this
+limit will only be used during matching if it is less than the limit set or
+defaulted by the caller of the match function.
+.sp
+ PCRE2_INFO_FIRSTBITMAP
+.sp
+In the absence of a single first code unit for a non-anchored pattern,
+\fBpcre2_compile()\fP may construct a 256-bit table that defines a fixed set of
+values for the first code unit in any match. For example, a pattern that starts
+with [abc] results in a table with three bits set. When code unit values
+greater than 255 are supported, the flag bit for 255 means "any code unit of
+value 255 or above". If such a table was constructed, a pointer to it is
+returned. Otherwise NULL is returned. The third argument should point to a
+\fBconst uint8_t *\fP variable.
+.sp
+ PCRE2_INFO_FIRSTCODETYPE
+.sp
+Return information about the first code unit of any matched string, for a
+non-anchored pattern. The third argument should point to an \fBuint32_t\fP
+variable. If there is a fixed first value, for example, the letter "c" from a
+pattern such as (cat|cow|coyote), 1 is returned, and the value can be retrieved
+using PCRE2_INFO_FIRSTCODEUNIT. If there is no fixed first value, but it is
+known that a match can occur only at the start of the subject or following a
+newline in the subject, 2 is returned. Otherwise, and for anchored patterns, 0
+is returned.
+.sp
+ PCRE2_INFO_FIRSTCODEUNIT
+.sp
+Return the value of the first code unit of any matched string for a pattern
+where PCRE2_INFO_FIRSTCODETYPE returns 1; otherwise return 0. The third
+argument should point to an \fBuint32_t\fP variable. In the 8-bit library, the
+value is always less than 256. In the 16-bit library the value can be up to
+0xffff. In the 32-bit library in UTF-32 mode the value can be up to 0x10ffff,
+and up to 0xffffffff when not using UTF-32 mode.
+.sp
+ PCRE2_INFO_FRAMESIZE
+.sp
+Return the size (in bytes) of the data frames that are used to remember
+backtracking positions when the pattern is processed by \fBpcre2_match()\fP
+without the use of JIT. The third argument should point to a \fBsize_t\fP
+variable. The frame size depends on the number of capturing parentheses in the
+pattern. Each additional capturing group adds two PCRE2_SIZE variables.
+.sp
+ PCRE2_INFO_HASBACKSLASHC
+.sp
+Return 1 if the pattern contains any instances of \eC, otherwise 0. The third
+argument should point to an \fBuint32_t\fP variable.
+.sp
+ PCRE2_INFO_HASCRORLF
+.sp
+Return 1 if the pattern contains any explicit matches for CR or LF characters,
+otherwise 0. The third argument should point to an \fBuint32_t\fP variable. An
+explicit match is either a literal CR or LF character, or \er or \en or one of
+the equivalent hexadecimal or octal escape sequences.
+.sp
+ PCRE2_INFO_HEAPLIMIT
+.sp
+If the pattern set a heap memory limit by including an item of the form
+(*LIMIT_HEAP=nnnn) at the start, the value is returned. The third argument
+should point to a uint32_t integer. If no such value has been set, the call to
+\fBpcre2_pattern_info()\fP returns the error PCRE2_ERROR_UNSET. Note that this
+limit will only be used during matching if it is less than the limit set or
+defaulted by the caller of the match function.
+.sp
+ PCRE2_INFO_JCHANGED
+.sp
+Return 1 if the (?J) or (?-J) option setting is used in the pattern, otherwise
+0. The third argument should point to an \fBuint32_t\fP variable. (?J) and
+(?-J) set and unset the local PCRE2_DUPNAMES option, respectively.
+.sp
+ PCRE2_INFO_JITSIZE
+.sp
+If the compiled pattern was successfully processed by
+\fBpcre2_jit_compile()\fP, return the size of the JIT compiled code, otherwise
+return zero. The third argument should point to a \fBsize_t\fP variable.
+.sp
+ PCRE2_INFO_LASTCODETYPE
+.sp
+Returns 1 if there is a rightmost literal code unit that must exist in any
+matched string, other than at its start. The third argument should point to an
+\fBuint32_t\fP variable. If there is no such value, 0 is returned. When 1 is
+returned, the code unit value itself can be retrieved using
+PCRE2_INFO_LASTCODEUNIT. For anchored patterns, a last literal value is
+recorded only if it follows something of variable length. For example, for the
+pattern /^a\ed+z\ed+/ the returned value is 1 (with "z" returned from
+PCRE2_INFO_LASTCODEUNIT), but for /^a\edz\ed/ the returned value is 0.
+.sp
+ PCRE2_INFO_LASTCODEUNIT
+.sp
+Return the value of the rightmost literal code unit that must exist in any
+matched string, other than at its start, for a pattern where
+PCRE2_INFO_LASTCODETYPE returns 1. Otherwise, return 0. The third argument
+should point to an \fBuint32_t\fP variable.
+.sp
+ PCRE2_INFO_MATCHEMPTY
+.sp
+Return 1 if the pattern might match an empty string, otherwise 0. The third
+argument should point to an \fBuint32_t\fP variable. When a pattern contains
+recursive subroutine calls it is not always possible to determine whether or
+not it can match an empty string. PCRE2 takes a cautious approach and returns 1
+in such cases.
+.sp
+ PCRE2_INFO_MATCHLIMIT
+.sp
+If the pattern set a match limit by including an item of the form
+(*LIMIT_MATCH=nnnn) at the start, the value is returned. The third argument
+should point to a uint32_t integer. If no such value has been set, the call to
+\fBpcre2_pattern_info()\fP returns the error PCRE2_ERROR_UNSET. Note that this
+limit will only be used during matching if it is less than the limit set or
+defaulted by the caller of the match function.
+.sp
+ PCRE2_INFO_MAXLOOKBEHIND
+.sp
+Return the number of characters (not code units) in the longest lookbehind
+assertion in the pattern. The third argument should point to a uint32_t
+integer. This information is useful when doing multi-segment matching using the
+partial matching facilities. Note that the simple assertions \eb and \eB
+require a one-character lookbehind. \eA also registers a one-character
+lookbehind, though it does not actually inspect the previous character. This is
+to ensure that at least one character from the old segment is retained when a
+new segment is processed. Otherwise, if there are no lookbehinds in the
+pattern, \eA might match incorrectly at the start of a second or subsequent
+segment.
+.sp
+ PCRE2_INFO_MINLENGTH
+.sp
+If a minimum length for matching subject strings was computed, its value is
+returned. Otherwise the returned value is 0. The value is a number of
+characters, which in UTF mode may be different from the number of code units.
+The third argument should point to an \fBuint32_t\fP variable. The value is a
+lower bound to the length of any matching string. There may not be any strings
+of that length that do actually match, but every string that does match is at
+least that long.
+.sp
+ PCRE2_INFO_NAMECOUNT
+ PCRE2_INFO_NAMEENTRYSIZE
+ PCRE2_INFO_NAMETABLE
+.sp
+PCRE2 supports the use of named as well as numbered capturing parentheses. The
+names are just an additional way of identifying the parentheses, which still
+acquire numbers. Several convenience functions such as
+\fBpcre2_substring_get_byname()\fP are provided for extracting captured
+substrings by name. It is also possible to extract the data directly, by first
+converting the name to a number in order to access the correct pointers in the
+output vector (described with \fBpcre2_match()\fP below). To do the conversion,
+you need to use the name-to-number map, which is described by these three
+values.
+.P
+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 \fBuint32_t\fP value. The entry
+size depends on the length of the longest name.
+.P
+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
+significant byte first. In the 16-bit library, the pointer points to 16-bit
+code units, the first of which contains the parenthesis number. In the 32-bit
+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.
+.P
+The names are in alphabetical order. If (?| is used to create multiple groups
+with the same number, as described in the
+.\" HTML <a href="pcre2pattern.html#dupsubpatternnumber">
+.\" </a>
+section on duplicate subpattern numbers
+.\"
+in the
+.\" HREF
+\fBpcre2pattern\fP
+.\"
+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.
+.P
+Duplicate names for subpatterns 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 subpatterns may have lower numbers.
+.P
+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):
+.sp
+.\" JOIN
+ (?<date> (?<year>(\ed\ed)?\ed\ed) -
+ (?<month>\ed\ed) - (?<day>\ed\ed) )
+.sp
+There are four named subpatterns, so the table has four entries, and each entry
+in the table is eight bytes long. The table is as follows, with non-printing
+bytes shows in hexadecimal, and undefined bytes shown as ??:
+.sp
+ 00 01 d a t e 00 ??
+ 00 05 d a y 00 ?? ??
+ 00 04 m o n t h 00
+ 00 02 y e a r 00 ??
+.sp
+When writing code to extract data from named subpatterns using the
+name-to-number map, remember that the length of the entries is likely to be
+different for each compiled pattern.
+.sp
+ PCRE2_INFO_NEWLINE
+.sp
+The output is one of the following \fBuint32_t\fP values:
+.sp
+ PCRE2_NEWLINE_CR Carriage return (CR)
+ PCRE2_NEWLINE_LF Linefeed (LF)
+ PCRE2_NEWLINE_CRLF Carriage return, linefeed (CRLF)
+ PCRE2_NEWLINE_ANY Any Unicode line ending
+ PCRE2_NEWLINE_ANYCRLF Any of CR, LF, or CRLF
+ PCRE2_NEWLINE_NUL The NUL character (binary zero)
+.sp
+This identifies the character sequence that will be recognized as meaning
+"newline" while matching.
+.sp
+ PCRE2_INFO_SIZE
+.sp
+Return the size of the compiled pattern in bytes (for all three libraries). The
+third argument should point to a \fBsize_t\fP variable. This value includes the
+size of the general data block that precedes the code units of the compiled
+pattern itself. The value that is used when \fBpcre2_compile()\fP is getting
+memory in which to place the compiled pattern may be slightly larger than the
+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.
+.
+.
+.\" HTML <a name="infoaboutcallouts"></a>
+.SH "INFORMATION ABOUT A PATTERN'S CALLOUTS"
+.rs
+.sp
+.nf
+.B int pcre2_callout_enumerate(const pcre2_code *\fIcode\fP,
+.B " int (*\fIcallback\fP)(pcre2_callout_enumerate_block *, void *),"
+.B " void *\fIuser_data\fP);"
+.fi
+.sp
+A script language that supports the use of string arguments in callouts might
+like to scan all the callouts in a pattern before running the match. This can
+be done by calling \fBpcre2_callout_enumerate()\fP. The first argument is a
+pointer to a compiled pattern, the second points to a callback function, and
+the third is arbitrary user data. The callback function is called for every
+callout in the pattern in the order in which they appear. Its first argument is
+a pointer to a callout enumeration block, and its second argument is the
+\fIuser_data\fP value that was passed to \fBpcre2_callout_enumerate()\fP. The
+contents of the callout enumeration block are described in the
+.\" HREF
+\fBpcre2callout\fP
+.\"
+documentation, which also gives further details about callouts.
+.
+.
+.SH "SERIALIZATION AND PRECOMPILING"
+.rs
+.sp
+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
+width, and must also have the same endianness, pointer width, and PCRE2_SIZE
+type. Before compiled patterns can be saved, they must be converted to a
+"serialized" form, which in the case of PCRE2 is really just a bytecode dump.
+The functions whose names begin with \fBpcre2_serialize_\fP are used for
+converting to and from the serialized form. They are described in the
+.\" HREF
+\fBpcre2serialize\fP
+.\"
+documentation. Note that PCRE2 serialization does not convert compiled patterns
+to an abstract format like Java or .NET serialization.
+.
+.
+.\" HTML <a name="matchdatablock"></a>
+.SH "THE MATCH DATA BLOCK"
+.rs
+.sp
+.nf
+.B pcre2_match_data *pcre2_match_data_create(uint32_t \fIovecsize\fP,
+.B " pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B pcre2_match_data *pcre2_match_data_create_from_pattern(
+.B " const pcre2_code *\fIcode\fP, pcre2_general_context *\fIgcontext\fP);"
+.sp
+.B void pcre2_match_data_free(pcre2_match_data *\fImatch_data\fP);
+.fi
+.P
+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 part of the subject and any substrings that were
+captured. This is known as the \fIovector\fP.
+.P
+Before calling \fBpcre2_match()\fP, \fBpcre2_dfa_match()\fP, or
+\fBpcre2_jit_match()\fP you must create a match data block by calling one of
+the creation functions above. For \fBpcre2_match_data_create()\fP, the first
+argument is the number of pairs of offsets in the \fIovector\fP. 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. A minimum of at least 1 pair is imposed by
+\fBpcre2_match_data_create()\fP, so it is always possible to return the overall
+matched string.
+.P
+The second argument of \fBpcre2_match_data_create()\fP is a pointer to a
+general context, which can specify custom memory management for obtaining the
+memory for the match data block. If you are not using custom memory management,
+pass NULL, which causes \fBmalloc()\fP to be used.
+.P
+For \fBpcre2_match_data_create_from_pattern()\fP, 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. 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).
+.P
+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
+.\" HTML <a href="#matchedstrings">
+.\" </a>
+matched strings
+.\"
+and
+.\" HTML <a href="#matchotherdata">
+.\" </a>
+other match data
+.\"
+below.
+.P
+When a call of \fBpcre2_match()\fP 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.
+.P
+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 running a match, you must not
+free a compiled pattern or a subject string until after all operations on the
+match data block (for that match) have taken place.
+.P
+When a match data block itself is no longer needed, it should be freed by
+calling \fBpcre2_match_data_free()\fP. If this function is called with a NULL
+argument, it returns immediately, without doing anything.
+.
+.
+.SH "MATCHING A PATTERN: THE TRADITIONAL FUNCTION"
+.rs
+.sp
+.nf
+.B int pcre2_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP,
+.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP,"
+.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP,"
+.B " pcre2_match_context *\fImcontext\fP);"
+.fi
+.P
+The function \fBpcre2_match()\fP is called to match a subject string against a
+compiled pattern, which is passed in the \fIcode\fP argument. You can call
+\fBpcre2_match()\fP with the same \fIcode\fP 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.
+.P
+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
+.\" HTML <a href="#dfamatch">
+.\" </a>
+below
+.\"
+in the section about the \fBpcre2_dfa_match()\fP function.
+.P
+Here is an example of a simple call to \fBpcre2_match()\fP:
+.sp
+ pcre2_match_data *md = pcre2_match_data_create(4, NULL);
+ int rc = pcre2_match(
+ re, /* result of pcre2_compile() */
+ "some string", /* the subject string */
+ 11, /* the length of the subject string */
+ 0, /* start at offset 0 in the subject */
+ 0, /* default options */
+ md, /* the match data block */
+ NULL); /* a match context; NULL means use defaults */
+.sp
+If the subject string is zero-terminated, the length can be given as
+PCRE2_ZERO_TERMINATED. A match context must be provided if certain less common
+matching parameters are to be changed. For details, see the section on
+.\" HTML <a href="#matchcontext">
+.\" </a>
+the match context
+.\"
+above.
+.
+.
+.SS "The string to be matched by \fBpcre2_match()\fP"
+.rs
+.sp
+The subject string is passed to \fBpcre2_match()\fP as a pointer in
+\fIsubject\fP, a length in \fIlength\fP, and a starting offset in
+\fIstartoffset\fP. The length and offset are in code units, not characters.
+That is, they are in bytes for the 8-bit library, 16-bit code units for the
+16-bit library, and 32-bit code units for the 32-bit library, whether or not
+UTF processing is enabled.
+.P
+If \fIstartoffset\fP is greater than the length of the subject,
+\fBpcre2_match()\fP returns PCRE2_ERROR_BADOFFSET. When the starting offset is
+zero, the search for a match starts at the beginning of the subject, and this
+is by far the most common case. In UTF-8 or UTF-16 mode, the starting offset
+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.
+.P
+A non-zero starting offset is useful when searching for another match in the
+same subject by calling \fBpcre2_match()\fP again after a previous success.
+Setting \fIstartoffset\fP differs from passing over a shortened string and
+setting PCRE2_NOTBOL in the case of a pattern that begins with any kind of
+lookbehind. For example, consider the pattern
+.sp
+ \eBiss\eB
+.sp
+which finds occurrences of "iss" in the middle of words. (\eB matches only if
+the current position in the subject is not a word boundary.) When applied to
+the string "Mississipi" the first call to \fBpcre2_match()\fP finds the first
+occurrence. If \fBpcre2_match()\fP is called again with just the remainder of
+the subject, namely "issipi", it does not match, because \eB is always false at
+the start of the subject, which is deemed to be a word boundary. However, if
+\fBpcre2_match()\fP is passed the entire string again, but with
+\fIstartoffset\fP 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.
+.P
+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
+PCRE2_ANCHORED options, and then if that fails, advancing the starting offset
+and trying an ordinary match again. There is some code that demonstrates how to
+do this in the
+.\" HREF
+\fBpcre2demo\fP
+.\"
+sample program. In the most general case, you have to check to see if the
+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.
+.P
+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 \eA.
+.
+.
+.\" HTML <a name="matchoptions"></a>
+.SS "Option bits for \fBpcre2_match()\fP"
+.rs
+.sp
+The unused bits of the \fIoptions\fP argument for \fBpcre2_match()\fP must be
+zero. The only bits that may be set are PCRE2_ANCHORED, 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.
+.P
+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 \fBpcre2_match()\fP is run. Apart from PCRE2_NO_JIT
+(obviously), the remaining options are supported for JIT matching.
+.sp
+ PCRE2_ANCHORED
+.sp
+The PCRE2_ANCHORED option limits \fBpcre2_match()\fP to matching at the first
+matching position. If a pattern was compiled with PCRE2_ANCHORED, or turned out
+to be anchored by virtue of its contents, it cannot be made unachored at
+matching time. Note that setting the option at match time disables JIT
+matching.
+.sp
+ PCRE2_ENDANCHORED
+.sp
+If the PCRE2_ENDANCHORED option is set, any string that \fBpcre2_match()\fP
+matches must be right at the end of the subject string. Note that setting the
+option at match time disables JIT matching.
+.sp
+ PCRE2_NOTBOL
+.sp
+This option specifies that first character of the subject string is not the
+beginning of a line, so the circumflex metacharacter should not match before
+it. Setting this without having set PCRE2_MULTILINE at compile time causes
+circumflex never to match. This option affects only the behaviour of the
+circumflex metacharacter. It does not affect \eA.
+.sp
+ PCRE2_NOTEOL
+.sp
+This option specifies that the end of the subject string is not the end of a
+line, so the dollar metacharacter should not match it nor (except in multiline
+mode) a newline immediately before it. Setting this without having set
+PCRE2_MULTILINE at compile time causes dollar never to match. This option
+affects only the behaviour of the dollar metacharacter. It does not affect \eZ
+or \ez.
+.sp
+ PCRE2_NOTEMPTY
+.sp
+An empty string is not considered to be a valid match if this option is set. If
+there are alternatives in the pattern, they are tried. If all the alternatives
+match the empty string, the entire match fails. For example, if the pattern
+.sp
+ a?b?
+.sp
+is applied to a string not beginning with "a" or "b", it matches an empty
+string at the start of the subject. With PCRE2_NOTEMPTY set, this match is not
+valid, so \fBpcre2_match()\fP searches further into the string for occurrences
+of "a" or "b".
+.sp
+ PCRE2_NOTEMPTY_ATSTART
+.sp
+This is like PCRE2_NOTEMPTY, except that it locks out an empty string match
+only at the first matching position, that is, at the start of the subject plus
+the starting offset. An empty string match later in the subject is permitted.
+If the pattern is anchored, such a match can occur only if the pattern contains
+\eK.
+.sp
+ PCRE2_NO_JIT
+.sp
+By default, if a pattern has been successfully processed by
+\fBpcre2_jit_compile()\fP, JIT is automatically used when \fBpcre2_match()\fP
+is called with options that JIT supports. Setting PCRE2_NO_JIT disables the use
+of JIT; it forces matching to be done by the interpreter.
+.sp
+ PCRE2_NO_UTF_CHECK
+.sp
+When PCRE2_UTF is set at compile time, the validity of the subject as a UTF
+string is checked by default when \fBpcre2_match()\fP is subsequently called.
+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 code unit of a character or to the
+end of the subject. If there are no lookbehind assertions in the pattern, the
+check starts at the starting offset. Otherwise, it starts at the length of the
+longest lookbehind before the starting offset, or at the start of the subject
+if there are not that many characters before the starting offset. Note that the
+sequences \eb and \eB are one-character lookbehinds.
+.P
+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
+code unit sequence. There are discussions about the validity of
+.\" HTML <a href="pcre2unicode.html#utf8strings">
+.\" </a>
+UTF-8 strings,
+.\"
+.\" HTML <a href="pcre2unicode.html#utf16strings">
+.\" </a>
+UTF-16 strings,
+.\"
+and
+.\" HTML <a href="pcre2unicode.html#utf32strings">
+.\" </a>
+UTF-32 strings
+.\"
+in the
+.\" HREF
+\fBpcre2unicode\fP
+.\"
+page.
+.P
+If you know that your subject is valid, and you want to skip these checks for
+performance reasons, you can set the PCRE2_NO_UTF_CHECK option when calling
+\fBpcre2_match()\fP. You might want to do this for the second and subsequent
+calls to \fBpcre2_match()\fP if you are making repeated calls to find other
+matches in the same subject string.
+.P
+\fBWarning:\fP When PCRE2_NO_UTF_CHECK is set, the effect of passing an invalid
+string as a subject, or an invalid value of \fIstartoffset\fP, is undefined.
+Your program may crash or loop indefinitely.
+.sp
+ PCRE2_PARTIAL_HARD
+ PCRE2_PARTIAL_SOFT
+.sp
+These options turn on the partial matching feature. A partial match occurs if
+the end of the subject string is reached successfully, but there are not enough
+subject characters to complete the match. If this happens 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.
+.P
+If PCRE2_PARTIAL_HARD is set, it overrides PCRE2_PARTIAL_SOFT. In this case, if
+a partial match is found, \fBpcre2_match()\fP 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.
+.P
+There is a more detailed discussion of partial and multi-segment matching, with
+examples, in the
+.\" HREF
+\fBpcre2partial\fP
+.\"
+documentation.
+.
+.
+.
+.SH "NEWLINE HANDLING WHEN MATCHING"
+.rs
+.sp
+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
+.\" HTML <a href="#compilecontext">
+.\" </a>
+compile context
+.\"
+by calling \fBpcre2_set_newline()\fP. It can also be overridden by starting a
+pattern string with, for example, (*CRLF), as described in the
+.\" HTML <a href="pcre2pattern.html#newlines">
+.\" </a>
+section on newline conventions
+.\"
+in the
+.\" HREF
+\fBpcre2pattern\fP
+.\"
+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.
+.P
+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.
+.P
+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 "\er\enA" because, after failing at the
+start, it skips both the CR and the LF before retrying. However, the pattern
+[\er\en]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.
+.P
+An explicit match for CR of LF is either a literal appearance of one of those
+characters in the pattern, or one of the \er or \en or equivalent octal or
+hexadecimal escape sequences. Implicit matches such as [^X] do not count, nor
+does \es, even though it includes CR and LF in the characters that it matches.
+.P
+Notwithstanding the above, anomalous effects may still occur when CRLF is a
+valid newline sequence and explicit \er or \en escapes appear in the pattern.
+.
+.
+.\" HTML <a name="matchedstrings"></a>
+.SH "HOW PCRE2_MATCH() RETURNS A STRING AND CAPTURED SUBSTRINGS"
+.rs
+.sp
+.nf
+.B uint32_t pcre2_get_ovector_count(pcre2_match_data *\fImatch_data\fP);
+.sp
+.B PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *\fImatch_data\fP);
+.fi
+.P
+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
+book, this is called "capturing" in what follows, and the phrase "capturing
+subpattern" or "capturing group" is used for a fragment of a pattern that picks
+out a substring. PCRE2 supports several other kinds of parenthesized subpattern
+that do not cause substrings to be captured. The \fBpcre2_pattern_info()\fP
+function can be used to find out how many capturing subpatterns there are in a
+compiled pattern.
+.P
+You can use auxiliary functions for accessing captured substrings
+.\" HTML <a href="#extractbynumber">
+.\" </a>
+by number
+.\"
+or
+.\" HTML <a href="#extractbyname">
+.\" </a>
+by name,
+.\"
+as described in sections below.
+.P
+Alternatively, you can make direct use of the vector of PCRE2_SIZE values,
+called the \fBovector\fP, which contains the offsets of captured strings. It is
+part of the
+.\" HTML <a href="#matchdatablock">
+.\" </a>
+match data block.
+.\"
+The function \fBpcre2_get_ovector_pointer()\fP returns the address of the
+ovector, and \fBpcre2_get_ovector_count()\fP returns the number of pairs of
+values it contains.
+.P
+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.
+.P
+After a partial match (error return PCRE2_ERROR_PARTIAL), only the first pair
+of offsets (that is, \fIovector[0]\fP and \fIovector[1]\fP) are set. They
+identify the part of the subject that was partially matched. See the
+.\" HREF
+\fBpcre2partial\fP
+.\"
+documentation for details of partial matching.
+.P
+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
+\fBpcre2_match()\fP is one more than the highest numbered pair that has been
+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.
+.P
+If a pattern uses the \eK 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\eK) is matched against "ab", the start and
+end offset values for the match are 2 and 0.
+.P
+If a capturing subpattern group is matched repeatedly within a single match
+operation, it is the last portion of the subject that it matched that is
+returned.
+.P
+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, \fBpcre2_match()\fP may be called with a match
+data block whose ovector is of minimum length (that is, one pair).
+.P
+It is possible for capturing subpattern number \fIn+1\fP to match some part of
+the subject when subpattern \fIn\fP 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 subpatterns 1 and 3 are matched, but 2 is not. When this
+happens, both values in the offset pairs corresponding to unused subpatterns
+are set to PCRE2_UNSET.
+.P
+Offset values that correspond to unused subpatterns 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)?)? subpatterns 2 and 3 are not matched.
+The return from the function is 2, because the highest used capturing
+subpattern number is 1. The offsets for for the second and third capturing
+subpatterns (assuming the vector is large enough, of course) are set to
+PCRE2_UNSET.
+.P
+Elements in the ovector that do not correspond to capturing parentheses in the
+pattern are never changed. That is, if a pattern contains \fIn\fP capturing
+parentheses, no more than \fIovector[0]\fP to \fIovector[2n+1]\fP are set by
+\fBpcre2_match()\fP. The other elements retain whatever values they previously
+had. After a failed match attempt, the contents of the ovector are unchanged.
+.
+.
+.\" HTML <a name="matchotherdata"></a>
+.SH "OTHER INFORMATION ABOUT A MATCH"
+.rs
+.sp
+.nf
+.B PCRE2_SPTR pcre2_get_mark(pcre2_match_data *\fImatch_data\fP);
+.sp
+.B PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *\fImatch_data\fP);
+.fi
+.P
+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.
+.P
+After a successful match, a partial match (PCRE2_ERROR_PARTIAL), or a failure
+to match (PCRE2_ERROR_NOMATCH), a (*MARK), (*PRUNE), or (*THEN) name may be
+available. The function \fBpcre2_get_mark()\fP can be called to access this
+name. The same function applies to all three verbs. It returns a pointer to the
+zero-terminated name, which is within the compiled pattern. If no name is
+available, NULL is returned. The length of the name (excluding the terminating
+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.
+.P
+After a successful match, the name that is returned is the last (*MARK),
+(*PRUNE), or (*THEN) name encountered on the matching path through the pattern.
+Instances of (*PRUNE) and (*THEN) without names are ignored. Thus, for example,
+if the matching path contains (*MARK:A)(*PRUNE), the name "A" is returned.
+After a "no match" or a partial match, the last encountered name is returned.
+For example, consider this pattern:
+.sp
+ ^(*MARK:A)((*MARK:B)a|b)c
+.sp
+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.
+.P
+\fBWarning:\fP 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
+of "c" in the subject before running the matching engine. This check fails for
+"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
+\fBpcre2_compile()\fP or starting the pattern with (*NO_START_OPT).
+.P
+After a successful match, a partial match, or one of the invalid UTF errors
+(for example, PCRE2_ERROR_UTF8_ERR5), \fBpcre2_get_startchar()\fP can be
+called. After a successful or partial match it returns the code unit offset of
+the character at which the match started. For a non-partial match, this can be
+different to the value of \fIovector[0]\fP if the pattern contains the \eK
+escape sequence. After a partial match, however, this value is always the same
+as \fIovector[0]\fP because \eK does not affect the result of a partial match.
+.P
+After a UTF check failure, \fBpcre2_get_startchar()\fP can be used to obtain
+the code unit offset of the invalid UTF character. Details are given in the
+.\" HREF
+\fBpcre2unicode\fP
+.\"
+page.
+.
+.
+.\" HTML <a name="errorlist"></a>
+.SH "ERROR RETURNS FROM \fBpcre2_match()\fP"
+.rs
+.sp
+If \fBpcre2_match()\fP fails, it returns a negative number. This can be
+converted to a text string by calling the \fBpcre2_get_error_message()\fP
+function (see "Obtaining a textual error message"
+.\" HTML <a href="#geterrormessage">
+.\" </a>
+below).
+.\"
+Negative error codes are also returned by other functions, and are documented
+with them. The codes are given names in the header file. If UTF checking is in
+force and an invalid UTF subject string is detected, one of a number of
+UTF-specific negative error codes is returned. Details are given in the
+.\" HREF
+\fBpcre2unicode\fP
+.\"
+page. The following are the other errors that may be returned by
+\fBpcre2_match()\fP:
+.sp
+ PCRE2_ERROR_NOMATCH
+.sp
+The subject string did not match the pattern.
+.sp
+ PCRE2_ERROR_PARTIAL
+.sp
+The subject string did not match, but it did match partially. See the
+.\" HREF
+\fBpcre2partial\fP
+.\"
+documentation for details of partial matching.
+.sp
+ PCRE2_ERROR_BADMAGIC
+.sp
+PCRE2 stores a 4-byte "magic number" at the start of the compiled code, to
+catch the case when it is passed a junk pointer. This is the error that is
+returned when the magic number is not present.
+.sp
+ PCRE2_ERROR_BADMODE
+.sp
+This error is given when a compiled pattern is passed to a function in a
+library of a different code unit width, for example, a pattern compiled by
+the 8-bit library is passed to a 16-bit or 32-bit library function.
+.sp
+ PCRE2_ERROR_BADOFFSET
+.sp
+The value of \fIstartoffset\fP was greater than the length of the subject.
+.sp
+ PCRE2_ERROR_BADOPTION
+.sp
+An unrecognized bit was set in the \fIoptions\fP argument.
+.sp
+ PCRE2_ERROR_BADUTFOFFSET
+.sp
+The UTF code unit sequence that was passed as a subject was checked and found
+to be valid (the PCRE2_NO_UTF_CHECK option was not set), but the value of
+\fIstartoffset\fP did not point to the beginning of a UTF character or the end
+of the subject.
+.sp
+ PCRE2_ERROR_CALLOUT
+.sp
+This error is never generated by \fBpcre2_match()\fP itself. It is provided for
+use by callout functions that want to cause \fBpcre2_match()\fP or
+\fBpcre2_callout_enumerate()\fP to return a distinctive error code. See the
+.\" HREF
+\fBpcre2callout\fP
+.\"
+documentation for details.
+.sp
+ PCRE2_ERROR_DEPTHLIMIT
+.sp
+The nested backtracking depth limit was reached.
+.sp
+ PCRE2_ERROR_HEAPLIMIT
+.sp
+The heap limit was reached.
+.sp
+ PCRE2_ERROR_INTERNAL
+.sp
+An unexpected internal error has occurred. This error could be caused by a bug
+in PCRE2 or by overwriting of the compiled pattern.
+.sp
+ PCRE2_ERROR_JIT_STACKLIMIT
+.sp
+This error is returned when a pattern that was successfully studied using JIT
+is being matched, but the memory available for the just-in-time processing
+stack is not large enough. See the
+.\" HREF
+\fBpcre2jit\fP
+.\"
+documentation for more details.
+.sp
+ PCRE2_ERROR_MATCHLIMIT
+.sp
+The backtracking match limit was reached.
+.sp
+ PCRE2_ERROR_NOMEMORY
+.sp
+If a pattern contains many nested backtracking points, heap memory is used to
+remember them. This error is given when the memory allocation function (default
+or custom) fails. Note that a different error, PCRE2_ERROR_HEAPLIMIT, is given
+if the amount of memory needed exceeds the heap limit.
+.sp
+ PCRE2_ERROR_NULL
+.sp
+Either the \fIcode\fP, \fIsubject\fP, or \fImatch_data\fP argument was passed
+as NULL.
+.sp
+ PCRE2_ERROR_RECURSELOOP
+.sp
+This error is returned when \fBpcre2_match()\fP detects a recursion loop within
+the pattern. Specifically, it means that either the whole pattern or a
+subpattern has been called recursively for the second time at the same position
+in the subject string. Some simple patterns that might do this are detected and
+faulted at compile time, but more complicated cases, in particular mutual
+recursions between two different subpatterns, cannot be detected until matching
+is attempted.
+.
+.
+.\" HTML <a name="geterrormessage"></a>
+.SH "OBTAINING A TEXTUAL ERROR MESSAGE"
+.rs
+.sp
+.nf
+.B int pcre2_get_error_message(int \fIerrorcode\fP, PCRE2_UCHAR *\fIbuffer\fP,
+.B " PCRE2_SIZE \fIbufflen\fP);"
+.fi
+.P
+A text message for an error code from any PCRE2 function (compile, match, or
+auxiliary) can be obtained by calling \fBpcre2_get_error_message()\fP. 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.
+.P
+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.
+.
+.
+.\" HTML <a name="extractbynumber"></a>
+.SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER"
+.rs
+.sp
+.nf
+.B int pcre2_substring_length_bynumber(pcre2_match_data *\fImatch_data\fP,
+.B " uint32_t \fInumber\fP, PCRE2_SIZE *\fIlength\fP);"
+.sp
+.B int pcre2_substring_copy_bynumber(pcre2_match_data *\fImatch_data\fP,
+.B " uint32_t \fInumber\fP, PCRE2_UCHAR *\fIbuffer\fP,"
+.B " PCRE2_SIZE *\fIbufflen\fP);"
+.sp
+.B int pcre2_substring_get_bynumber(pcre2_match_data *\fImatch_data\fP,
+.B " uint32_t \fInumber\fP, PCRE2_UCHAR **\fIbufferptr\fP,"
+.B " PCRE2_SIZE *\fIbufflen\fP);"
+.sp
+.B void pcre2_substring_free(PCRE2_UCHAR *\fIbuffer\fP);
+.fi
+.P
+Captured substrings can be accessed directly by using the ovector as described
+.\" HTML <a href="#matchedstrings">
+.\" </a>
+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.
+.P
+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.
+.P
+If a pattern uses the \eK 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\eK) 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.
+.P
+You can find the length in code units of a captured substring without
+extracting it by calling \fBpcre2_substring_length_bynumber()\fP. 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.
+.P
+The \fBpcre2_substring_copy_bynumber()\fP function copies a captured substring
+into a supplied buffer, whereas \fBpcre2_substring_get_bynumber()\fP 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 capturing group number.
+.P
+The final arguments of \fBpcre2_substring_copy_bynumber()\fP 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.
+.P
+For \fBpcre2_substring_get_bynumber()\fP 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 \fBpcre2_substring_free()\fP.
+.P
+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,
+PCRE2_ERROR_PARTIAL is returned. Other possible error codes are:
+.sp
+ PCRE2_ERROR_NOMEMORY
+.sp
+The buffer was too small for \fBpcre2_substring_copy_bynumber()\fP, or the
+attempt to get memory failed for \fBpcre2_substring_get_bynumber()\fP.
+.sp
+ PCRE2_ERROR_NOSUBSTRING
+.sp
+There is no substring with that number in the pattern, that is, the number is
+greater than the number of capturing parentheses.
+.sp
+ PCRE2_ERROR_UNAVAILABLE
+.sp
+The substring number, though not greater than the number of captures in the
+pattern, is greater than the number of slots in the ovector, so the substring
+could not be captured.
+.sp
+ PCRE2_ERROR_UNSET
+.sp
+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.
+.
+.
+.SH "EXTRACTING A LIST OF ALL CAPTURED SUBSTRINGS"
+.rs
+.sp
+.nf
+.B int pcre2_substring_list_get(pcre2_match_data *\fImatch_data\fP,
+.B " PCRE2_UCHAR ***\fIlistptr\fP, PCRE2_SIZE **\fIlengthsptr\fP);
+.sp
+.B void pcre2_substring_list_free(PCRE2_SPTR *\fIlist\fP);
+.fi
+.P
+The \fBpcre2_substring_list_get()\fP 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.
+.P
+This function must be called only after a successful match. If called after a
+partial match, the error code PCRE2_ERROR_PARTIAL is returned.
+.P
+The address of the memory block is returned via \fIlistptr\fP, 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
+\fIlengthsptr\fP. If your strings do not contain binary zeros and you do not
+therefore need the lengths, you may supply NULL as the \fBlengthsptr\fP
+argument to disable the creation of a list of lengths. The yield of the
+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 \fBpcre2_substring_list_free()\fP.
+.P
+If this function encounters a substring that is unset, which can happen when
+capturing subpattern number \fIn+1\fP matches some part of the subject, but
+subpattern \fIn\fP 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 \fBpcre2_substring_length_bynumber()\fP.
+.
+.
+.\" HTML <a name="extractbyname"></a>
+.SH "EXTRACTING CAPTURED SUBSTRINGS BY NAME"
+.rs
+.sp
+.nf
+.B int pcre2_substring_number_from_name(const pcre2_code *\fIcode\fP,
+.B " PCRE2_SPTR \fIname\fP);"
+.sp
+.B int pcre2_substring_length_byname(pcre2_match_data *\fImatch_data\fP,
+.B " PCRE2_SPTR \fIname\fP, PCRE2_SIZE *\fIlength\fP);"
+.sp
+.B int pcre2_substring_copy_byname(pcre2_match_data *\fImatch_data\fP,
+.B " PCRE2_SPTR \fIname\fP, PCRE2_UCHAR *\fIbuffer\fP, PCRE2_SIZE *\fIbufflen\fP);"
+.sp
+.B int pcre2_substring_get_byname(pcre2_match_data *\fImatch_data\fP,
+.B " PCRE2_SPTR \fIname\fP, PCRE2_UCHAR **\fIbufferptr\fP, PCRE2_SIZE *\fIbufflen\fP);"
+.sp
+.B void pcre2_substring_free(PCRE2_UCHAR *\fIbuffer\fP);
+.fi
+.P
+To extract a substring by name, you first have to find associated number.
+For example, for this pattern:
+.sp
+ (a+)b(?<xxx>\ed+)...
+.sp
+the number of the subpattern called "xxx" is 2. If the name is known to be
+unique (PCRE2_DUPNAMES was not set), you can find the number from the name by
+calling \fBpcre2_substring_number_from_name()\fP. The first argument is the
+compiled pattern, and the second is the name. The yield of the function is the
+subpattern number, PCRE2_ERROR_NOSUBSTRING if there is no subpattern of that
+name, or PCRE2_ERROR_NOUNIQUESUBSTRING if there is more than one subpattern of
+that name. Given the number, you can extract the substring directly from the
+ovector, or use one of the "bynumber" functions described above.
+.P
+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
+first named string that is set.
+.P
+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.
+.P
+\fBWarning:\fP If the pattern uses the (?| feature to set up multiple
+subpatterns with the same number, as described in the
+.\" HTML <a href="pcre2pattern.html#dupsubpatternnumber">
+.\" </a>
+section on duplicate subpattern numbers
+.\"
+in the
+.\" HREF
+\fBpcre2pattern\fP
+.\"
+page, you cannot use names to distinguish the different subpatterns, because
+names are not included in the compiled code. The matching process uses only
+numbers. For this reason, the use of different names for subpatterns of the
+same number causes an error at compile time.
+.
+.
+.SH "CREATING A NEW STRING WITH SUBSTITUTIONS"
+.rs
+.sp
+.nf
+.B int pcre2_substitute(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP,
+.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP,"
+.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP,"
+.B " pcre2_match_context *\fImcontext\fP, PCRE2_SPTR \fIreplacement\fP,"
+.B " PCRE2_SIZE \fIrlength\fP, PCRE2_UCHAR *\fIoutputbuffer\zfP,"
+.B " PCRE2_SIZE *\fIoutlengthptr\fP);"
+.fi
+.P
+This function calls \fBpcre2_match()\fP and then makes a copy of the subject
+string in \fIoutputbuffer\fP, replacing the part that was matched with the
+\fIreplacement\fP string, whose length is supplied in \fBrlength\fP. This can
+be given as PCRE2_ZERO_TERMINATED for a zero-terminated string. Matches in
+which a \eK 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 \eK in a lookbehind causes the match to start
+earlier than the point that was reached in the previous iteration are also not
+supported.
+.P
+The first seven arguments of \fBpcre2_substitute()\fP are the same as for
+\fBpcre2_match()\fP, except that the partial matching options are not
+permitted, and \fImatch_data\fP 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.
+.P
+If an external \fImatch_data\fP block is provided, its contents afterwards
+are those set by the final call to \fBpcre2_match()\fP, which will have
+ended in a matching error. The contents of the ovector within the match data
+block may or may not have been changed.
+.P
+The \fIoutlengthptr\fP argument 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 of the new string, excluding the
+trailing zero that is automatically added.
+.P
+If the function is not successful, the value set via \fIoutlengthptr\fP 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
+(see below), in which case the value is the minimum length needed, including
+space for the trailing zero. Note that in order to compute the required length,
+\fBpcre2_substitute()\fP has to simulate all the matching and copying, instead
+of giving an error return as soon as the buffer overflows. Note also that the
+length is in code units, not bytes.
+.P
+In the replacement string, which is interpreted as a UTF string in UTF mode,
+and is checked for UTF validity unless the PCRE2_NO_UTF_CHECK option is set, a
+dollar character is an escape character that can specify the insertion of
+characters from capturing groups or (*MARK), (*PRUNE), or (*THEN) items in the
+pattern. The following forms are always recognized:
+.sp
+ $$ insert a dollar character
+ $<n> or ${<n>} insert the contents of group <n>
+ $*MARK or ${*MARK} insert a (*MARK), (*PRUNE), or (*THEN) name
+.sp
+Either a group number or a group name can be given for <n>. Curly brackets are
+required only if the following character would be 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+=".
+.P
+$*MARK inserts the name from the last encountered (*MARK), (*PRUNE), or (*THEN)
+on the matching path that has a name. (*MARK) must always include a name, but
+(*PRUNE) and (*THEN) need not. For example, in the case of (*MARK:A)(*PRUNE)
+the name inserted is "A", but for (*MARK:A)(*PRUNE:B) the relevant name is "B".
+This facility can be used to perform simple simultaneous substitutions, as this
+\fBpcre2test\fP example shows:
+.sp
+ /(*MARK:pear)apple|(*MARK:orange)lemon/g,replace=${*MARK}
+ apple lemon
+ 2: pear orange
+.sp
+As well as the usual options for \fBpcre2_match()\fP, a number of additional
+options can be set in the \fIoptions\fP argument of \fBpcre2_substitute()\fP.
+.P
+PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject string,
+replacing every matching substring. If this option is not set, only the first
+matching substring is replaced. The search for matches takes place in the
+original subject string (that is, previous replacements do not affect it).
+Iteration is implemented by advancing the \fIstartoffset\fP 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.
+.P
+You can restrict the effect of a global substitution to a portion of the
+subject string by setting either or both of \fIstartoffset\fP and an offset
+limit. Here is a \fPpcre2test\fP example:
+.sp
+ /B/g,replace=!,use_offset_limit
+ ABC ABC ABC ABC\e=offset=3,offset_limit=12
+ 2: ABC A!C A!C ABC
+.sp
+When continuing with global substitutions after matching a substring with zero
+length, an attempt to find a non-empty match at the same offset is performed.
+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.
+.P
+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, \fBpcre2_substitute()\fP continues to go through
+the motions of matching and substituting (without, of course, writing anything)
+in order to compute the size of buffer that is needed. This value is passed
+back via the \fIoutlengthptr\fP variable, with the result of the function still
+being PCRE2_ERROR_NOMEMORY.
+.P
+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.
+.P
+PCRE2_SUBSTITUTE_UNKNOWN_UNSET causes references to capturing 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.
+.P
+PCRE2_SUBSTITUTE_UNSET_EMPTY causes unset capturing 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.
+.P
+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, two things change:
+.P
+Firstly, backslash in a replacement string is interpreted as an escape
+character. The usual forms such as \en or \ex{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 \eQ...\eE,
+exactly as in pattern strings.
+.P
+There are also four escape sequences for forcing the case of inserted letters.
+The insertion mechanism has three states: no case forcing, force upper case,
+and force lower case. The escape sequences change the current state: \eU and
+\eL change to upper or lower case forcing, respectively, and \eE (when not
+terminating a \eQ quoted sequence) reverts to no case forcing. The sequences
+\eu and \el 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. Case forcing applies to all inserted characters, including those from
+captured groups and letters within \eQ...\eE quoted sequences.
+.P
+Note that case forcing sequences such as \eU...\eE do not nest. For example,
+the result of processing "\eUaa\eLBB\eEcc\eE" is "AAbbcc"; the final \eE has no
+effect.
+.P
+The second effect of setting PCRE2_SUBSTITUTE_EXTENDED is to add more
+flexibility to group substitution. The syntax is similar to that used by Bash:
+.sp
+ ${<n>:-<string>}
+ ${<n>:+<string1>:<string2>}
+.sp
+As before, <n> may be a group number or a name. The first form specifies a
+default value. If group <n> is set, its value is inserted; if not, <string> is
+expanded and the result inserted. The second form specifies strings that are
+expanded and inserted when group <n> is set or unset, respectively. The first
+form is just a convenient shorthand for
+.sp
+ ${<n>:+${<n>}:<string>}
+.sp
+Backslash can be used to escape colons and closing curly brackets in the
+replacement strings. A change of the case forcing state within a replacement
+string remains in force afterwards, as shown in this \fBpcre2test\fP example:
+.sp
+ /(some)?(body)/substitute_extended,replace=${1:+\eU:\eL}HeLLo
+ body
+ 1: hello
+ somebody
+ 1: HELLO
+.sp
+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.
+.P
+If successful, \fBpcre2_substitute()\fP returns the number of replacements that
+were made. This may be zero if no matches were found, and is never greater than
+1 unless PCRE2_SUBSTITUTE_GLOBAL is set.
+.P
+In the event of an error, a negative error code is returned. Except for
+PCRE2_ERROR_NOMATCH (which is never returned), errors from \fBpcre2_match()\fP
+are passed straight back.
+.P
+PCRE2_ERROR_NOSUBSTRING is returned for a non-existent substring insertion,
+unless PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set.
+.P
+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.
+.P
+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 \fIoutlengthptr\fP. Note that this does not happen by
+default.
+.P
+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
+not found), PCRE2_ERROR_BADSUBSTITUTION (syntax error in extended group
+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 \eK is used in an assertion).
+.P
+As for all PCRE2 errors, a text message that describes the error can be
+obtained by calling the \fBpcre2_get_error_message()\fP function (see
+"Obtaining a textual error message"
+.\" HTML <a href="#geterrormessage">
+.\" </a>
+above).
+.\"
+.
+.
+.SH "DUPLICATE SUBPATTERN NAMES"
+.rs
+.sp
+.nf
+.B int pcre2_substring_nametable_scan(const pcre2_code *\fIcode\fP,
+.B " PCRE2_SPTR \fIname\fP, PCRE2_SPTR *\fIfirst\fP, PCRE2_SPTR *\fIlast\fP);"
+.fi
+.P
+When a pattern is compiled with the PCRE2_DUPNAMES option, names for
+subpatterns are not required to be unique. Duplicate names are always allowed
+for subpatterns with the same number, created by using the (?| feature. Indeed,
+if such subpatterns are named, they are required to use the same names.
+.P
+Normally, patterns with duplicate names are such that in any one match, only
+one of the named subpatterns participates. An example is shown in the
+.\" HREF
+\fBpcre2pattern\fP
+.\"
+documentation.
+.P
+When duplicates are present, \fBpcre2_substring_copy_byname()\fP and
+\fBpcre2_substring_get_byname()\fP return the first substring corresponding to
+the given name that is set. Only if none are set is PCRE2_ERROR_UNSET is
+returned. The \fBpcre2_substring_number_from_name()\fP function returns the
+error PCRE2_ERROR_NOUNIQUESUBSTRING when there are duplicate names.
+.P
+If you want to get full details of all captured substrings for a given name,
+you must use the \fBpcre2_substring_nametable_scan()\fP 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.
+.P
+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.
+.P
+The format of the name table is described
+.\" HTML <a href="#infoaboutpattern">
+.\" </a>
+above
+.\"
+in the section entitled \fIInformation about a pattern\fP. Given all the
+relevant entries for the name, you can extract each of their numbers, and hence
+the captured data.
+.
+.
+.SH "FINDING ALL POSSIBLE MATCHES AT ONE POSITION"
+.rs
+.sp
+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,
+consider using the alternative matching function (see below) instead. If you
+cannot use the alternative function, you can kludge it up by making use of the
+callout facility, which is described in the
+.\" HREF
+\fBpcre2callout\fP
+.\"
+documentation.
+.P
+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 \fBpcre2_match()\fP to backtrack and try
+other alternatives. Ultimately, when it runs out of matches,
+\fBpcre2_match()\fP will yield PCRE2_ERROR_NOMATCH.
+.
+.
+.\" HTML <a name="dfamatch"></a>
+.SH "MATCHING A PATTERN: THE ALTERNATIVE FUNCTION"
+.rs
+.sp
+.nf
+.B int pcre2_dfa_match(const pcre2_code *\fIcode\fP, PCRE2_SPTR \fIsubject\fP,
+.B " PCRE2_SIZE \fIlength\fP, PCRE2_SIZE \fIstartoffset\fP,"
+.B " uint32_t \fIoptions\fP, pcre2_match_data *\fImatch_data\fP,"
+.B " pcre2_match_context *\fImcontext\fP,"
+.B " int *\fIworkspace\fP, PCRE2_SIZE \fIwscount\fP);"
+.fi
+.P
+The function \fBpcre2_dfa_match()\fP 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.
+This has different characteristics to the normal algorithm, and is not
+compatible with Perl. Some of the features of PCRE2 patterns are not supported.
+Nevertheless, there are times when this kind of matching can be useful. For a
+discussion of the two matching algorithms, and a list of features that
+\fBpcre2_dfa_match()\fP does not support, see the
+.\" HREF
+\fBpcre2matching\fP
+.\"
+documentation.
+.P
+The arguments for the \fBpcre2_dfa_match()\fP function are the same as for
+\fBpcre2_match()\fP, 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 \fBpcre2_match()\fP, so their
+description is not repeated here.
+.P
+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.
+.P
+Here is an example of a simple call to \fBpcre2_dfa_match()\fP:
+.sp
+ int wspace[20];
+ pcre2_match_data *md = pcre2_match_data_create(4, NULL);
+ int rc = pcre2_dfa_match(
+ re, /* result of pcre2_compile() */
+ "some string", /* the subject string */
+ 11, /* the length of the subject string */
+ 0, /* start at offset 0 in the subject */
+ 0, /* default options */
+ md, /* the match data block */
+ NULL, /* a match context; NULL means use defaults */
+ wspace, /* working space vector */
+ 20); /* number of elements (NOT size in bytes) */
+.
+.SS "Option bits for \fBpcre_dfa_match()\fP"
+.rs
+.sp
+The unused bits of the \fIoptions\fP argument for \fBpcre2_dfa_match()\fP must
+be zero. The only bits that may be set are PCRE2_ANCHORED, PCRE2_ENDANCHORED,
+PCRE2_NOTBOL, PCRE2_NOTEOL, PCRE2_NOTEMPTY, PCRE2_NOTEMPTY_ATSTART,
+PCRE2_NO_UTF_CHECK, PCRE2_PARTIAL_HARD, PCRE2_PARTIAL_SOFT, PCRE2_DFA_SHORTEST,
+and PCRE2_DFA_RESTART. All but the last four of these are exactly the same as
+for \fBpcre2_match()\fP, so their description is not repeated here.
+.sp
+ PCRE2_PARTIAL_HARD
+ PCRE2_PARTIAL_SOFT
+.sp
+These have the same general effect as they do for \fBpcre2_match()\fP, but the
+details are slightly different. When PCRE2_PARTIAL_HARD is set for
+\fBpcre2_dfa_match()\fP, it returns PCRE2_ERROR_PARTIAL if the end of the
+subject is reached and there is still at least one matching possibility that
+requires additional characters. This happens even if some complete matches have
+already been found. When PCRE2_PARTIAL_SOFT is set, the return code
+PCRE2_ERROR_NOMATCH is converted into PCRE2_ERROR_PARTIAL if the end of the
+subject is reached, there have been no complete matches, but there is still at
+least one matching possibility. The portion of the string that was inspected
+when the longest partial match was found is set as the first matching string in
+both cases. There is a more detailed discussion of partial and multi-segment
+matching, with examples, in the
+.\" HREF
+\fBpcre2partial\fP
+.\"
+documentation.
+.sp
+ PCRE2_DFA_SHORTEST
+.sp
+Setting the PCRE2_DFA_SHORTEST option causes the matching algorithm to stop as
+soon as it has found one match. Because of the way the alternative algorithm
+works, this is necessarily the shortest possible match at the first possible
+matching point in the subject string.
+.sp
+ PCRE2_DFA_RESTART
+.sp
+When \fBpcre2_dfa_match()\fP returns a partial match, it is possible to call it
+again, with additional subject characters, and have it continue with the same
+match. The PCRE2_DFA_RESTART option requests this action; when it is set, the
+\fIworkspace\fP and \fIwscount\fP options must reference the same vector as
+before because data about the match so far is left in them after a partial
+match. There is more discussion of this facility in the
+.\" HREF
+\fBpcre2partial\fP
+.\"
+documentation.
+.
+.
+.SS "Successful returns from \fBpcre2_dfa_match()\fP"
+.rs
+.sp
+When \fBpcre2_dfa_match()\fP 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
+all initial substrings of the longer matches. For example, if the pattern
+.sp
+ <.*>
+.sp
+is matched against the string
+.sp
+ This is <something> <something else> <something further> no more
+.sp
+the three matched strings are
+.sp
+ <something> <something else> <something further>
+ <something> <something else>
+ <something>
+.sp
+On success, the yield of the function is a number greater than zero, which is
+the number of matched substrings. The offsets of the substrings are returned in
+the ovector, and can be extracted by number in the same way as for
+\fBpcre2_match()\fP, but the numbers bear no relation to any capturing groups
+that may exist in the pattern, because DFA matching does not support group
+capture.
+.P
+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.
+.P
+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.
+.P
+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\ed+" is compiled as if it were "a\ed++". 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\ed+?" or set
+the PCRE2_NO_AUTO_POSSESS option when compiling.
+.
+.
+.SS "Error returns from \fBpcre2_dfa_match()\fP"
+.rs
+.sp
+The \fBpcre2_dfa_match()\fP function returns a negative number when it fails.
+Many of the errors are the same as for \fBpcre2_match()\fP, as described
+.\" HTML <a href="#errorlist">
+.\" </a>
+above.
+.\"
+There are in addition the following errors that are specific to
+\fBpcre2_dfa_match()\fP:
+.sp
+ PCRE2_ERROR_DFA_UITEM
+.sp
+This return is given if \fBpcre2_dfa_match()\fP encounters an item in the
+pattern that it does not support, for instance, the use of \eC in a UTF mode or
+a backreference.
+.sp
+ PCRE2_ERROR_DFA_UCOND
+.sp
+This return is given if \fBpcre2_dfa_match()\fP encounters a condition item
+that uses a backreference for the condition, or a test for recursion in a
+specific group. These are not supported.
+.sp
+ PCRE2_ERROR_DFA_WSSIZE
+.sp
+This return is given if \fBpcre2_dfa_match()\fP runs out of space in the
+\fIworkspace\fP vector.
+.sp
+ PCRE2_ERROR_DFA_RECURSE
+.sp
+When a recursive subpattern is processed, the matching function calls itself
+recursively, using private memory for the ovector and \fIworkspace\fP. This
+error is given if the internal ovector is not large enough. This should be
+extremely rare, as a vector of size 1000 is used.
+.sp
+ PCRE2_ERROR_DFA_BADRESTART
+.sp
+When \fBpcre2_dfa_match()\fP is called with the \fBPCRE2_DFA_RESTART\fP option,
+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.
+.
+.
+.SH "SEE ALSO"
+.rs
+.sp
+\fBpcre2build\fP(3), \fBpcre2callout\fP(3), \fBpcre2demo(3)\fP,
+\fBpcre2matching\fP(3), \fBpcre2partial\fP(3), \fBpcre2posix\fP(3),
+\fBpcre2sample\fP(3), \fBpcre2unicode\fP(3).
+.
+.
+.SH AUTHOR
+.rs
+.sp
+.nf
+Philip Hazel
+University Computing Service
+Cambridge, England.
+.fi
+.
+.
+.SH REVISION
+.rs
+.sp
+.nf
+Last updated: 07 September 2018
+Copyright (c) 1997-2018 University of Cambridge.
+.fi
projects / ossec-hids.git / blobdiff