Provided by: libpcre2-dev_10.42-1_amd64 bug

NAME

       PCRE2 - Perl-compatible regular expressions (revised API)

       #include <pcre2.h>

       PCRE2  is  a  new  API  for  PCRE,  starting  at  release  10.0.  This document contains a
       description of all its native functions. See the pcre2 document for an overview of all the
       PCRE2 documentation.

PCRE2 NATIVE API BASIC FUNCTIONS


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

       void pcre2_code_free(pcre2_code *code);

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

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

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

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

       void pcre2_match_data_free(pcre2_match_data *match_data);

PCRE2 NATIVE API AUXILIARY MATCH FUNCTIONS


       PCRE2_SPTR pcre2_get_mark(pcre2_match_data *match_data);

       uint32_t pcre2_get_ovector_count(pcre2_match_data *match_data);

       PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *match_data);

       PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *match_data);

PCRE2 NATIVE API GENERAL CONTEXT FUNCTIONS


       pcre2_general_context *pcre2_general_context_create(
         void *(*private_malloc)(PCRE2_SIZE, void *),
         void (*private_free)(void *, void *), void *memory_data);

       pcre2_general_context *pcre2_general_context_copy(
         pcre2_general_context *gcontext);

       void pcre2_general_context_free(pcre2_general_context *gcontext);

PCRE2 NATIVE API COMPILE CONTEXT FUNCTIONS


       pcre2_compile_context *pcre2_compile_context_create(
         pcre2_general_context *gcontext);

       pcre2_compile_context *pcre2_compile_context_copy(
         pcre2_compile_context *ccontext);

       void pcre2_compile_context_free(pcre2_compile_context *ccontext);

       int pcre2_set_bsr(pcre2_compile_context *ccontext,
         uint32_t value);

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

       int pcre2_set_compile_extra_options(pcre2_compile_context *ccontext,
         uint32_t extra_options);

       int pcre2_set_max_pattern_length(pcre2_compile_context *ccontext,
         PCRE2_SIZE value);

       int pcre2_set_newline(pcre2_compile_context *ccontext,
         uint32_t value);

       int pcre2_set_parens_nest_limit(pcre2_compile_context *ccontext,
         uint32_t value);

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

PCRE2 NATIVE API MATCH CONTEXT FUNCTIONS


       pcre2_match_context *pcre2_match_context_create(
         pcre2_general_context *gcontext);

       pcre2_match_context *pcre2_match_context_copy(
         pcre2_match_context *mcontext);

       void pcre2_match_context_free(pcre2_match_context *mcontext);

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

       int pcre2_set_substitute_callout(pcre2_match_context *mcontext,
         int (*callout_function)(pcre2_substitute_callout_block *, void *),
         void *callout_data);

       int pcre2_set_offset_limit(pcre2_match_context *mcontext,
         PCRE2_SIZE value);

       int pcre2_set_heap_limit(pcre2_match_context *mcontext,
         uint32_t value);

       int pcre2_set_match_limit(pcre2_match_context *mcontext,
         uint32_t value);

       int pcre2_set_depth_limit(pcre2_match_context *mcontext,
         uint32_t value);

PCRE2 NATIVE API STRING EXTRACTION FUNCTIONS


       int pcre2_substring_copy_byname(pcre2_match_data *match_data,
         PCRE2_SPTR name, PCRE2_UCHAR *buffer, PCRE2_SIZE *bufflen);

       int pcre2_substring_copy_bynumber(pcre2_match_data *match_data,
         uint32_t number, PCRE2_UCHAR *buffer,
         PCRE2_SIZE *bufflen);

       void pcre2_substring_free(PCRE2_UCHAR *buffer);

       int pcre2_substring_get_byname(pcre2_match_data *match_data,
         PCRE2_SPTR name, PCRE2_UCHAR **bufferptr, PCRE2_SIZE *bufflen);

       int pcre2_substring_get_bynumber(pcre2_match_data *match_data,
         uint32_t number, PCRE2_UCHAR **bufferptr,
         PCRE2_SIZE *bufflen);

       int pcre2_substring_length_byname(pcre2_match_data *match_data,
         PCRE2_SPTR name, PCRE2_SIZE *length);

       int pcre2_substring_length_bynumber(pcre2_match_data *match_data,
         uint32_t number, PCRE2_SIZE *length);

       int pcre2_substring_nametable_scan(const pcre2_code *code,
         PCRE2_SPTR name, PCRE2_SPTR *first, PCRE2_SPTR *last);

       int pcre2_substring_number_from_name(const pcre2_code *code,
         PCRE2_SPTR name);

       void pcre2_substring_list_free(PCRE2_SPTR *list);

       int pcre2_substring_list_get(pcre2_match_data *match_data,
         PCRE2_UCHAR ***listptr, PCRE2_SIZE **lengthsptr);

PCRE2 NATIVE API STRING SUBSTITUTION FUNCTION


       int pcre2_substitute(const pcre2_code *code, PCRE2_SPTR subject,
         PCRE2_SIZE length, PCRE2_SIZE startoffset,
         uint32_t options, pcre2_match_data *match_data,
         pcre2_match_context *mcontext, PCRE2_SPTR replacementz,
         PCRE2_SIZE rlength, PCRE2_UCHAR *outputbuffer,
         PCRE2_SIZE *outlengthptr);

PCRE2 NATIVE API JIT FUNCTIONS


       int pcre2_jit_compile(pcre2_code *code, uint32_t options);

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

       void pcre2_jit_free_unused_memory(pcre2_general_context *gcontext);

       pcre2_jit_stack *pcre2_jit_stack_create(PCRE2_SIZE startsize,
         PCRE2_SIZE maxsize, pcre2_general_context *gcontext);

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

       void pcre2_jit_stack_free(pcre2_jit_stack *jit_stack);

PCRE2 NATIVE API SERIALIZATION FUNCTIONS


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

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

       void pcre2_serialize_free(uint8_t *bytes);

       int32_t pcre2_serialize_get_number_of_codes(const uint8_t *bytes);

PCRE2 NATIVE API AUXILIARY FUNCTIONS


       pcre2_code *pcre2_code_copy(const pcre2_code *code);

       pcre2_code *pcre2_code_copy_with_tables(const pcre2_code *code);

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

       const uint8_t *pcre2_maketables(pcre2_general_context *gcontext);

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

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

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

       int pcre2_config(uint32_t what, void *where);

PCRE2 NATIVE API OBSOLETE FUNCTIONS


       int pcre2_set_recursion_limit(pcre2_match_context *mcontext,
         uint32_t value);

       int pcre2_set_recursion_memory_management(
         pcre2_match_context *mcontext,
         void *(*private_malloc)(PCRE2_SIZE, void *),
         void (*private_free)(void *, void *), void *memory_data);

       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
       pcre2_set_depth_limit();  the  second  is  no  longer  needed and has no effect (it always
       returns zero).

PCRE2 EXPERIMENTAL PATTERN CONVERSION FUNCTIONS


       pcre2_convert_context *pcre2_convert_context_create(
         pcre2_general_context *gcontext);

       pcre2_convert_context *pcre2_convert_context_copy(
         pcre2_convert_context *cvcontext);

       void pcre2_convert_context_free(pcre2_convert_context *cvcontext);

       int pcre2_set_glob_escape(pcre2_convert_context *cvcontext,
         uint32_t escape_char);

       int pcre2_set_glob_separator(pcre2_convert_context *cvcontext,
         uint32_t separator_char);

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

       void pcre2_converted_pattern_free(PCRE2_UCHAR *converted_pattern);

       These functions provide a way of converting non-PCRE2 patterns into patterns that  can  be
       processed  by  pcre2_compile(). 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 pcre2convert documentation.

PCRE2 8-BIT, 16-BIT, AND 32-BIT LIBRARIES


       There  are  three  PCRE2  libraries,  supporting  8-bit,  16-bit,  and  32-bit code units,
       respectively. However, there is just one header file, pcre2.h.  This contains the function
       prototypes  and  other  definitions for all three libraries. One, two, or all three can be
       installed simultaneously. On  Unix-like  systems  the  libraries  are  called  libpcre2-8,
       libpcre2-16, and libpcre2-32, and they can also co-exist with the original PCRE libraries.

       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:

         pcre2_compile_8()
         pcre2_compile_16()
         pcre2_compile_32()

       There are also three different sets of data types:

         PCRE2_UCHAR8, PCRE2_UCHAR16, PCRE2_UCHAR32
         PCRE2_SPTR8,  PCRE2_SPTR16,  PCRE2_SPTR32

       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.

       Many  applications use only one code unit width. For their convenience, macros are defined
       whose names are the generic forms such as pcre2_compile() and PCRE2_SPTR. These macros use
       the  value  of  the macro PCRE2_CODE_UNIT_WIDTH to 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 pcre2.h in order to make use of the
       generic names.

       Applications that use more than one code unit width can be linked with more than one PCRE2
       library,  but must define PCRE2_CODE_UNIT_WIDTH to be 0 before including pcre2.h, and then
       use the real function names. Any code that is to be included in an environment  where  the
       value  of  PCRE2_CODE_UNIT_WIDTH  is  unknown  should  also  use  the real function names.
       (Unfortunately, it is not possible in C code to save and restore the value of a macro.)

       If PCRE2_CODE_UNIT_WIDTH is not defined before including pcre2.h, a compiler error occurs.

       When using multiple libraries in an application, you must take care  when  processing  any
       particular  pattern to use only functions from a single library.  For example, if you want
       to run a match using a pattern that was compiled with pcre2_compile_16(), you must  do  so
       with pcre2_match_16(), not pcre2_match_8() or pcre2_match_32().

       In  the  function  summaries  above,  and  in  the  rest  of this document and other PCRE2
       documents, functions and data types are described using their generic names,  without  the
       _8, _16, or _32 suffix.

PCRE2 API OVERVIEW


       PCRE2  has  its  own  native API, which is described in this document. There are also some
       wrapper functions for the 8-bit library that correspond to the  POSIX  regular  expression
       API,  but they do not give access to all the functionality of PCRE2. They are described in
       the pcre2posix documentation. Both these APIs define a set of C function calls.

       The native API C data types, function prototypes,  option  values,  and  error  codes  are
       defined  in  the  header  file pcre2.h, which also contains definitions of PCRE2_MAJOR and
       PCRE2_MINOR, the major and minor release numbers for the  library.  Applications  can  use
       these to include support for different releases of PCRE2.

       In  a Windows environment, if you want to statically link an application program against a
       non-dll PCRE2 library, you must define PCRE2_STATIC before including pcre2.h.

       The functions pcre2_compile() and  pcre2_match()  are  used  for  compiling  and  matching
       regular  expressions  in  a Perl-compatible manner. A sample program that demonstrates the
       simplest way of using them is provided in the file called pcre2demo.c in the PCRE2  source
       distribution.  A  listing of this program is given in the pcre2demo documentation, and the
       pcre2sample documentation describes how to compile and run it.

       The compiling and matching functions recognize various options that are passed as bits  in
       an options argument. There are also some more complicated parameters such as custom memory
       management functions and resource limits that are passed in  "contexts"  (which  are  just
       memory blocks, described below). Simple applications do not need to make use of contexts.

       Just-in-time  (JIT)  compiler support is an optional feature of PCRE2 that can be built in
       appropriate hardware environments. It greatly speeds up the matching performance  of  many
       patterns. Programs can request that it be used if available by calling pcre2_jit_compile()
       after a pattern has been successfully compiled by pcre2_compile(). This  does  nothing  if
       JIT support is not available.

       More   complicated   programs   might  need  to  make  use  of  the  specialist  functions
       pcre2_jit_stack_create(), pcre2_jit_stack_free(), and pcre2_jit_stack_assign() in order to
       control the JIT code's memory usage.

       JIT  matching  is  automatically  used  by  pcre2_match()  if  it is available, unless the
       PCRE2_NO_JIT option is set. There is also a direct interface for JIT matching, which gives
       improved  performance  at  the expense of less sanity checking. The JIT-specific functions
       are discussed in the pcre2jit documentation.

       A second matching function, pcre2_dfa_match(),  which  is  not  Perl-compatible,  is  also
       provided.  This  uses  a  different  algorithm for the matching. The alternative algorithm
       finds all possible matches (at a given 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 pcre2matching documentation. There is no JIT support for
       pcre2_dfa_match().

       In addition to the main compiling and matching functions, there are convenience  functions
       for  extracting  captured  substrings  from  a  subject  string  that  has been matched by
       pcre2_match(). They are:

         pcre2_substring_copy_byname()
         pcre2_substring_copy_bynumber()
         pcre2_substring_get_byname()
         pcre2_substring_get_bynumber()
         pcre2_substring_list_get()
         pcre2_substring_length_byname()
         pcre2_substring_length_bynumber()
         pcre2_substring_nametable_scan()
         pcre2_substring_number_from_name()

       pcre2_substring_free() and pcre2_substring_list_free() 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.

       The function pcre2_substitute() can be called to match a pattern and return a copy of  the
       subject string with substitutions for parts that were matched.

       Functions whose names begin with pcre2_serialize_ are used for saving compiled patterns on
       disc or elsewhere, and reloading them later.

       Finally, there are  functions  for  finding  out  information  about  a  compiled  pattern
       (pcre2_pattern_info())   and   about   the   configuration  with  which  PCRE2  was  built
       (pcre2_config()).

       Functions with names ending with _free() are used for freeing  memory  blocks  of  various
       sorts.  In  all  cases,  if one of these functions is called with a NULL argument, it does
       nothing.

STRING LENGTHS AND OFFSETS


       The PCRE2 API uses string lengths and offsets  into  strings  of  code  units  in  several
       places.  These  values  are  always of type PCRE2_SIZE, which is an unsigned integer type,
       currently always defined as size_t. The largest 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.

NEWLINES


       PCRE2  supports five different conventions for indicating line breaks in strings: a single
       CR (carriage return) character,  a  single  LF  (linefeed)  character,  the  two-character
       sequence  CRLF,  any  of the three preceding, or any 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).

       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 pcre2_compile(), or it can be specified by
       special text at the start of the pattern itself; this overrides any  other  settings.  See
       the pcre2pattern page for details of the special character sequences.

       In  the  PCRE2  documentation the word "newline" is used to mean "the character or pair of
       characters that indicate a line break". The  choice  of  newline  convention  affects  the
       handling  of the dot, circumflex, and dollar 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 section on
       pcre2_match() options below.

       The choice of newline convention does not affect the interpretation of the \n or \r escape
       sequences, nor does it affect what \R matches; this has its own separate convention.

MULTITHREADING


       In  a multithreaded application it is important to keep thread-specific data separate from
       data that can be shared between threads. The PCRE2 library code itself is thread-safe:  it
       contains  no  static or global variables. The API is designed to be fairly simple for non-
       threaded applications while at the same time ensuring that multithreaded applications  can
       use it.

       There  are  several different blocks of data that are used to pass information between the
       application and the PCRE2 libraries.

   The compiled pattern

       A pointer to the compiled form of a pattern is returned to the user  when  pcre2_compile()
       is  successful.  The  data  in the compiled pattern is fixed, and does not change when the
       pattern is matched. Therefore, it is thread-safe, 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 pcre2jit documentation for more details.

       In a more complicated situation, where patterns are compiled  only  when  they  are  first
       needed,  but  are  still  shared  between  threads,  pointers to compiled patterns must be
       protected from simultaneous writing by multiple threads. This is  somewhat  tricky  to  do
       correctly.  If  you  know that writing to a pointer is atomic in your environment, you can
       use logic like this:

         Get a read-only (shared) lock (mutex) for pointer
         if (pointer == NULL)
           {
           Get a write (unique) lock for pointer
           if (pointer == NULL) pointer = pcre2_compile(...
           }
         Release the lock
         Use pointer in pcre2_match()

       Of course, testing for compilation errors should also be included in the code.

       The reason for checking the pointer a second time is as follows: Several threads may  have
       acquired  the shared lock and tested the pointer for being NULL, but only one of them will
       be given the write lock, with the rest kept waiting. The winning thread will  compile  the
       pattern  and  store the result.  After this thread releases the write lock, another thread
       will get it, and if it does not retest pointer for being NULL, will recompile the  pattern
       and overwrite the pointer, creating a memory leak and possibly causing other issues.

       In  an  environment  where  writing to a pointer may not be atomic, the above logic is not
       sufficient. The thread that is doing the compiling may be descheduled after  writing  only
       part  of  the pointer, which could cause other threads to use an invalid value. Instead of
       checking the pointer itself, a separate "pointer is  valid"  flag  (that  can  be  updated
       atomically) must be used:

         Get a read-only (shared) lock (mutex) for pointer
         if (!pointer_is_valid)
           {
           Get a write (unique) lock for pointer
           if (!pointer_is_valid)
             {
             pointer = pcre2_compile(...
             pointer_is_valid = TRUE
             }
           }
         Release the lock
         Use pointer in pcre2_match()

       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 value within the compiled code block, so a thread must gain unique
       write  access  to  the  pointer   before   calling   pcre2_jit_compile().   Alternatively,
       pcre2_code_copy() or pcre2_code_copy_with_tables() can be used to obtain a private copy of
       the compiled code before calling the JIT compiler.

   Context blocks

       The next main section below introduces the idea of "contexts" in which PCRE2 functions are
       called.  A  context  is  nothing more than a collection of parameters that control the way
       PCRE2 operates. Grouping a number of parameters together 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.

       In  a  multithreaded application, if the parameters in a context are values that are never
       changed, the same context can be used by all the threads. However, if any thread needs  to
       change any value in a context, it must make its own thread-specific copy.

   Match blocks

       The  matching  functions  need  a block of memory for storing the results of a match. This
       includes details of what was matched, as well as additional information such as  the  name
       of a (*MARK) setting. Each thread must provide its own copy of this memory.

PCRE2 CONTEXTS


       Some  PCRE2  functions have a lot of parameters, many of which are used only by specialist
       applications, for example,  those  that  use  custom  memory  management  or  non-standard
       character  tables.  To  keep function argument lists at a reasonable size, and at the same
       time to keep the API extensible, "uncommon" parameters are passed to certain functions  in
       a  context  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.

       There are three different types of context: a general context that is relevant for several
       PCRE2 operations, a compile-time context, and a match-time context.

   The general context

       At present, this context  just  contains  pointers  to  (and  data  for)  external  memory
       management functions that are called from several places in the PCRE2 library. The context
       is named `general' rather than specifically `memory' 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:

       pcre2_general_context *pcre2_general_context_create(
         void *(*private_malloc)(PCRE2_SIZE, void *),
         void (*private_free)(void *, void *), void *memory_data);

       The two function pointers specify custom memory  management  functions,  whose  prototypes
       are:

         void *private_malloc(PCRE2_SIZE, void *);
         void  private_free(void *, void *);

       Whenever  code  in  PCRE2  calls  these  functions,  the  final  argument  is the value of
       memory_data. Either of the first two arguments of the creation function may  be  NULL,  in
       which  case  the system memory management functions malloc() and free() are used. (This is
       not currently useful, as there are no other fields in a general  context,  but  in  future
       there might be.)  The private_malloc() function is used (if supplied) to obtain memory for
       storing the context, and all three values are saved as part of the context.

       Whenever PCRE2 creates a data block of any kind, the  block  contains  a  pointer  to  the
       free()  function  that matches the malloc() function that was used. When the time comes to
       free the block, this function is called.

       A general context can be copied by calling:

       pcre2_general_context *pcre2_general_context_copy(
         pcre2_general_context *gcontext);

       The memory used for a general context should be freed by calling:

       void pcre2_general_context_free(pcre2_general_context *gcontext);

       If this function is passed a NULL argument, it returns immediately without doing anything.

   The compile context

       A compile context is required if you want  to  provide  an  external  function  for  stack
       checking  during  compilation  or  to  change  the  default values of any of the following
       compile-time parameters:

         What \R 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)

       A compile context is also required if you are using custom memory management.  If none  of
       these apply, just pass NULL as the context argument of pcre2_compile().

       A compile context is created, copied, and freed by the following functions:

       pcre2_compile_context *pcre2_compile_context_create(
         pcre2_general_context *gcontext);

       pcre2_compile_context *pcre2_compile_context_copy(
         pcre2_compile_context *ccontext);

       void pcre2_compile_context_free(pcre2_compile_context *ccontext);

       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.

       int pcre2_set_bsr(pcre2_compile_context *ccontext,
         uint32_t value);

       The  value  must be PCRE2_BSR_ANYCRLF, to specify that \R matches only CR, LF, or CRLF, or
       PCRE2_BSR_UNICODE, to specify that \R matches any Unicode line ending sequence. The  value
       is  used  by the JIT compiler and by the two interpreted matching functions, pcre2_match()
       and pcre2_dfa_match().

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

       The value must be the result of a call to pcre2_maketables(), whose  only  argument  is  a
       general context. This function builds a set of character tables in the current locale.

       int pcre2_set_compile_extra_options(pcre2_compile_context *ccontext,
         uint32_t extra_options);

       As  PCRE2  has  developed, almost all the 32 option bits that are available in the options
       argument of pcre2_compile() 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" below.

       int pcre2_set_max_pattern_length(pcre2_compile_context *ccontext,
         PCRE2_SIZE value);

       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.

       int pcre2_set_newline(pcre2_compile_context *ccontext,
         uint32_t value);

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

       A pattern can override the value set in the compile context by starting  with  a  sequence
       such as (*CRLF). See the pcre2pattern page for details.

       When  a  pattern  is  compiled  with the PCRE2_EXTENDED or PCRE2_EXTENDED_MORE option, the
       newline convention affects the recognition of the end of internal comments  starting  with
       #. The value is saved with the compiled pattern for subsequent use by the JIT compiler and
       by the two interpreted matching functions, pcre2_match() and pcre2_dfa_match().

       int pcre2_set_parens_nest_limit(pcre2_compile_context *ccontext,
         uint32_t value);

       This parameter adjusts 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.

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

       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 pcre2_compile()  starts
       to  compile  a  parenthesized  part of a pattern. This function can check the actual stack
       size (or anything else that it wants to, of course).

       The first argument to the callout function gives the current depth  of  nesting,  and  the
       second    is    user    data    that    is    set    up    by   the   last   argument   of
       pcre2_set_compile_recursion_guard(). The callout function should return  zero  if  all  is
       well, or non-zero to force an error.

   The match context

       A match context is required if you want to:

         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

       If  none  of  these  apply,  just  pass  NULL  as  the  context argument of pcre2_match(),
       pcre2_dfa_match(), or pcre2_jit_match().

       A match context is created, copied, and freed by the following functions:

       pcre2_match_context *pcre2_match_context_create(
         pcre2_general_context *gcontext);

       pcre2_match_context *pcre2_match_context_copy(
         pcre2_match_context *mcontext);

       void pcre2_match_context_free(pcre2_match_context *mcontext);

       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.

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

       This sets up a callout function for PCRE2 to call at specified points  during  a  matching
       operation. Details are given in the pcre2callout documentation.

       int pcre2_set_substitute_callout(pcre2_match_context *mcontext,
         int (*callout_function)(pcre2_substitute_callout_block *, void *),
         void *callout_data);

       This  sets  up  a  callout  function  for  PCRE2  to  call after each substitution made by
       pcre2_substitute(). Details are given in the section entitled "Creating a new string  with
       substitutions" below.

       int pcre2_set_offset_limit(pcre2_match_context *mcontext,
         PCRE2_SIZE value);

       The  offset_limit parameter limits how far an unanchored search can advance in the subject
       string.  The  default  value  is  PCRE2_UNSET.  The  pcre2_match()  and  pcre2_dfa_match()
       functions  return  PCRE2_ERROR_NOMATCH  if  a match with a starting point before or at the
       given offset is not found. The pcre2_substitute() function makes no more substitutions.

       For example, if the pattern /abc/ is matched against "123abc" with an  offset  limit  less
       than  3,  the result is PCRE2_ERROR_NOMATCH. A match can never be found if the startoffset
       argument of pcre2_match(), pcre2_dfa_match(), or pcre2_substitute() is  greater  than  the
       offset limit set in the match context.

       When  using  this  facility,  you  must set the PCRE2_USE_OFFSET_LIMIT option when calling
       pcre2_compile() so that when JIT is in use, different code can be compiled. If a match  is
       started with a non-default match limit when PCRE2_USE_OFFSET_LIMIT is not set, an error is
       generated.

       The offset limit facility can be used to  track  progress  when  searching  large  subject
       strings  or  to  limit  the  extent  of global substitutions. See also the PCRE2_FIRSTLINE
       option, which requires a match to start before or at the first 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.

       int pcre2_set_heap_limit(pcre2_match_context *mcontext,
         uint32_t value);

       The heap_limit parameter specifies, in units of kibibytes (1024 bytes), the maximum amount
       of heap memory that pcre2_match() may use to hold backtracking information when running an
       interpretive  match.  This limit also applies to pcre2_dfa_match(), 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 pcre2jit 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.

       A  value  for  the heap limit may also be supplied by an item at the start of a pattern of
       the form

         (*LIMIT_HEAP=ddd)

       where ddd is a decimal number. However, such a setting is ignored unless ddd is less  than
       the  limit  set  by the caller of pcre2_match() or, if no such limit is set, less than the
       default.

       The pcre2_match() function always needs some heap memory,  so  setting  a  value  of  zero
       guarantees  a  "heap limit exceeded" error. Details of how pcre2_match() uses the heap are
       given in the pcre2perform documentation.

       For pcre2_dfa_match(), a vector on the  system  stack  is  used  when  processing  pattern
       recursions,  lookarounds,  or  atomic  groups,  and only if this is not big enough is heap
       memory used. In this case, setting a value of zero disables the use of the heap.

       int pcre2_set_match_limit(pcre2_match_context *mcontext,
         uint32_t value);

       The match_limit 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.

       There is an internal counter in pcre2_match() that is incremented each time round its main
       matching loop. If this value reaches the match limit, pcre2_match() returns  the  negative
       value  PCRE2_ERROR_MATCHLIMIT.  This has 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 pcre2_dfa_match(), though
       the counting is done in a different way.

       When  pcre2_match()  is  called  with  a  pattern  that  was  successfully  processed   by
       pcre2_jit_compile(), the way in which matching is executed is entirely different. However,
       there is still the possibility of runaway matching that goes on for a very long time,  and
       so  the  match_limit value is also used in this case (but in a different way) to limit how
       long the matching can continue.

       The default value for the limit can be set when PCRE2 is built; the default 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

         (*LIMIT_MATCH=ddd)

       where ddd is a decimal number. However, such a setting is ignored unless ddd is less  than
       the  limit set by the caller of pcre2_match() or pcre2_dfa_match() or, if no such limit is
       set, less than the default.

       int pcre2_set_depth_limit(pcre2_match_context *mcontext,
         uint32_t value);

       This parameter limits the depth of nested backtracking  in  pcre2_match().   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.

       The depth limit is not relevant, and is ignored, when matching is done using JIT  compiled
       code.  However,  it is supported by pcre2_dfa_match(), which uses it to limit the depth of
       nested  internal  recursive  function  calls  that  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.

       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 pcre2_dfa_match(),  can  use  a
       great  deal  of  memory.  However,  it  is probably better to limit heap usage directly by
       calling pcre2_set_heap_limit().

       The default value for the depth limit can be set when PCRE2 is built; if it  is  not,  the
       default  is  set  to  the  same value as the default for the match limit.  If the limit is
       exceeded, pcre2_match() or pcre2_dfa_match() 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

         (*LIMIT_DEPTH=ddd)

       where  ddd is a decimal number. However, such a setting is ignored unless ddd is less than
       the limit set by the caller of pcre2_match() or pcre2_dfa_match() or, if no such limit  is
       set, less than the default.

CHECKING BUILD-TIME OPTIONS


       int pcre2_config(uint32_t what, void *where);

       The  function  pcre2_config()  makes  it  possible for a PCRE2 client to find the value of
       certain configuration parameters  and  to  discover  which  optional  features  have  been
       compiled into the PCRE2 library. The pcre2build documentation has more details about these
       features.

       The first argument for pcre2_config() specifies which information is required. The  second
       argument  is  a pointer to memory into which the information is placed. If NULL is passed,
       the function returns the amount of memory that is needed for  the  requested  information.
       For  calls  that  return  numerical  values,  the value is in bytes; when requesting these
       values, where should point to appropriately aligned memory. For calls that return strings,
       the required length is given in code units, not counting the terminating zero.

       When  requesting  information,  the  returned value from pcre2_config() is non-negative on
       success, or the negative error code  PCRE2_ERROR_BADOPTION  if  the  value  in  the  first
       argument is not recognized. The following information is available:

         PCRE2_CONFIG_BSR

       The  output  is  a  uint32_t integer whose value indicates what character sequences the \R
       escape sequence matches by default. A value of PCRE2_BSR_UNICODE means that \R matches any
       Unicode  line ending sequence; a value of PCRE2_BSR_ANYCRLF means that \R matches only CR,
       LF, or CRLF. The default can be overridden when a pattern is compiled.

         PCRE2_CONFIG_COMPILED_WIDTHS

       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.

         PCRE2_CONFIG_DEPTHLIMIT

       The output is a uint32_t integer that gives the default limit  for  the  depth  of  nested
       backtracking  in  pcre2_match() or the depth of nested recursions, lookarounds, and atomic
       groups in pcre2_dfa_match(). Further details are given with pcre2_set_depth_limit() above.

         PCRE2_CONFIG_HEAPLIMIT

       The output is a uint32_t integer that gives, in  kibibytes,  the  default  limit  for  the
       amount  of  heap  memory  used  by pcre2_match() or pcre2_dfa_match(). Further details are
       given with pcre2_set_heap_limit() above.

         PCRE2_CONFIG_JIT

       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.

         PCRE2_CONFIG_JITTARGET

       The  where  argument  should  point  to a buffer that is at least 48 code units long. (The
       exact length required can be found by calling pcre2_config() with where 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.

         PCRE2_CONFIG_LINKSIZE

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

       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.

         PCRE2_CONFIG_MATCHLIMIT

       The  output  is  a  uint32_t integer that gives the default match limit for pcre2_match().
       Further details are given with pcre2_set_match_limit() above.

         PCRE2_CONFIG_NEWLINE

       The output is a uint32_t integer whose value specifies the default character sequence that
       is recognized as meaning "newline". The values are:

         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)

       The default should normally correspond to the standard sequence for your operating system.

         PCRE2_CONFIG_NEVER_BACKSLASH_C

       The  output  is  a  uint32_t  integer  that is set to one if the use of \C was permanently
       disabled when PCRE2 was built; otherwise it is set to zero.

         PCRE2_CONFIG_PARENSLIMIT

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

         PCRE2_CONFIG_STACKRECURSE

       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.

         PCRE2_CONFIG_TABLES_LENGTH

       The output is a uint32_t integer that gives the length  of  PCRE2's  character  processing
       tables in bytes. For details of these tables see the section on locale support below.

         PCRE2_CONFIG_UNICODE_VERSION

       The  where  argument  should  point  to a buffer that is at least 24 code units long. (The
       exact length required can be found by calling pcre2_config() with where 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.

         PCRE2_CONFIG_UNICODE

       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.

         PCRE2_CONFIG_VERSION

       The  where  argument  should  point  to a buffer that is at least 24 code units long. (The
       exact length required can be found by calling pcre2_config() with where 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.

COMPILING A PATTERN


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

       void pcre2_code_free(pcre2_code *code);

       pcre2_code *pcre2_code_copy(const pcre2_code *code);

       pcre2_code *pcre2_code_copy_with_tables(const pcre2_code *code);

       The pcre2_compile() function compiles a pattern into an internal  form.   The  pattern  is
       defined  by  a  pointer  to  a  string  of code units and a length (in code units). If the
       pattern is zero-terminated, the length can  be  specified  as  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.

       If the compile context argument ccontext is NULL,  memory  for  the  compiled  pattern  is
       obtained by calling malloc(). Otherwise, it is obtained from the same memory function that
       was  used  for  the  compile  context.  The  caller  must  free  the  memory  by   calling
       pcre2_code_free() when it is no longer needed.  If pcre2_code_free() is called with a NULL
       argument, it returns immediately, without doing anything.

       The function pcre2_code_copy() makes a copy of the compiled code in new memory, using  the
       same  memory  allocator  as  was  used  for  the  original.  However, if the code has been
       processed by the JIT compiler (see 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 pcre2_jit_compile() if required. If pcre2_code_copy() is called
       with a NULL argument, it returns NULL.

       The  pcre2_code_copy()  function  provides a way for individual threads in a multithreaded
       application to acquire a private copy of shared compiled code.  However, it does not  make
       a  copy  of the character tables used by the compiled pattern; the new pattern code points
       to the same tables as the original code.  (See "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 pcre2_code_copy_with_tables() 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
       pcre2_code_free()  is   called   for   the   new   copy   of   the   compiled   code.   If
       pcre2_code_copy_with_tables() is called with a NULL argument, it returns NULL.

       NOTE:  When  one of the matching functions is called, pointers to the compiled pattern and
       the subject string are set in the match data block so that they can be referenced  by  the
       substring  extraction functions after a successful match.  After running a match, you must
       not free a compiled pattern or a subject string until after all operations  on  the  match
       data  block have taken place, unless, in the case of the subject string, you have used the
       PCRE2_COPY_MATCHED_SUBJECT option, which is described in the section entitled "Option bits
       for pcre2_match()" below.

       The  options  argument  for  pcre2_compile() contains various bit settings that affect the
       compilation. It should be zero if none of them are required.  The  available  options  are
       described  below.  Some  of  them (in 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 pcre2pattern documentation).

       For those options that can be different in different parts of the pattern, the contents of
       the  options  argument  specifies  their  settings  at  the  start  of  compilation.   The
       PCRE2_ANCHORED,  PCRE2_ENDANCHORED,  and PCRE2_NO_UTF_CHECK options can be set at the time
       of matching as well as at compile time.

       Some additional options and less frequently required compile-time parameters (for example,
       the newline setting) can be provided in a compile context (as described above).

       If  errorcode or erroroffset is NULL, pcre2_compile() returns NULL immediately. Otherwise,
       the variables to which these point are set to an error code and an offset (number of  code
       units)  within  the  pattern,  respectively,  when  pcre2_compile() returns NULL because a
       compilation error has occurred.

       There are nearly 100 positive error codes that pcre2_compile() may return if it  finds  an
       error  in  the pattern. There are also some negative error codes that are used for invalid
       UTF strings when  validity  checking  is  in  force.  These  are  the  same  as  given  by
       pcre2_match()  and pcre2_dfa_match(), and are described in the pcre2unicode documentation.
       There is no separate documentation for the positive error codes, because the textual error
       messages  that  are  obtained  by  calling  the  pcre2_get_error_message()  function  (see
       "Obtaining a textual  error  message"  below)  should  be  self-explanatory.  Macro  names
       starting  with  PCRE2_ERROR_  are  defined  for  both positive and negative error codes in
       pcre2.h. When compilation is successful errorcode is set  to  a  value  that  returns  the
       message "no error" if passed to pcre2_get_error_message().

       The  value  returned  in  erroroffset  is  an  indication of where in the pattern an error
       occurred. When there is no error, zero is returned. A non-zero value  is  not  necessarily
       the  furthest point in the pattern that was read. For 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.

       Some errors are not detected until the whole pattern has been scanned; in these cases, the
       offset  passed  back  is the length of the pattern. Note that the offset is in code units,
       not characters, even in a UTF mode. It may sometimes point into the middle of a  UTF-8  or
       UTF-16 character.

       This code fragment shows a typical straightforward call to pcre2_compile():

         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 */

   Main compile options

       The following names for option bits are defined in the pcre2.h header file:

         PCRE2_ANCHORED

       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.

         PCRE2_ALLOW_EMPTY_CLASS

       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.

         PCRE2_ALT_BSUX

       This  option  request  alternative handling of three escape sequences, which makes PCRE2's
       behaviour more like ECMAscript (aka JavaScript). When it is set:

       (1) \U matches an upper case "U" character; by default \U  causes  a  compile  time  error
       (Perl uses \U to upper case subsequent characters).

       (2)  \u  matches  a  lower  case  "u"  character unless it is followed by four hexadecimal
       digits, in which case the hexadecimal number defines the code point to match. By  default,
       \u causes a compile time error (Perl uses it to upper case the following character).

       (3) \x matches a lower case "x" character unless it is followed by two hexadecimal digits,
       in which case the hexadecimal number defines the code point to match. By  default,  as  in
       Perl,  a hexadecimal number is always expected after \x, but it may have zero, one, or two
       digits (so, for example, \xz matches a binary zero character followed by z).

       ECMAscript 6 added additional  functionality  to  \u.  This  can  be  accessed  using  the
       PCRE2_EXTRA_ALT_BSUX  extra  option  (see  "Extra compile options" below).  Note that this
       alternative escape handling applies only to patterns. Neither of these options affects the
       processing of replacement strings passed to pcre2_substitute().

         PCRE2_ALT_CIRCUMFLEX

       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.

         PCRE2_ALT_VERBNAMES

       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  \)  or
       between  \Q  and  \E.  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.

         PCRE2_AUTO_CALLOUT

       If  this  bit is set, pcre2_compile() 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 pcre2callout documentation.

         PCRE2_CASELESS

       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 either PCRE2_UTF or PCRE2_UCP is set, Unicode properties are used
       for all characters with more than one other case, and for all characters whose code points
       are  greater  than  U+007F.  Note  that  there are two ASCII characters, K and S, that, in
       addition to their lower case ASCII equivalents, are case-equivalent  with  U+212A  (Kelvin
       sign)  and  U+017F  (long S) respectively. For lower valued characters with only one other
       case, a lookup table is used for speed. When neither PCRE2_UTF nor  PCRE2_UCP  is  set,  a
       lookup  table is used for all code points less than 256, and higher code points (available
       only in 16-bit or 32-bit mode) are treated as not having another case.

         PCRE2_DOLLAR_ENDONLY

       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.

         PCRE2_DOTALL

       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 \N escape sequence always matches a non-
       newline character, independent of the setting of PCRE2_DOTALL.

         PCRE2_DUPNAMES

       If this bit is set, names used to identify capture groups need not be unique.  This can be
       helpful  for certain types of pattern when it is known that only one instance of the named
       group can ever be matched. There are more details of named capture groups below; see  also
       the pcre2pattern documentation.

         PCRE2_ENDANCHORED

       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:

         .(*ACCEPT)|..
         .|..

       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.

       For DFA matching with pcre2_dfa_match(), PCRE2_ENDANCHORED applies only to the first (that
       is, the longest) matched string. Other parallel matches, which are necessarily  substrings
       of the first one, must obviously end before the end of the subject.

         PCRE2_EXTENDED

       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 groups, 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.

       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 pcre2_maketables(), which uses
       the isspace() 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).

       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 \h and \v escapes in patterns are a much bigger set.

       As  well  as  ignoring  most white space, PCRE2_EXTENDED also causes characters between an
       unescaped # outside a character class and the next  newline,  inclusive,  to  be  ignored,
       which makes it possible to include comments inside complicated patterns. Note that the end
       of this type of comment is a literal newline sequence in  the  pattern;  escape  sequences
       that happen to represent a newline do not count.

       Which  characters are interpreted as newlines can be specified by a setting in the compile
       context that is passed to pcre2_compile() or by a special sequence at  the  start  of  the
       pattern,  as  described  in the section entitled "Newline conventions" in the pcre2pattern
       documentation. A default is defined when PCRE2 is built.

         PCRE2_EXTENDED_MORE

       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.

         PCRE2_FIRSTLINE

       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 startoffset is non-zero, the  limiting  newline  is
       not  necessarily  the  first newline in the subject. For example, if the subject string is
       "abc\nxyz" (where \n represents a single-character  newline)  a  pattern  match  for  "yz"
       succeeds   with   PCRE2_FIRSTLINE   if   startoffset   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.

         PCRE2_LITERAL

       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_MATCH_INVALID_UTF,
       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.

         PCRE2_MATCH_INVALID_UTF

       This option forces PCRE2_UTF  (see  below)  and  also  enables  support  for  matching  by
       pcre2_match() in subject strings that contain invalid UTF sequences.  This facility is not
       supported for DFA matching. For details, see the pcre2unicode documentation.

         PCRE2_MATCH_UNSET_BACKREF

       If this option is set, a backreference to an unset capture group matches an  empty  string
       (by  default  this  causes  the  current matching alternative to fail).  A pattern such as
       (\1)(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).

         PCRE2_MULTILINE

       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.

       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.

         PCRE2_NEVER_BACKSLASH_C

       This  option  locks  out the use of \C 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 \C.

         PCRE2_NEVER_UCP

       This  option  locks out the use of Unicode properties for handling \B, \b, \D, \d, \S, \s,
       \W, \w, 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.

         PCRE2_NEVER_UTF

       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.

         PCRE2_NO_AUTO_CAPTURE

       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 capture groups (backreferences or recursion/subroutine calls) may only refer
       to named groups, though the reference can be by name or by number.

         PCRE2_NO_AUTO_POSSESS

       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.

         PCRE2_NO_DOTSTAR_ANCHOR

       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 \A or \G or ^. The optimization is automatically disabled for .* if it  is
       inside  an  atomic  group or a capture group that is the subject of a backreference, or if
       the pattern contains (*PRUNE) or (*SKIP). 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.

         PCRE2_NO_START_OPTIMIZE

       This is an option whose main  effect  is  at  matching  time.  It  does  not  change  what
       pcre2_compile() generates, but it does affect the output of the JIT compiler.

       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.

       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.

       Setting PCRE2_NO_START_OPTIMIZE may change the outcome of a matching operation.   Consider
       the pattern

         (*COMMIT)ABC

       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".

       As another start-up optimization makes use of a minimum length  for  a  matching  subject,
       which is recorded when possible. Consider the pattern

         (*MARK:1)B(*MARK:2)(X|Y)

       The  minimum length for a match is two characters. If the subject is "XXBB", the "starting
       character" optimization skips "XX", then tries to match "BB", which is long enough. In the
       process,  (*MARK:2)  is encountered and remembered. When the match attempt fails, the next
       "B" is found, but there is only one character left, so there are no more attempts, and "no
       match"  is  returned  with  the  "last mark seen" set to "2". If NO_START_OPTIMIZE is set,
       however, matches are tried at every possible starting position, including at  the  end  of
       the  subject, where (*MARK:1) is encountered, but there is no "B", so the "last mark seen"
       that is returned is "1". In this case, the optimizations do not affect the  overall  match
       result,  which  is  still "no match", but they do affect the auxiliary information that is
       returned.

         PCRE2_NO_UTF_CHECK

       When PCRE2_UTF is set, the validity of the  pattern  as  a  UTF  string  is  automatically
       checked.  There  are  discussions about the validity of UTF-8 strings, UTF-16 strings, and
       UTF-32 strings in the  pcre2unicode  document.  If  an  invalid  UTF  sequence  is  found,
       pcre2_compile() returns a negative error code.

       If  you  know that your pattern is a valid UTF string, and you want to skip this check for
       performance reasons, you can set the PCRE2_NO_UTF_CHECK option. When it is set, the effect
       of  passing  an invalid UTF string as a pattern is undefined. It may cause your program to
       crash or loop.

       Note that this option can also  be  passed  to  pcre2_match()  and  pcre2_dfa_match(),  to
       suppress UTF validity checking of the subject string.

       Note  also that setting PCRE2_NO_UTF_CHECK at compile time does not disable the error that
       is given if an escape sequence for an invalid Unicode code point  is  encountered  in  the
       pattern.  In  particular,  the  so-called  "surrogate"  code points (0xd800 to 0xdfff) are
       invalid. If you want  to  allow  escape  sequences  such  as  \x{d800}  you  can  set  the
       PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES  extra  option,  as  described in the section entitled
       "Extra compile options" below.  However, this is possible only in UTF-8 and UTF-32  modes,
       because these values are not representable in UTF-16.

         PCRE2_UCP

       This  option  has  two effects. Firstly, it change the way PCRE2 processes \B, \b, \D, \d,
       \S, \s, \W, \w, 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  generic  character  types  in  the
       pcre2pattern  page.  If you set PCRE2_UCP, matching one of the items it affects takes much
       longer.

       The second effect of PCRE2_UCP is to force the use of Unicode properties  for  upper/lower
       casing  operations on characters with code points greater than 127, even when PCRE2_UTF is
       not set. This makes it possible, for example, to process strings in the 16-bit UCS-2 code.
       This  option  is  available only if PCRE2 has been compiled with Unicode support (which is
       the default).

         PCRE2_UNGREEDY

       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.

         PCRE2_USE_OFFSET_LIMIT

       This option must be set for pcre2_compile() if pcre2_set_offset_limit()  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 pcre2_set_offset_limit() in the section that describes
       match contexts. See also the PCRE2_FIRSTLINE option above.

         PCRE2_UTF

       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  pcre2unicode  page.  In
       particular,  note  that  it  changes  the  way PCRE2_CASELESS handles characters with code
       points greater than 127.

   Extra compile options

       The  option  bits  that   can   be   set   in   a   compile   context   by   calling   the
       pcre2_set_compile_extra_options() function are as follows:

         PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK

       Since  release  10.38  PCRE2  has  forbidden  the  use of \K within lookaround assertions,
       following Perl's lead. This option is provided to re-enable the previous behaviour (act in
       positive lookarounds, ignore in negative ones) in case anybody is relying on it.

         PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES

       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.

       These  values also cause errors if encountered in escape sequences such as \x{d912} within
       a pattern. However, it seems that  some  applications,  when  using  PCRE2  to  check  for
       unwanted  characters  in  UTF-8  strings,  explicitly test for the surrogates using escape
       sequences. The PCRE2_NO_UTF_CHECK option does not disable the error that  occurs,  because
       it applies only to the testing of input strings for UTF validity.

       If  the  extra  option  PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES  is  set, surrogate code point
       values in UTF-8 and UTF-32 patterns no longer provoke errors and are incorporated  in  the
       compiled pattern. However, they can only match subject characters if the matching function
       is called with PCRE2_NO_UTF_CHECK set.

         PCRE2_EXTRA_ALT_BSUX

       The original option PCRE2_ALT_BSUX causes PCRE2 to process \U, \u, and \x in the way  that
       ECMAscript  (aka  JavaScript)  does. Additional functionality was defined by ECMAscript 6;
       setting PCRE2_EXTRA_ALT_BSUX  has  the  effect  of  PCRE2_ALT_BSUX,  but  in  addition  it
       recognizes  \u{hhh..}  as  a  hexadecimal  character  code,  where  hhh.. is any number of
       hexadecimal digits.

         PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL

       This is a dangerous option. Use with care. By default, an unrecognized escape such  as  \j
       or  a  malformed  one  such  as  \x{2z}  causes  a  compile-time  error  when  detected by
       pcre2_compile(). Perl is somewhat inconsistent in handling such items: for example, \j  is
       treated  as  a  literal  "j",  and non-hexadecimal digits in \x{} are just ignored, though
       warnings are given in both cases if Perl's warning switch is enabled. However, a malformed
       octal number after \o{ always causes an error in Perl.

       If  the  PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL  extra option is passed to pcre2_compile(), all
       unrecognized or malformed escape sequences are treated as  single-character  escapes.  For
       example,  \j is a literal "j" and \x{2z} is treated as the literal string "x{2z}". Setting
       this option means that typos in patterns may go undetected and  have  unexpected  results.
       Also note that a sequence such as [\N{] is interpreted as a malformed attempt at [\N{...}]
       and so is treated as [N{] whereas [\N] gives an error because an unqualified \N is a valid
       escape  sequence  but  is  not  supported  in  a  character class. To reiterate: this is a
       dangerous option. Use with great care.

         PCRE2_EXTRA_ESCAPED_CR_IS_LF

       There are some legacy applications where the escape sequence \r in a pattern  is  expected
       to  match  a newline. If this option is set, \r in a pattern is converted to \n so that it
       matches a LF (linefeed) instead of a CR (carriage return) character. The option  does  not
       affect  a  literal  CR in the pattern, nor does it affect CR specified as an explicit code
       point such as \x{0D}.

         PCRE2_EXTRA_MATCH_LINE

       This option is provided for use by the -x option of pcre2grep. 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.

         PCRE2_EXTRA_MATCH_WORD

       This option is provided for use by the -w option of pcre2grep. 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 "\b(?:" at the start  of  the  compiled  pattern  and
       ")\b"  at  the  end.  The option may be used with PCRE2_LITERAL. However, it is ignored if
       PCRE2_EXTRA_MATCH_LINE is also set.

JUST-IN-TIME (JIT) COMPILATION


       int pcre2_jit_compile(pcre2_code *code, uint32_t options);

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

       void pcre2_jit_free_unused_memory(pcre2_general_context *gcontext);

       pcre2_jit_stack *pcre2_jit_stack_create(PCRE2_SIZE startsize,
         PCRE2_SIZE maxsize, pcre2_general_context *gcontext);

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

       void pcre2_jit_stack_free(pcre2_jit_stack *jit_stack);

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

       JIT  compilation  is  a heavyweight optimization. It can take some time for patterns to be
       analyzed, and for one-off matches and simple patterns  the  benefit  of  faster  execution
       might  be  offset  by  a much slower compilation time.  Most (but not all) patterns can be
       optimized by the JIT compiler.

LOCALE SUPPORT


       const uint8_t *pcre2_maketables(pcre2_general_context *gcontext);

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

       PCRE2 handles caseless matching, and determines whether characters are letters, digits, or
       whatever,  by reference to a set of tables, indexed by character code point. However, this
       applies only to characters whose code points are less than 256. By default,  higher-valued
       code points never match escapes such as \w or \d.

       When  PCRE2  is  built  with  Unicode  support  (the  default),  certain Unicode character
       properties can be tested with \p and \P, or, alternatively, the PCRE2_UCP  option  can  be
       set when a pattern is compiled; this causes \w and friends to use Unicode property support
       instead of the built-in tables.  PCRE2_UCP also causes upper/lower  casing  operations  on
       characters  with  code  points  greater  than 127 to use Unicode properties. These effects
       apply even when PCRE2_UTF is not set.

       The use of locales with Unicode is discouraged. If you are handling characters  with  code
       points  greater  than  127, you should either use Unicode support, or use locales, but not
       try to mix the two.

       PCRE2 contains a built-in set of character tables that are used  by  default.   These  are
       sufficient  for  many  applications.  Normally,  the  internal tables recognize only ASCII
       characters. However, when PCRE2 is built, it is possible to cause the internal  tables  to
       be  rebuilt  in  the  default  "C"  locale of the local system, which may cause them to be
       different.

       The built-in tables can be overridden by tables supplied by  the  application  that  calls
       PCRE2.  These  may  be  created  in a different locale from the default.  As more and more
       applications change to using Unicode, the need for this locale support is expected to  die
       away.

       External  tables  are  built  by  calling the pcre2_maketables() function, in the relevant
       locale. The only argument to this function is a general context, which can be used to pass
       a  custom  memory  allocator.  If  the  argument is NULL, the system malloc() is used. The
       result can be passed to pcre2_compile() as often  as  necessary,  by  creating  a  compile
       context and calling pcre2_set_character_tables() to set the tables pointer therein.

       For  example,  to  build  and use tables that are appropriate for the French locale (where
       accented characters with values greater than 127 are treated as  letters),  the  following
       code could be used:

         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);

       The  locale  name  "fr_FR"  is used on Linux and other Unix-like systems; if you are using
       Windows, the name for the French locale is "french".

       The pointer that is passed (via the compile context) to pcre2_compile() is saved with  the
       compiled  pattern,  and  the same tables are used by the matching functions. Thus, for any
       single pattern, compilation and matching both happen in the  same  locale,  but  different
       patterns can be processed in different locales.

       It  is the caller's responsibility to ensure that the memory containing the tables remains
       available while they are still in use. When they are no longer  needed,  you  can  discard
       them  using  pcre2_maketables_free(),  which  should  pass as its first parameter the same
       global context that was used to create the tables.

   Saving locale tables

       The tables described above  are  just  a  sequence  of  binary  bytes,  which  makes  them
       independent  of  hardware  characteristics  such as endianness or whether the processor is
       32-bit or 64-bit. A copy of the result of pcre2_maketables() can therefore be saved  in  a
       file  or  elsewhere and re-used later, even in a different program or on another computer.
       The size of the tables (number of bytes) must be obtained by calling  pcre2_config()  with
       the  PCRE2_CONFIG_TABLES_LENGTH  option  because  pcre2_maketables()  does not return this
       value. Note that the pcre2_dftables program, which is part of the PCRE2 build system,  can
       be  used  stand-alone  to  create  a  file  that  contains a set of binary tables. See the
       pcre2build documentation for details.

INFORMATION ABOUT A COMPILED PATTERN


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

       The pcre2_pattern_info() function returns general information about  a  compiled  pattern.
       For   information   about  callouts,  see  the  next  section.   The  first  argument  for
       pcre2_pattern_info() 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:

         PCRE2_ERROR_NULL           the argument code was NULL
         PCRE2_ERROR_BADMAGIC       the "magic number" was not found
         PCRE2_ERROR_BADOPTION      the value of what was invalid
         PCRE2_ERROR_UNSET          the requested field is not set

       The  "magic  number"  is  placed  at  the start of each compiled pattern as a simple check
       against  passing  an   arbitrary   memory   pointer.   Here   is   a   typical   call   of
       pcre2_pattern_info(), to obtain the length of the compiled pattern:

         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 */

       The possible values for the second argument are defined in pcre2.h, and are as follows:

         PCRE2_INFO_ALLOPTIONS
         PCRE2_INFO_ARGOPTIONS
         PCRE2_INFO_EXTRAOPTIONS

       Return  copies  of  the  pattern's  options. The third argument should point to a uint32_t
       variable.  PCRE2_INFO_ARGOPTIONS  returns  exactly  the  options  that  were   passed   to
       pcre2_compile(),  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.

       For example, if the pattern /(*UTF)abc/ is compiled with the  PCRE2_EXTENDED  option,  the
       result for PCRE2_INFO_ALLOPTIONS is PCRE2_EXTENDED and PCRE2_UTF.  Option settings such as
       (?i) that can change within a pattern do not affect the result  of  PCRE2_INFO_ALLOPTIONS,
       even if they appear right at the start of the pattern. (This was different in some earlier
       releases.)

       A pattern compiled without PCRE2_ANCHORED is automatically anchored by PCRE2 if the  first
       significant item in every top-level branch is one of the following:

         ^     unless PCRE2_MULTILINE is set
         \A    always
         \G    always
         .*    sometimes - see below

       When  .*  is the first significant item, anchoring is possible only when all the following
       are true:

         .* is not in an atomic group
         .* is not in a capture 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

       For patterns that are auto-anchored, the PCRE2_ANCHORED bit is set in the options returned
       for PCRE2_INFO_ALLOPTIONS.

         PCRE2_INFO_BACKREFMAX

       Return  the  number of the highest backreference in the pattern. The third argument should
       point to a uint32_t variable. Named capture groups acquire numbers as well as  names,  and
       these  count  towards the highest backreference. Backreferences such as \4 or \g{12} match
       the captured characters of the given group, but in addition,  the  check  that  a  capture
       group  is  set  in a conditional group such as (?(3)a|b) is also a backreference.  Zero is
       returned if there are no backreferences.

         PCRE2_INFO_BSR

       The output is a uint32_t integer whose value indicates what  character  sequences  the  \R
       escape  sequence  matches.  A value of PCRE2_BSR_UNICODE means that \R matches any Unicode
       line ending sequence; a value of PCRE2_BSR_ANYCRLF means that \R matches only CR,  LF,  or
       CRLF.

         PCRE2_INFO_CAPTURECOUNT

       Return the highest capture group number in the pattern. In patterns where (?| is not used,
       this is also the total number of capture groups. The third  argument  should  point  to  a
       uint32_t variable.

         PCRE2_INFO_DEPTHLIMIT

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

         PCRE2_INFO_FIRSTBITMAP

       In the absence of a single first code unit for a non-anchored pattern, pcre2_compile() 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 const uint8_t *
       variable.

         PCRE2_INFO_FIRSTCODETYPE

       Return information about the first code unit of any matched  string,  for  a  non-anchored
       pattern. The third argument should point to a uint32_t 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.

         PCRE2_INFO_FIRSTCODEUNIT

       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
       a uint32_t 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.

         PCRE2_INFO_FRAMESIZE

       Return the size (in bytes) of the data frames  that  are  used  to  remember  backtracking
       positions when the pattern is processed by pcre2_match() without the use of JIT. The third
       argument should point to a size_t variable. The  frame  size  depends  on  the  number  of
       capturing  parentheses  in  the pattern. Each additional capture group adds two PCRE2_SIZE
       variables.

         PCRE2_INFO_HASBACKSLASHC

       Return 1 if the pattern contains any instances of \C,  otherwise  0.  The  third  argument
       should point to a uint32_t variable.

         PCRE2_INFO_HASCRORLF

       Return  1  if the pattern contains any explicit matches for CR or LF characters, otherwise
       0. The third argument should point to a uint32_t variable. An explicit match is  either  a
       literal  CR  or  LF  character,  or \r or \n or one of the equivalent hexadecimal or octal
       escape sequences.

         PCRE2_INFO_HEAPLIMIT

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

         PCRE2_INFO_JCHANGED

       Return 1 if the (?J) or (?-J) option setting is used in  the  pattern,  otherwise  0.  The
       third argument should point to a uint32_t variable. (?J) and (?-J) set and unset the local
       PCRE2_DUPNAMES option, respectively.

         PCRE2_INFO_JITSIZE

       If the compiled pattern was successfully processed by pcre2_jit_compile(), return the size
       of  the  JIT  compiled  code,  otherwise return zero. The third argument should point to a
       size_t variable.

         PCRE2_INFO_LASTCODETYPE

       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 a uint32_t 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\d+z\d+/  the returned value is 1 (with "z" returned from PCRE2_INFO_LASTCODEUNIT), but
       for /^a\dz\d/ the returned value is 0.

         PCRE2_INFO_LASTCODEUNIT

       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 a uint32_t variable.

         PCRE2_INFO_MATCHEMPTY

       Return 1 if the pattern might match an empty  string,  otherwise  0.  The  third  argument
       should point to a uint32_t 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.

         PCRE2_INFO_MATCHLIMIT

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

         PCRE2_INFO_MAXLOOKBEHIND

       A  lookbehind assertion moves back a certain number of characters (not code units) when it
       starts to process each of its branches. This request returns the largest of these backward
       moves. The third argument should point to a uint32_t integer. The simple assertions \b and
       \B require a one-character lookbehind and cause PCRE2_INFO_MAXLOOKBEHIND to  return  1  in
       the  absence  of  anything longer. \A also registers a one-character lookbehind, though it
       does not actually inspect the previous character.

       Note that this information is useful  for  multi-segment  matching  only  if  the  pattern
       contains  no nested lookbehinds. For example, the pattern (?<=a(?<=ba)c) returns a maximum
       lookbehind of 2, but when it  is  processed,  the  first  lookbehind  moves  back  by  two
       characters,  matches  one  character,  then  the  nested lookbehind also moves back by two
       characters. This puts the matching point three characters  earlier  than  it  was  at  the
       start.   PCRE2_INFO_MAXLOOKBEHIND  is  really  only  useful  as  a debugging tool. See the
       pcre2partial documentation for a discussion of multi-segment matching.

         PCRE2_INFO_MINLENGTH

       If a minimum length for matching subject strings was  computed,  its  value  is  returned.
       Otherwise the returned value is 0. This value is not computed when PCRE2_NO_START_OPTIMIZE
       is set. 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 a uint32_t 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.

         PCRE2_INFO_NAMECOUNT
         PCRE2_INFO_NAMEENTRYSIZE
         PCRE2_INFO_NAMETABLE

       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  pcre2_substring_get_byname()  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 pcre2_match() below). To do the conversion, you need to  use
       the name-to-number map, which is described by these three values.

       The  map consists of a number of fixed-size entries. PCRE2_INFO_NAMECOUNT gives the number
       of entries, and PCRE2_INFO_NAMEENTRYSIZE gives the size of each entry in code units;  both
       of  these  return  a  uint32_t  value. The entry size depends on the length of the longest
       name.

       PCRE2_INFO_NAMETABLE returns a pointer to  the  first  entry  of  the  table.  This  is  a
       PCRE2_SPTR  pointer to a block of code units. In the 8-bit library, the first two bytes of
       each entry are the number of the capturing parenthesis, most 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.

       The names are in alphabetical order. If (?| is used to create multiple capture groups with
       the  same  number,  as  described  in  the  section  on  duplicate  group  numbers  in the
       pcre2pattern page, the groups may be given the same name, but there is only one  entry  in
       the table. Different names for groups of the same number are not permitted.

       Duplicate  names  for  capture  groups  with  different numbers are permitted, but only if
       PCRE2_DUPNAMES is set. They appear in the table in the order in which they were  found  in
       the  pattern.  In  the  absence of (?| this is the order of increasing number; when (?| is
       used this is not necessarily the case because later capture groups may have lower numbers.

       As a simple example of  the  name/number  table,  consider  the  following  pattern  after
       compilation by the 8-bit library (assume PCRE2_EXTENDED is set, so white space - including
       newlines - is ignored):

         (?<date> (?<year>(\d\d)?\d\d) -
         (?<month>\d\d) - (?<day>\d\d) )

       There are four named capture groups, 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 ??:

         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 ??

       When writing code to extract data from named capture groups using the name-to-number  map,
       remember  that  the  length  of  the  entries  is likely to be different for each compiled
       pattern.

         PCRE2_INFO_NEWLINE

       The output is one of the following uint32_t values:

         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)

       This identifies the character sequence that will be recognized as meaning "newline"  while
       matching.

         PCRE2_INFO_SIZE

       Return  the  size  of  the  compiled pattern in bytes (for all three libraries). The third
       argument should point to a size_t 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 pcre2_compile() 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.

INFORMATION ABOUT A PATTERN'S CALLOUTS


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

       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
       pcre2_callout_enumerate().  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
       user_data  value that was passed to pcre2_callout_enumerate(). The contents of the callout
       enumeration block are described  in  the  pcre2callout  documentation,  which  also  gives
       further details about callouts.

SERIALIZATION AND PRECOMPILING


       It  is  possible  to  save  compiled patterns on disc or elsewhere, and reload them later,
       subject to a number of restrictions. The host on which the patterns are reloaded  must  be
       running  the  same version of PCRE2, with the same code unit 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 pcre2_serialize_ are used  for
       converting  to  and  from  the  serialized  form. They are described in the pcre2serialize
       documentation. Note that PCRE2 serialization does not  convert  compiled  patterns  to  an
       abstract format like Java or .NET serialization.

THE MATCH DATA BLOCK


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

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

       void pcre2_match_data_free(pcre2_match_data *match_data);

       Information  about  a  successful  or  unsuccessful match is placed in a match data block,
       which is an opaque structure that is accessed by function calls. In particular, the  match
       data  block  contains  a vector of offsets into the subject string that define the matched
       parts of the subject. This is known as the ovector.

       Before calling pcre2_match(), pcre2_dfa_match(), or pcre2_jit_match() you  must  create  a
       match   data   block   by   calling   one   of   the   creation   functions   above.   For
       pcre2_match_data_create(), the first argument is the number of pairs  of  offsets  in  the
       ovector.

       When  using  pcre2_match(),  one  pair  of offsets is required to identify the string that
       matched the whole pattern, with an  additional  pair  for  each  captured  substring.  For
       example,  a  value  of 4 creates enough space to record the matched portion of the subject
       plus three captured substrings.

       When using pcre2_dfa_match() there may be multiple matched substrings of different lengths
       at  the same point in the subject. The ovector should be made large enough to hold as many
       as are expected.

       A minimum of at least 1 pair is imposed by  pcre2_match_data_create(),  so  it  is  always
       possible  to return the overall matched string in the case of pcre2_match() or the longest
       match in the case of pcre2_dfa_match(). The maximum number of pairs is 65535; if  the  the
       first argument of pcre2_match_data_create() is greater than this, 65535 is used.

       The  second argument of pcre2_match_data_create() is a pointer to a general context, which
       can specify custom memory management for obtaining the memory for the match data block. If
       you are not using custom memory management, pass NULL, which causes malloc() to be used.

       For  pcre2_match_data_create_from_pattern(), the first argument is a pointer to a compiled
       pattern. The ovector is created to be exactly the right size to hold all the substrings  a
       pattern  might capture when matched using pcre2_match(). You should not use this call when
       matching with pcre2_dfa_match(). The second argument is  again  a  pointer  to  a  general
       context,  but  in  this  case  if  NULL  is  passed, the memory is obtained using the same
       allocator that was used for the compiled pattern (custom or default).

       A match data block can be used many times, with the same or different  compiled  patterns.
       You  can extract information from a match data block after a match operation has finished,
       using functions that are described in the sections on matched strings and other match data
       below.

       When  a  call of pcre2_match() fails, valid data is available in the match block only when
       the error is PCRE2_ERROR_NOMATCH, PCRE2_ERROR_PARTIAL, or one of the error  codes  for  an
       invalid UTF string. Exactly what is available depends on the error, and is detailed below.

       When  one  of  the  matching functions is called, pointers to the compiled pattern and the
       subject string are set in the match data block so that  they  can  be  referenced  by  the
       extraction  functions after a successful match. After running 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, unless, in the case of the subject string, you have
       used the PCRE2_COPY_MATCHED_SUBJECT option, which is described  in  the  section  entitled
       "Option bits for pcre2_match()" below.

       When  a  match  data  block  itself  is  no  longer  needed, it should be freed by calling
       pcre2_match_data_free(). If this function is called  with  a  NULL  argument,  it  returns
       immediately, without doing anything.

MATCHING A PATTERN: THE TRADITIONAL FUNCTION


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

       The function pcre2_match() is called to match a subject string against a compiled pattern,
       which is passed in the code argument. You  can  call  pcre2_match()  with  the  same  code
       argument  as  many  times  as  you  like, in order to find multiple matches in the subject
       string or to match different subject strings with the same pattern.

       This function is the main matching facility of the library, and it operates in a Perl-like
       manner.  For  specialist  use  there  is  also  an alternative matching function, which is
       described below in the section about the pcre2_dfa_match() function.

       Here is an example of a simple call to pcre2_match():

         pcre2_match_data *md = pcre2_match_data_create(4, NULL);
         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 */

       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 the match context above.

   The string to be matched by pcre2_match()

       The subject string is passed to pcre2_match() as a pointer in subject, a length in length,
       and  a  starting  offset  in  startoffset.  The  length  and offset are in code units, not
       characters.  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. As a special case, if subject is  NULL  and  length  is  zero,  the
       subject  is  assumed  to  be  an  empty  string. If length is non-zero, an error occurs if
       subject is NULL.

       If  startoffset  is  greater  than  the  length  of  the  subject,  pcre2_match()  returns
       PCRE2_ERROR_BADOFFSET.  When the starting offset is zero, the search for a match starts at
       the beginning of the subject, and this 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.

       A  non-zero starting offset is useful when searching for another match in the same subject
       by calling pcre2_match() again after a previous success.  Setting startoffset differs from
       passing  over  a  shortened  string and setting PCRE2_NOTBOL in the case of a pattern that
       begins with any kind of lookbehind. For example, consider the pattern

         \Biss\B

       which finds occurrences of "iss" in the middle of words. (\B matches only if  the  current
       position  in the subject is not a word boundary.) When applied to the string "Mississippi"
       the first call to pcre2_match() finds the first occurrence.  If  pcre2_match()  is  called
       again with just the remainder of the subject, namely "issippi", it does not match, because
       \B is always false at the start of the subject, which is deemed to  be  a  word  boundary.
       However,  if  pcre2_match() is passed the entire string again, but with startoffset set to
       4, it finds the second occurrence of "iss" because it is able to look behind the  starting
       point to discover that it is preceded by a letter.

       Finding all the matches in a subject is tricky when the pattern can match an empty string.
       It is possible to emulate Perl's /g behaviour by first trying the match again at the  same
       offset,  with  the  PCRE2_NOTEMPTY_ATSTART  and  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 pcre2demo 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.

       If a non-zero starting offset is passed when the pattern is anchored, a single attempt  to
       match  at  the given offset is made. This can only succeed if the pattern does not require
       the match to be at the start of the subject. In other words, the  anchoring  must  be  the
       result  of  setting  the  PCRE2_ANCHORED option or the use of .* with PCRE2_DOTALL, not by
       starting the pattern with ^ or \A.

   Option bits for pcre2_match()

       The unused bits of the options argument for pcre2_match() must be zero. The only bits that
       may    be   set   are   PCRE2_ANCHORED,   PCRE2_COPY_MATCHED_SUBJECT,   PCRE2_ENDANCHORED,
       PCRE2_NOTBOL,   PCRE2_NOTEOL,   PCRE2_NOTEMPTY,   PCRE2_NOTEMPTY_ATSTART,    PCRE2_NO_JIT,
       PCRE2_NO_UTF_CHECK,  PCRE2_PARTIAL_HARD, and PCRE2_PARTIAL_SOFT. Their action is described
       below.

       Setting PCRE2_ANCHORED or PCRE2_ENDANCHORED at match time is not supported by the just-in-
       time  (JIT)  compiler. If it is set, JIT matching is disabled and the interpretive code in
       pcre2_match() is run. Apart from  PCRE2_NO_JIT  (obviously),  the  remaining  options  are
       supported for JIT matching.

         PCRE2_ANCHORED

       The PCRE2_ANCHORED option limits pcre2_match() 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.

         PCRE2_COPY_MATCHED_SUBJECT

       By default, a pointer to the subject is remembered in the match data block so that,  after
       a successful match, it can be referenced by the substring extraction functions. This means
       that the subject's memory must not be freed until all such operations  are  complete.  For
       some  applications  where  the lifetime of the subject string is not guaranteed, it may be
       necessary to make a copy of the subject string, but it is wasteful to do this  unless  the
       match  is  successful. After a successful match, if PCRE2_COPY_MATCHED_SUBJECT is set, the
       subject is copied and the new pointer is remembered in the match data block instead of the
       original subject pointer. The memory allocator that was used for the match block itself is
       used. The copy is automatically freed when pcre2_match_data_free() is called to  free  the
       match  data  block.  It is also automatically freed if the match data block is re-used for
       another match operation.

         PCRE2_ENDANCHORED

       If the PCRE2_ENDANCHORED option is set, any string  that  pcre2_match()  matches  must  be
       right  at  the  end  of  the  subject  string.  Note that setting the option at match time
       disables JIT matching.

         PCRE2_NOTBOL

       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 \A.

         PCRE2_NOTEOL

       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 \Z or \z.

         PCRE2_NOTEMPTY

       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

         a?b?

       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  pcre2_match()
       searches further into the string for occurrences of "a" or "b".

         PCRE2_NOTEMPTY_ATSTART

       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 \K.

         PCRE2_NO_JIT

       By default, if a pattern has been successfully processed by  pcre2_jit_compile(),  JIT  is
       automatically  used  when  pcre2_match() 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.

         PCRE2_NO_UTF_CHECK

       When PCRE2_UTF is set at compile time, the validity of the subject  as  a  UTF  string  is
       checked  unless  PCRE2_NO_UTF_CHECK  is passed to pcre2_match() or PCRE2_MATCH_INVALID_UTF
       was passed to pcre2_compile(). The latter special case  is  discussed  in  detail  in  the
       pcre2unicode documentation.

       In  the default case, if a non-zero starting offset is given, the check is applied only to
       that part of the subject that could be inspected during matching, and  there  is  a  check
       that the starting offset points to the first 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  \b  and  \B  are one-character
       lookbehinds.

       The check is carried out before any other processing takes place,  and  a  negative  error
       code  is returned if the check fails. There are several UTF error codes for each code unit
       width, corresponding to  different  problems  with  the  code  unit  sequence.  There  are
       discussions about the validity of UTF-8 strings, UTF-16 strings, and UTF-32 strings in the
       pcre2unicode documentation.

       If you know that your subject is valid, and you want to skip this  check  for  performance
       reasons,  you  can set the PCRE2_NO_UTF_CHECK option when calling pcre2_match(). You might
       want to do this for the second and subsequent calls to pcre2_match()  if  you  are  making
       repeated calls to find multiple matches in the same subject string.

       Warning:  Unless  PCRE2_MATCH_INVALID_UTF was set at compile time, when PCRE2_NO_UTF_CHECK
       is set at match time the effect of passing an invalid string as a subject, or  an  invalid
       value  of  startoffset, is undefined.  Your program may crash or loop indefinitely or give
       wrong results.

         PCRE2_PARTIAL_HARD
         PCRE2_PARTIAL_SOFT

       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. In addition, either at least one character must have been inspected or
       the  pattern  must  contain  a  lookbehind, or the pattern must be one that could match an
       empty string.

       If this situation arises when PCRE2_PARTIAL_SOFT  (but  not  PCRE2_PARTIAL_HARD)  is  set,
       matching continues by testing any remaining alternatives. Only if no complete match can be
       found is PCRE2_ERROR_PARTIAL returned instead  of  PCRE2_ERROR_NOMATCH.  In  other  words,
       PCRE2_PARTIAL_SOFT  specifies  that  the caller is prepared to handle a partial match, but
       only if no complete match can be found.

       If PCRE2_PARTIAL_HARD is set, it overrides PCRE2_PARTIAL_SOFT. In this case, if a  partial
       match is found, pcre2_match() immediately returns PCRE2_ERROR_PARTIAL, without considering
       any other alternatives. In other words, when PCRE2_PARTIAL_HARD is set, a partial match is
       considered to be more important that an alternative complete match.

       There  is a more detailed discussion of partial and multi-segment matching, with examples,
       in the pcre2partial documentation.

NEWLINE HANDLING WHEN MATCHING


       When PCRE2 is built, a default newline convention is set; this  is  usually  the  standard
       convention for the operating system. The default can be overridden in a compile context by
       calling pcre2_set_newline(). It can also be overridden by starting a pattern string  with,
       for  example,  (*CRLF),  as  described  in  the  section  on  newline  conventions  in the
       pcre2pattern page. During matching, the newline choice affects the behaviour of  the  dot,
       circumflex,  and  dollar  metacharacters.  It  may  also  alter the way the match starting
       position is advanced after a match failure for an unanchored pattern.

       When PCRE2_NEWLINE_CRLF, PCRE2_NEWLINE_ANYCRLF, or PCRE2_NEWLINE_ANY is set as the newline
       convention,  and a match attempt for an unanchored pattern fails when the current starting
       position is at a CRLF sequence, and the pattern contains no explicit matches for CR or  LF
       characters,  the  match  position  is  advanced by two characters instead of one, in other
       words, to after the CRLF.

       The above rule is a compromise that makes the most common  cases  work  as  expected.  For
       example, if the pattern is .+A (and the PCRE2_DOTALL option is not set), it does not match
       the string "\r\nA" because, after failing at the start, it skips both the CR  and  the  LF
       before  retrying. However, the pattern [\r\n]A does match that string, because it contains
       an explicit CR or LF reference, and so advances only by  one  character  after  the  first
       failure.

       An  explicit  match for CR of LF is either a literal appearance of one of those characters
       in the pattern, or one of  the  \r  or  \n  or  equivalent  octal  or  hexadecimal  escape
       sequences.  Implicit  matches  such  as  [^X]  do  not  count, nor does \s, even though it
       includes CR and LF in the characters that it matches.

       Notwithstanding the above, anomalous effects may still occur when CRLF is a valid  newline
       sequence and explicit \r or \n escapes appear in the pattern.

HOW PCRE2_MATCH() RETURNS A STRING AND CAPTURED SUBSTRINGS


       uint32_t pcre2_get_ovector_count(pcre2_match_data *match_data);

       PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *match_data);

       In  general,  a pattern matches a certain portion of the subject, and in addition, further
       substrings from the subject may be picked out  by  parenthesized  parts  of  the  pattern.
       Following  the usage in Jeffrey Friedl's book, this is called "capturing" in what follows,
       and the phrase "capture group" (Perl terminology) is used for a fragment of a pattern that
       picks  out  a substring. PCRE2 supports several other kinds of parenthesized group that do
       not cause substrings to be captured. The pcre2_pattern_info() function can be used to find
       out how many capture groups there are in a compiled pattern.

       You can use auxiliary functions for accessing captured substrings by number or by name, as
       described in sections below.

       Alternatively, you can make direct use of the vector  of  PCRE2_SIZE  values,  called  the
       ovector,  which  contains  the  offsets  of captured strings. It is part of the match data
       block.  The function pcre2_get_ovector_pointer() returns the address of the  ovector,  and
       pcre2_get_ovector_count() returns the number of pairs of values it contains.

       Within  the  ovector,  the  first in each pair of values is set to the offset of the first
       code unit of a substring, and the second is set to the offset of the first code unit after
       the  end of a substring. These values are always code unit offsets, not character offsets.
       That is, they are byte offsets in the 8-bit library, 16-bit offsets in the 16-bit library,
       and 32-bit offsets in the 32-bit library.

       After  a  partial match (error return PCRE2_ERROR_PARTIAL), only the first pair of offsets
       (that is, ovector[0] and ovector[1]) are set. They identify the part of the  subject  that
       was partially matched. See the pcre2partial documentation for details of partial matching.

       After  a  fully  successful match, the first pair of offsets identifies the portion of the
       subject string that was matched by the entire pattern. The next pair is used for the first
       captured  substring,  and  so on. The value returned by pcre2_match() 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.

       If a pattern uses the \K escape sequence within a positive assertion, the  reported  start
       of  a  successful  match  can  be  greater than the end of the match.  For example, if the
       pattern (?=ab\K) is matched against "ab", the start and end offset values  for  the  match
       are 2 and 0.

       If  a  capture group is matched repeatedly within a single match operation, it is the last
       portion of the subject that it matched that is returned.

       If the ovector is too small to hold  all  the  captured  substring  offsets,  as  much  as
       possible  is  filled  in, and the function returns a value of zero. If captured substrings
       are not of interest, pcre2_match() may be called with a match data block whose ovector  is
       of minimum length (that is, one pair).

       It is possible for capture group number n+1 to match some part of the subject when group n
       has not been used at all. For example, if the string "abc" is matched against the  pattern
       (a|(z))(bc)  the  return  from the function is 4, and groups 1 and 3 are matched, but 2 is
       not. When this happens, both values in the offset pairs corresponding to unused groups are
       set to PCRE2_UNSET.

       Offset  values  that correspond to unused groups at the end of the expression are also set
       to PCRE2_UNSET.  For  example,  if  the  string  "abc"  is  matched  against  the  pattern
       (abc)(x(yz)?)?  groups 2 and 3 are not matched. The return from the function is 2, because
       the highest used capture group number is 1. The offsets  for  for  the  second  and  third
       capture groupss (assuming the vector is large enough, of course) are set to PCRE2_UNSET.

       Elements in the ovector that do not correspond to capturing parentheses in the pattern are
       never changed. That is, if a pattern  contains  n  capturing  parentheses,  no  more  than
       ovector[0]  to  ovector[2n+1] are set by pcre2_match(). The other elements retain whatever
       values they previously had. After a failed match attempt, the contents of the ovector  are
       unchanged.

OTHER INFORMATION ABOUT A MATCH


       PCRE2_SPTR pcre2_get_mark(pcre2_match_data *match_data);

       PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *match_data);

       As  well as the offsets in the ovector, other information about a match is retained in the
       match data block and can be retrieved by the above functions in appropriate circumstances.
       If they are called at other times, the result is undefined.

       After  a  successful  match,  a partial match (PCRE2_ERROR_PARTIAL), or a failure to match
       (PCRE2_ERROR_NOMATCH), a mark name may be available. The function pcre2_get_mark() can  be
       called  to  access  this  name,  which  can  be  specified  in  the  pattern by any of the
       backtracking control verbs, not just (*MARK). The same function applies to all the  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.

       After a successful match, the name that is returned is the last mark name  encountered  on
       the  matching  path  through the pattern. Instances of backtracking verbs without names do
       not count. Thus, for example, if the matching path 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:

         ^(*MARK:A)((*MARK:B)a|b)c

       When it matches "bc", the returned name is A. The B mark is "seen" in the first branch  of
       the  group, but it is not on the matching path. On the other hand, when this pattern fails
       to match "bx", the returned name is B.

       Warning: By default, certain start-of-match optimizations are used  to  give  a  fast  "no
       match"  result  in  some  situations.  For  example,  if the anchoring is removed from the
       pattern above, there is an initial check for the presence 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  pcre2_compile()  or  by  starting  the  pattern with
       (*NO_START_OPT).

       After a successful match, a partial match, or one of the invalid UTF errors (for  example,
       PCRE2_ERROR_UTF8_ERR5), pcre2_get_startchar() can be called. After a successful or partial
       match it returns the code unit offset of the character at which the match started.  For  a
       non-partial  match,  this  can  be  different  to  the  value of ovector[0] if the pattern
       contains the \K escape sequence. After a partial match, however, this value is always  the
       same as ovector[0] because \K does not affect the result of a partial match.

       After  a  UTF  check  failure,  pcre2_get_startchar()  can be used to obtain the code unit
       offset of the invalid UTF character. Details are given in the pcre2unicode page.

ERROR RETURNS FROM pcre2_match()


       If pcre2_match() fails, it returns a negative number. This can  be  converted  to  a  text
       string  by  calling the pcre2_get_error_message() function (see "Obtaining a textual error
       message" 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 pcre2unicode page. The
       following are the other errors that may be returned by pcre2_match():

         PCRE2_ERROR_NOMATCH

       The subject string did not match the pattern.

         PCRE2_ERROR_PARTIAL

       The subject string did not match,  but  it  did  match  partially.  See  the  pcre2partial
       documentation for details of partial matching.

         PCRE2_ERROR_BADMAGIC

       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.

         PCRE2_ERROR_BADMODE

       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.

         PCRE2_ERROR_BADOFFSET

       The value of startoffset was greater than the length of the subject.

         PCRE2_ERROR_BADOPTION

       An unrecognized bit was set in the options argument.

         PCRE2_ERROR_BADUTFOFFSET

       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 startoffset did not point to
       the beginning of a UTF character or the end of the subject.

         PCRE2_ERROR_CALLOUT

       This  error  is never generated by pcre2_match() itself. It is provided for use by callout
       functions that want to  cause  pcre2_match()  or  pcre2_callout_enumerate()  to  return  a
       distinctive error code. See the pcre2callout documentation for details.

         PCRE2_ERROR_DEPTHLIMIT

       The nested backtracking depth limit was reached.

         PCRE2_ERROR_HEAPLIMIT

       The heap limit was reached.

         PCRE2_ERROR_INTERNAL

       An unexpected internal error has occurred. This error could be caused by a bug in PCRE2 or
       by overwriting of the compiled pattern.

         PCRE2_ERROR_JIT_STACKLIMIT

       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 pcre2jit documentation for more details.

         PCRE2_ERROR_MATCHLIMIT

       The backtracking match limit was reached.

         PCRE2_ERROR_NOMEMORY

       Heap memory is used to remember backgracking points. This error is given when  the  memory
       allocation   function   (default   or   custom)   fails.  Note  that  a  different  error,
       PCRE2_ERROR_HEAPLIMIT, is given if the amount of memory needed  exceeds  the  heap  limit.
       PCRE2_ERROR_NOMEMORY  is  also  returned  if  PCRE2_COPY_MATCHED_SUBJECT is set and memory
       allocation fails.

         PCRE2_ERROR_NULL

       Either the code, subject, or match_data argument was passed as NULL.

         PCRE2_ERROR_RECURSELOOP

       This error is returned when pcre2_match() detects a recursion  loop  within  the  pattern.
       Specifically,  it  means  that either the whole pattern or a capture group 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 groups,  cannot  be  detected
       until matching is attempted.

OBTAINING A TEXTUAL ERROR MESSAGE


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

       A  text  message  for an error code from any PCRE2 function (compile, match, or auxiliary)
       can be obtained by calling pcre2_get_error_message(). The code  is  passed  as  the  first
       argument, with the remaining two arguments specifying a code unit buffer and its length in
       code units, into which the text message is placed. The message is returned in  code  units
       of the appropriate width for the library that is being used.

       The  returned  message  is  terminated  with a trailing zero, and the function returns the
       number of code units used, excluding the trailing zero. If the error  number  is  unknown,
       the  negative  error code PCRE2_ERROR_BADDATA is returned. If the buffer is too small, the
       message is truncated (but still with  a  trailing  zero),  and  the  negative  error  code
       PCRE2_ERROR_NOMEMORY  is  returned.   None of the messages are very long; a buffer size of
       120 code units is ample.

EXTRACTING CAPTURED SUBSTRINGS BY NUMBER


       int pcre2_substring_length_bynumber(pcre2_match_data *match_data,
         uint32_t number, PCRE2_SIZE *length);

       int pcre2_substring_copy_bynumber(pcre2_match_data *match_data,
         uint32_t number, PCRE2_UCHAR *buffer,
         PCRE2_SIZE *bufflen);

       int pcre2_substring_get_bynumber(pcre2_match_data *match_data,
         uint32_t number, PCRE2_UCHAR **bufferptr,
         PCRE2_SIZE *bufflen);

       void pcre2_substring_free(PCRE2_UCHAR *buffer);

       Captured substrings can be accessed directly by using the ovector as described above.  For
       convenience,  auxiliary  functions are provided for extracting captured substrings as new,
       separate, zero-terminated strings. A substring that contains a binary  zero  is  correctly
       extracted  and  has a further zero added on the end, but the result is not, of course, a C
       string.

       The functions in this section identify substrings by number. The number zero refers to the
       entire  matched  substring,  with  higher  numbers  referring  to  substrings  captured by
       parenthesized groups. After a partial match, only substring zero is available. An  attempt
       to  extract  any  other  substring  gives  the error PCRE2_ERROR_PARTIAL. The next section
       describes similar functions for extracting captured substrings by name.

       If a pattern uses the \K escape sequence within a positive assertion, the  reported  start
       of  a  successful  match  can  be  greater than the end of the match.  For example, if the
       pattern (?=ab\K) is matched against "ab", the start and end offset values  for  the  match
       are  2  and  0.  In  this  situation, calling these functions with a zero substring number
       extracts a zero-length empty string.

       You can find the length in code units of a captured substring  without  extracting  it  by
       calling  pcre2_substring_length_bynumber().  The  first argument is a pointer to the match
       data block, the second is the group number, and the third is a pointer to a variable  into
       which the length is placed. If you just want to know whether or not the substring has been
       captured, you can pass the third argument as NULL.

       The pcre2_substring_copy_bynumber() function copies a captured substring into  a  supplied
       buffer,  whereas  pcre2_substring_get_bynumber() copies it into new memory, obtained using
       the same memory allocation function that was used for the match data block. The first  two
       arguments  of  these  functions  are a pointer to the match data block and a capture group
       number.

       The final arguments of pcre2_substring_copy_bynumber() are a pointer to the buffer  and  a
       pointer  to a variable that contains its length in code units.  This is updated to contain
       the actual  number  of  code  units  used  for  the  extracted  substring,  excluding  the
       terminating zero.

       For  pcre2_substring_get_bynumber() the third and fourth arguments point to variables that
       are updated with a pointer to the new memory and the number of code  units  that  comprise
       the  substring,  again  excluding  the  terminating  zero. When the substring is no longer
       needed, the memory should be freed by calling pcre2_substring_free().

       The return value from all these functions is zero for success, or a negative  error  code.
       If  the  pattern  match failed, the match failure code is returned.  If a substring number
       greater than zero is used after a partial match, PCRE2_ERROR_PARTIAL  is  returned.  Other
       possible error codes are:

         PCRE2_ERROR_NOMEMORY

       The buffer was too small for pcre2_substring_copy_bynumber(), or the attempt to get memory
       failed for pcre2_substring_get_bynumber().

         PCRE2_ERROR_NOSUBSTRING

       There is no substring with that number in the pattern, that is, the number is greater than
       the number of capturing parentheses.

         PCRE2_ERROR_UNAVAILABLE

       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.

         PCRE2_ERROR_UNSET

       The substring did not participate in the match. For example, if the pattern is (abc)|(def)
       and the subject is "def", and the ovector contains at least two capturing slots, substring
       number 1 is unset.

EXTRACTING A LIST OF ALL CAPTURED SUBSTRINGS


       int pcre2_substring_list_get(pcre2_match_data *match_data,
         PCRE2_UCHAR ***listptr, PCRE2_SIZE **lengthsptr);

       void pcre2_substring_list_free(PCRE2_SPTR *list);

       The pcre2_substring_list_get() function extracts all available  substrings  and  builds  a
       list  of  pointers  to them. It also (optionally) builds a second list that contains their
       lengths (in code units), excluding a terminating zero that is added to each of  them.  All
       this is done in a single block of memory that is obtained using the same memory allocation
       function that was used to get the match data block.

       This function must be called only after a successful match.  If  called  after  a  partial
       match, the error code PCRE2_ERROR_PARTIAL is returned.

       The  address  of  the memory block is returned via listptr, which is also the start of the
       list of string pointers. The end of the list is marked by a NULL pointer. The  address  of
       the  list  of  lengths  is  returned via lengthsptr. If your strings do not contain binary
       zeros and you do not therefore need the lengths, you may supply  NULL  as  the  lengthsptr
       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 pcre2_substring_list_free().

       If this function encounters a substring that is unset, which can happen when capture group
       number n+1 matches some part of the subject, but group n has not  been  used  at  all,  it
       returns an empty string. This can be distinguished from a genuine zero-length substring by
       inspecting the appropriate offset in the ovector,  which  contain  PCRE2_UNSET  for  unset
       substrings, or by calling pcre2_substring_length_bynumber().

EXTRACTING CAPTURED SUBSTRINGS BY NAME


       int pcre2_substring_number_from_name(const pcre2_code *code,
         PCRE2_SPTR name);

       int pcre2_substring_length_byname(pcre2_match_data *match_data,
         PCRE2_SPTR name, PCRE2_SIZE *length);

       int pcre2_substring_copy_byname(pcre2_match_data *match_data,
         PCRE2_SPTR name, PCRE2_UCHAR *buffer, PCRE2_SIZE *bufflen);

       int pcre2_substring_get_byname(pcre2_match_data *match_data,
         PCRE2_SPTR name, PCRE2_UCHAR **bufferptr, PCRE2_SIZE *bufflen);

       void pcre2_substring_free(PCRE2_UCHAR *buffer);

       To  extract  a  substring by name, you first have to find associated number.  For example,
       for this pattern:

         (a+)b(?<xxx>\d+)...

       the number of the capture group 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
       pcre2_substring_number_from_name(). The first argument is the compiled  pattern,  and  the
       second is the name. The yield of the function is the group number, PCRE2_ERROR_NOSUBSTRING
       if there is no group with that name, or PCRE2_ERROR_NOUNIQUESUBSTRING  if  there  is  more
       than  one  group with that name.  Given the number, you can extract the substring directly
       from the ovector, or use one of the "bynumber" functions described above.

       For convenience, there are also "byname"  functions  that  correspond  to  the  "bynumber"
       functions,  the  only  difference  being  that  the second argument is a name instead of a
       number. If PCRE2_DUPNAMES is set and there are duplicate names, these functions  scan  all
       the  groups  with  the  given name, and return the captured substring from the first named
       group that is set.

       If there are no groups with the given name, PCRE2_ERROR_NOSUBSTRING is  returned.  If  all
       groups  with  the  name  have  numbers  that  are  greater than the number of slots in the
       ovector, PCRE2_ERROR_UNAVAILABLE is returned. If there is at least one group with  a  slot
       in the ovector, but no group is found to be set, PCRE2_ERROR_UNSET is returned.

       Warning:  If  the  pattern uses the (?| feature to set up multiple capture groups with the
       same number, as described in the section on duplicate group numbers  in  the  pcre2pattern
       page,  you cannot use names to distinguish the different capture groups, because names are
       not included in the compiled code. The  matching  process  uses  only  numbers.  For  this
       reason,  the  use  of  different  names for groups with the same number causes an error at
       compile time.

CREATING A NEW STRING WITH SUBSTITUTIONS


       int pcre2_substitute(const pcre2_code *code, PCRE2_SPTR subject,
         PCRE2_SIZE length, PCRE2_SIZE startoffset,
         uint32_t options, pcre2_match_data *match_data,
         pcre2_match_context *mcontext, PCRE2_SPTR replacement,
         PCRE2_SIZE rlength, PCRE2_UCHAR *outputbuffer,
         PCRE2_SIZE *outlengthptr);

       This function optionally calls pcre2_match() and then makes a copy of the  subject  string
       in  outputbuffer,  replacing  parts  that  were matched with the replacement string, whose
       length is supplied in rlength, which can be given as  PCRE2_ZERO_TERMINATED  for  a  zero-
       terminated  string.  As  a  special  case, if replacement is NULL and rlength is zero, the
       replacement is assumed to be an empty string. If rlength is non-zero, an error  occurs  if
       replacement is NULL.

       There  is  an  option  (see  PCRE2_SUBSTITUTE_REPLACEMENT_ONLY  below)  to return just the
       replacement string(s). The default action is  to  perform  just  one  replacement  if  the
       pattern  matches,  but  there  is  an  option  that  requests  multiple  replacements (see
       PCRE2_SUBSTITUTE_GLOBAL below).

       If successful, pcre2_substitute() returns the number of substitutions  that  were  carried
       out.  This  may  be  zero  if  no  match  was  found, and is never greater than one unless
       PCRE2_SUBSTITUTE_GLOBAL is set. A negative value is returned if an error is detected.

       Matches in which a \K item in a lookahead in the pattern causes the match to end before it
       starts  are  not  supported,  and  give  rise to an error return. For global replacements,
       matches in which \K in a lookbehind causes the match to start earlier than the point  that
       was reached in the previous iteration are also not supported.

       The  first seven arguments of pcre2_substitute() are the same as for pcre2_match(), except
       that the partial matching options are not permitted, and match_data may be passed as NULL,
       in  which case a match data block is obtained and freed within this function, using memory
       management functions from the match context, if provided, or else those that were used  to
       allocate memory for the compiled code.

       If  match_data  is not NULL and PCRE2_SUBSTITUTE_MATCHED is not set, the provided block is
       used for all calls to pcre2_match(), and its contents afterwards are  the  result  of  the
       final  call. For global changes, this will always be a no-match error. The contents of the
       ovector within the match data block may or may not have been changed.

       As well as the usual options for pcre2_match(), a number of additional options can be  set
       in    the    options    argument    of    pcre2_substitute().     One   such   option   is
       PCRE2_SUBSTITUTE_MATCHED. When this is set, an external match_data block must be provided,
       and  it  must  have  already been used for an external call to pcre2_match() with the same
       pattern and subject arguments. The data in  the  match_data  block  (return  code,  offset
       vector)  is  then  used  for  the first substitution instead of calling pcre2_match() from
       within pcre2_substitute(). This allows an application to check for a match before choosing
       to substitute, without having to repeat the match.

       The   contents  of  the  externally  supplied  match  data  block  are  not  changed  when
       PCRE2_SUBSTITUTE_MATCHED is set. If PCRE2_SUBSTITUTE_GLOBAL is also set, pcre2_match()  is
       called  after  the first substitution to check for further matches, but this is done using
       an internally obtained match data block, thus always leaving the external block unchanged.

       The  code  argument  is  not  used  for  matching  before  the  first  substitution   when
       PCRE2_SUBSTITUTE_MATCHED    is    set,    but    it    must   be   provided,   even   when
       PCRE2_SUBSTITUTE_GLOBAL is not set, because  it  contains  information  such  as  the  UTF
       setting and the number of capturing parentheses in the pattern.

       The  default  action  of pcre2_substitute() is to return a copy of the subject string with
       matched substrings replaced. However, if PCRE2_SUBSTITUTE_REPLACEMENT_ONLY  is  set,  only
       the  replacement  substrings  are  returned. In the global case, multiple replacements are
       concatenated in the output buffer. Substitution  callouts  (see  below)  can  be  used  to
       separate them if necessary.

       The outlengthptr argument of pcre2_substitute() must point to a variable that contains the
       length, in code units, of the output buffer. If the function is successful, the  value  is
       updated to contain the length in code units of the new string, excluding the trailing zero
       that is automatically added.

       If the function is not successful, the value set via outlengthptr depends on the  type  of
       error.  For  syntax  errors  in  the  replacement  string,  the value is the offset in the
       replacement string  where  the  error  was  detected.  For  other  errors,  the  value  is
       PCRE2_UNSET  by  default.  This  includes  the  case of the output buffer being too small,
       unless PCRE2_SUBSTITUTE_OVERFLOW_LENGTH is set.

       PCRE2_SUBSTITUTE_OVERFLOW_LENGTH changes what happens when the output buffer is too small.
       The  default  action is to return PCRE2_ERROR_NOMEMORY immediately. If this option is set,
       however,  pcre2_substitute()  continues  to  go  through  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 outlengthptr variable, with  the  result
       of the function still being PCRE2_ERROR_NOMEMORY.

       Passing  a buffer size of zero is a permitted way of finding out how much memory is needed
       for given substitution. However, this does mean that the entire operation is  carried  out
       twice.  Depending  on the application, it may be more efficient to allocate a large buffer
       and free the excess afterwards, instead of using PCRE2_SUBSTITUTE_OVERFLOW_LENGTH.

       The replacement string, which is interpreted as a UTF string in UTF mode, is  checked  for
       UTF validity unless PCRE2_NO_UTF_CHECK is set. An invalid UTF replacement string causes an
       immediate return with the relevant UTF error code.

       If PCRE2_SUBSTITUTE_LITERAL is set, the replacement string is not interpreted in any  way.
       By  default,  however,  a  dollar  character  is  an escape character that can specify the
       insertion of characters from capture groups and names from (*MARK) or other control  verbs
       in the pattern. The following forms are always recognized:

         $$                  insert a dollar character
         $<n> or ${<n>}      insert the contents of group <n>
         $*MARK or ${*MARK}  insert a control verb name

       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+=".

       $*MARK  inserts  the  name  from  the  last  encountered  backtracking control verb on the
       matching path that has a name. (*MARK) must always include a name,  but  the  other  verbs
       need  not. For example, in the case of (*MARK:A)(*PRUNE) the name 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 pcre2test example shows:

         /(*MARK:pear)apple|(*MARK:orange)lemon/g,replace=${*MARK}
             apple lemon
          2: pear orange

       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
       startoffset value for each search, which is always passed the entire subject string. If an
       offset limit is set in the match context, searching stops when that limit is reached.

       You can restrict the effect of a global substitution to a portion of the subject string by
       setting either or both of startoffset and an offset limit. Here is a pcre2test example:

         /B/g,replace=!,use_offset_limit
         ABC ABC ABC ABC\=offset=3,offset_limit=12
          2: ABC A!C A!C ABC

       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.

       PCRE2_SUBSTITUTE_UNKNOWN_UNSET  causes  references to capture groups that do not appear in
       the pattern to be treated as unset groups. This option should be used with  care,  because
       it   means   that   a   typo   in   a   group   name   or  number  no  longer  causes  the
       PCRE2_ERROR_NOSUBSTRING error.

       PCRE2_SUBSTITUTE_UNSET_EMPTY causes unset capture groups (including  unknown  groups  when
       PCRE2_SUBSTITUTE_UNKNOWN_UNSET  is  set)  to  be treated as empty strings when inserted as
       described above. If this option is not set, an attempt to insert an unset group causes the
       PCRE2_ERROR_UNSET  error.  This option does not influence the extended substitution syntax
       described below.

       PCRE2_SUBSTITUTE_EXTENDED causes extra processing to be applied to the replacement string.
       Without  this  option,  only the dollar character is special, and only the group insertion
       forms listed above are valid. When PCRE2_SUBSTITUTE_EXTENDED is set, two things change:

       Firstly, backslash in a replacement string is interpreted  as  an  escape  character.  The
       usual  forms  such as \n or \x{ddd} can be used to specify particular character codes, and
       backslash followed by any  non-alphanumeric  character  quotes  that  character.  Extended
       quoting can be coded using \Q...\E, exactly as in pattern strings.

       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: \U and \L change to upper or lower
       case forcing, respectively, and \E (when not terminating a \Q quoted sequence) reverts  to
       no  case  forcing. The sequences \u and \l force the next character (if it is a letter) to
       upper or lower case, respectively, and then the state automatically  reverts  to  no  case
       forcing.  Case  forcing  applies  to all inserted characters, including those from capture
       groups and letters within \Q...\E quoted sequences. If either PCRE2_UTF or  PCRE2_UCP  was
       set when the pattern was compiled, Unicode properties are used for case forcing characters
       whose code points are greater than 127.

       Note that case forcing sequences such as \U...\E do not nest. For example, the  result  of
       processing  "\Uaa\LBB\Ecc\E"  is  "AAbbcc"; the final \E has no effect. Note also that the
       PCRE2_ALT_BSUX and PCRE2_EXTRA_ALT_BSUX options do not apply to replacement strings.

       The second effect of setting PCRE2_SUBSTITUTE_EXTENDED  is  to  add  more  flexibility  to
       capture group substitution. The syntax is similar to that used by Bash:

         ${<n>:-<string>}
         ${<n>:+<string1>:<string2>}

       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

         ${<n>:+${<n>}:<string>}

       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 pcre2test example:

         /(some)?(body)/substitute_extended,replace=${1:+\U:\L}HeLLo
             body
          1: hello
             somebody
          1: HELLO

       The PCRE2_SUBSTITUTE_UNSET_EMPTY option does  not  affect  these  extended  substitutions.
       However,  PCRE2_SUBSTITUTE_UNKNOWN_UNSET  does cause unknown groups in the extended syntax
       forms to be treated as unset.

       If      PCRE2_SUBSTITUTE_LITERAL       is       set,       PCRE2_SUBSTITUTE_UNKNOWN_UNSET,
       PCRE2_SUBSTITUTE_UNSET_EMPTY,   and   PCRE2_SUBSTITUTE_EXTENDED  are  irrelevant  and  are
       ignored.

   Substitution errors

       In the event of an error, pcre2_substitute() returns a negative  error  code.  Except  for
       PCRE2_ERROR_NOMATCH  (which  is  never  returned),  errors  from  pcre2_match() are passed
       straight back.

       PCRE2_ERROR_NOSUBSTRING  is  returned  for  a  non-existent  substring  insertion,  unless
       PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set.

       PCRE2_ERROR_UNSET  is  returned  for  an  unset  substring insertion (including an unknown
       substring when PCRE2_SUBSTITUTE_UNKNOWN_UNSET  is  set)  when  the  simple  (non-extended)
       syntax is used and PCRE2_SUBSTITUTE_UNSET_EMPTY is not set.

       PCRE2_ERROR_NOMEMORY  is  returned  if  the  output  buffer  is  not  big  enough.  If the
       PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option is set, the size  of  buffer  that  is  needed  is
       returned via outlengthptr. Note that this does not happen by default.

       PCRE2_ERROR_NULL  is  returned  if  PCRE2_SUBSTITUTE_MATCHED  is  set  but  the match_data
       argument is NULL or if the  subject  or  replacement  arguments  are  NULL.  For  backward
       compatibility  reasons  an  exception  is made for the replacement argument if the rlength
       argument is also 0.

       PCRE2_ERROR_BADREPLACEMENT is used for miscellaneous  syntax  errors  in  the  replacement
       string,  with  more  particular  errors  being  PCRE2_ERROR_BADREPESCAPE  (invalid  escape
       sequence),   PCRE2_ERROR_REPMISSINGBRACE    (closing    curly    bracket    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 \K is used in an
       assertion).

       As for all PCRE2 errors, a text message that  describes  the  error  can  be  obtained  by
       calling  the  pcre2_get_error_message()  function (see "Obtaining a textual error message"
       above).

   Substitution callouts

       int pcre2_set_substitute_callout(pcre2_match_context *mcontext,
         int (*callout_function)(pcre2_substitute_callout_block *, void *),
         void *callout_data);

       The pcre2_set_substitution_callout() function can be used to specify  a  callout  function
       for  pcre2_substitute().  This  information  is  passed  in  a  match context. The callout
       function is called after each substitution has  been  processed,  but  it  can  cause  the
       replacement  not to happen. The callout function is not called for simulated substitutions
       that happen as a result of the PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option.

       The first argument of the callout function is a pointer  to  a  substitute  callout  block
       structure, which contains the following fields, not necessarily in this order:

         uint32_t    version;
         uint32_t    subscount;
         PCRE2_SPTR  input;
         PCRE2_SPTR  output;
         PCRE2_SIZE *ovector;
         uint32_t    oveccount;
         PCRE2_SIZE  output_offsets[2];

       The  version field contains the version number of the block format. The current version is
       0. The version number will increase in future if more fields are added, but the  intention
       is never to remove any of the existing fields.

       The  subscount  field is the number of the current match. It is 1 for the first callout, 2
       for the second, and so on. The input and output pointers are copies of the  values  passed
       to pcre2_substitute().

       The  ovector  field  points  to  the ovector, which contains the result of the most recent
       match. The oveccount field contains the number of pairs that are set in the  ovector,  and
       is always greater than zero.

       The  output_offsets  vector  contains the offsets of the replacement in the output string.
       This has already been processed for dollar and (if requested) backslash  substitutions  as
       described above.

       The  second  argument of the callout function is the value passed as callout_data when the
       function was registered. The value returned by the  callout  function  is  interpreted  as
       follows:

       If the value is zero, the replacement is accepted, and, if PCRE2_SUBSTITUTE_GLOBAL is set,
       processing continues with a search for the next match. If  the  value  is  not  zero,  the
       current  replacement  is  not  accepted.  If  the  value  is greater than zero, processing
       continues when PCRE2_SUBSTITUTE_GLOBAL is set. Otherwise (the value is less than  zero  or
       PCRE2_SUBSTITUTE_GLOBAL is not set), the the rest of the input is copied to the output and
       the call to pcre2_substitute() exits, returning the number of matches so far.

DUPLICATE CAPTURE GROUP NAMES


       int pcre2_substring_nametable_scan(const pcre2_code *code,
         PCRE2_SPTR name, PCRE2_SPTR *first, PCRE2_SPTR *last);

       When a pattern is compiled with the PCRE2_DUPNAMES option, names for  capture  groups  are
       not  required  to  be  unique. Duplicate names are always allowed for groups with the same
       number, created by using the (?| feature. Indeed, if  such  groups  are  named,  they  are
       required to use the same names.

       Normally,  patterns  that  use duplicate names are such that in any one match, only one of
       each set of identically-named groups participates. An example is shown in the pcre2pattern
       documentation.

       When       duplicates       are       present,      pcre2_substring_copy_byname()      and
       pcre2_substring_get_byname() return the first substring corresponding to  the  given  name
       that   is   set.   Only   if   none   are   set  is  PCRE2_ERROR_UNSET  is  returned.  The
       pcre2_substring_number_from_name()        function        returns        the         error
       PCRE2_ERROR_NOUNIQUESUBSTRING when there are duplicate names.

       If  you want to get full details of all captured substrings for a given name, you must use
       the pcre2_substring_nametable_scan() function. The first argument is the compiled pattern,
       and  the  second  is  the  name.  If the third and fourth arguments are NULL, the function
       returns a group number for a unique name, or PCRE2_ERROR_NOUNIQUESUBSTRING otherwise.

       When the third and fourth arguments are not NULL, they must be pointers to variables  that
       are updated by the function. After it has run, they point to the first and last entries in
       the name-to-number table for the given name, and the function returns the length  of  each
       entry  in  code  units. In both cases, PCRE2_ERROR_NOSUBSTRING is returned if there are no
       entries for the given name.

       The format of the name table is described above in the section entitled Information  about
       a  pattern.  Given  all  the  relevant entries for the name, you can extract each of their
       numbers, and hence the captured data.

FINDING ALL POSSIBLE MATCHES AT ONE POSITION


       The traditional matching function uses a similar algorithm to Perl, which  stops  when  it
       finds  the  first  match at a given point in the subject. If you want to find all possible
       matches, or the longest possible match at a given position, 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 pcre2callout
       documentation.

       What  you  have  to  do is to insert a callout right at the end of the pattern.  When your
       callout function is called, extract and save the current matched substring. Then return 1,
       which  forces  pcre2_match()  to backtrack and try other alternatives. Ultimately, when it
       runs out of matches, pcre2_match() will yield PCRE2_ERROR_NOMATCH.

MATCHING A PATTERN: THE ALTERNATIVE FUNCTION


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

       The function pcre2_dfa_match() is called to match a  subject  string  against  a  compiled
       pattern,  using a matching algorithm that scans the subject string just once (not counting
       lookaround  assertions),  and  does  not  backtrack  (except  when  processing  lookaround
       assertions).  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  pcre2_dfa_match()  does  not
       support, see the pcre2matching documentation.

       The  arguments  for the pcre2_dfa_match() function are the same as for pcre2_match(), plus
       two extras. The ovector within the match data block is used in a different way,  and  this
       is  described  below.  The  other  common  arguments  are  used  in  the  same  way as for
       pcre2_match(), so their description is not repeated here.

       The two additional arguments provide workspace for  the  function.  The  workspace  vector
       should  contain  at  least  20  elements.  It  is used for keeping track of multiple paths
       through the pattern tree. More workspace is needed for patterns and subjects  where  there
       are a lot of potential matches.

       Here is an example of a simple call to pcre2_dfa_match():

         int wspace[20];
         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) */

   Option bits for pcre2_dfa_match()

       The  unused bits of the options argument for pcre2_dfa_match() must be zero. The only bits
       that  may  be  set  are  PCRE2_ANCHORED,  PCRE2_COPY_MATCHED_SUBJECT,   PCRE2_ENDANCHORED,
       PCRE2_NOTBOL,  PCRE2_NOTEOL,  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 pcre2_match(), so their description is
       not repeated here.

         PCRE2_PARTIAL_HARD
         PCRE2_PARTIAL_SOFT

       These have the same general effect as they do  for  pcre2_match(),  but  the  details  are
       slightly  different.  When  PCRE2_PARTIAL_HARD  is  set  for pcre2_dfa_match(), 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 pcre2partial
       documentation.

         PCRE2_DFA_SHORTEST

       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.

         PCRE2_DFA_RESTART

       When  pcre2_dfa_match()  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 workspace and wscount
       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
       pcre2partial documentation.

   Successful returns from pcre2_dfa_match()

       When pcre2_dfa_match() succeeds, it may have  matched  more  than  one  substring  in  the
       subject.  Note,  however,  that  all the matches from one run of the function start at the
       same point in the subject. The shorter matches are all initial substrings  of  the  longer
       matches. For example, if the pattern

         <.*>

       is matched against the string

         This is <something> <something else> <something further> no more

       the three matched strings are

         <something> <something else> <something further>
         <something> <something else>
         <something>

       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 pcre2_match(), but the numbers bear no
       relation to any capture groups that may exist in the pattern, because  DFA  matching  does
       not support capturing.

       Calls  to  the  convenience  functions  that  extract  substrings by name return the error
       PCRE2_ERROR_DFA_UFUNC (unsupported function) if used after a DFA  match.  The  convenience
       functions that extract substrings by number never return PCRE2_ERROR_NOSUBSTRING.

       The  matched  strings  are  stored in the ovector in reverse order of length; that is, the
       longest matching string is first. If there were too many matches to fit into the  ovector,
       the yield of the function is zero, and the vector is filled with the longest matches.

       NOTE: PCRE2's "auto-possessification" optimization usually applies to character repeats at
       the end of a pattern (as well as internally). For example, the pattern "a\d+" is  compiled
       as if it were "a\d++". For DFA matching, this means that only one possible match is found.
       If you really do want multiple matches in such cases, either use an ungreedy  repeat  such
       as "a\d+?" or set the PCRE2_NO_AUTO_POSSESS option when compiling.

   Error returns from pcre2_dfa_match()

       The  pcre2_dfa_match()  function  returns  a  negative  number when it fails.  Many of the
       errors are the same as for pcre2_match(), as described above.  There are in  addition  the
       following errors that are specific to pcre2_dfa_match():

         PCRE2_ERROR_DFA_UITEM

       This  return  is given if pcre2_dfa_match() encounters an item in the pattern that it does
       not support, for instance, the use of \C in a UTF mode or a backreference.

         PCRE2_ERROR_DFA_UCOND

       This return is given  if  pcre2_dfa_match()  encounters  a  condition  item  that  uses  a
       backreference  for  the  condition,  or  a test for recursion in a specific capture group.
       These are not supported.

         PCRE2_ERROR_DFA_UINVALID_UTF

       This return is given if pcre2_dfa_match() is called for a pattern that was  compiled  with
       PCRE2_MATCH_INVALID_UTF. This is not supported for DFA matching.

         PCRE2_ERROR_DFA_WSSIZE

       This return is given if pcre2_dfa_match() runs out of space in the workspace vector.

         PCRE2_ERROR_DFA_RECURSE

       When  a  recursion  or  subroutine  call  is processed, the matching function calls itself
       recursively, using private memory for the ovector and workspace.  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.

         PCRE2_ERROR_DFA_BADRESTART

       When pcre2_dfa_match() is called with  the  PCRE2_DFA_RESTART  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.

SEE ALSO


       pcre2build(3),   pcre2callout(3),   pcre2demo(3),    pcre2matching(3),    pcre2partial(3),
       pcre2posix(3), pcre2sample(3), pcre2unicode(3).

AUTHOR


       Philip Hazel
       Retired from University Computing Service
       Cambridge, England.

REVISION


       Last updated: 27 July 2022
       Copyright (c) 1997-2022 University of Cambridge.