pcre2api

PCRE2API(3)                Library Functions Manual                PCRE2API(3)

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 docu-
       ment 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 simul-
       taneously. On Unix-like systems the libraries  are  called  libpcre2-8,
       libpcre2-16, and libpcre2-32, and they can also co-exist with the orig-
       inal 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_com-
       pile() and  PCRE2_SPTR.  These  macros  use  the  value  of  the  macro
       PCRE2_CODE_UNIT_WIDTH  to generate the appropriate width-specific func-
       tion 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 pat-
       tern 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 corre-
       spond  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 compli-
       cated  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-com-
       patible, 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  algo-
       rithms   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 pro-
       vided, to free memory used for extracted strings. If  either  of  these
       functions  is called with a NULL argument, the function returns immedi-
       ately 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 com-
       piled 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  (line-
       feed) character, the two-character sequence CRLF, any of the three pre-
       ceding, 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  advance-
       ment 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  appli-
       cations can use it.

       There are several different blocks of data that are used to pass infor-
       mation 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:  Sev-
       eral  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 immedi-
       ately  (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  com-
       piler.

   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 val-
       ues 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 addi-
       tional 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  func-
       tions  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 func-
       tion 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 man-
       agement.  If none of these apply, just pass NULL as the  context  argu-
       ment of pcre2_compile().

       A  compile context is created, copied, and freed by the following func-
       tions:

       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 char-
       acter 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  avail-
       able  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 func-
       tion 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  effec-
       tively unlimited.

       int pcre2_set_newline(pcre2_compile_context *ccontext,
         uint32_t value);

       This specifies which characters or character sequences are to be recog-
       nized 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 recogni-
       tion  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  com-
       piled.  The limit applies to parentheses of all kinds, not just captur-
       ing 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  argu-
       ment   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 func-
       tions:

       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 doc-
       umentation.

       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  substitu-
       tion made by pcre2_substitute(). Details are given in the section enti-
       tled "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, differ-
       ent  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  gener-
       ated.

       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, which-
       ever 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 process-
       ing  patterns  with a lot of nested pattern recursion or lookarounds or
       atomic groups. This limit does not apply to matching with the JIT opti-
       mization,  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 starts out using a 20KiB vector on the  sys-
       tem stack for recording backtracking points. The more nested backtrack-
       ing points there are (that is, the deeper the search  tree),  the  more
       memory  is  needed.   Heap memory is used only if the initial vector is
       too small. If the heap limit is set to a value less than 21 (in partic-
       ular,  zero)  no  heap memory will be used. In this case, only patterns
       that do not have a lot of nested backtracking can be successfully  pro-
       cessed.

       Similarly,  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, too,
       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  pro-
       cessed 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_BADOP-
       TION  if the value in the first argument is not recognized. The follow-
       ing 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  sup-
       port, 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(). Fur-
       ther 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  nest-
       ing 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 out-
       put 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 char-
       acter 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 termi-
       nating 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 com-
       piled 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 match-
       ing,  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 com-
       piled 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  automati-
       cally  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  pat-
       tern,  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 com-
       pile context (as described above).

       If errorcode or erroroffset is NULL, pcre2_compile() returns NULL imme-
       diately.  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. The values are not defined when compilation is suc-
       cessful and pcre2_compile() returns a non-NULL value.

       There  are  nearly  100  positive  error codes that pcre2_compile() may
       return if it finds an error in the pattern. There are also  some  nega-
       tive  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 mes-
       sage"  below)  should  be  self-explanatory.  Macro names starting with
       PCRE2_ERROR_ are defined for both positive and negative error codes  in
       pcre2.h.

       The value returned in erroroffset is an indication of where in the pat-
       tern the error occurred. It is not necessarily the  furthest  point  in
       the  pattern  that  was  read. For example, after the error "lookbehind
       assertion is not fixed length", the error offset points to the start of
       the  failing assertion. For an invalid UTF-8 or UTF-16 string, the off-
       set 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 char-
       acter.

       This code fragment shows a typical straightforward call  to  pcre2_com-
       pile():

         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 com-
       pile 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 termi-
       nating 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 immedi-
       ately before or after an explicit callout in the pattern.  For  discus-
       sion 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 equiv-
       alents, 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 sub-
       ject 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 neg-
       ative 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.  How-
       ever, 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  obvi-
       ously 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.  How-
       ever,  white  space  is  not  allowed within sequences such as (?> that
       introduce various parenthesized groups, nor  within  numerical  quanti-
       fiers 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 set-
       ting.

       When  PCRE2  is compiled without Unicode support, PCRE2_EXTENDED recog-
       nizes as white space only those characters with code points  less  than
       256 that are flagged as white space in its low-character table. The ta-
       ble 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 char-
       acters,  five  more Unicode "Pattern White Space" characters are recog-
       nized 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 char-
       acters 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 set-
       ting  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  sec-
       tion  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 set-
       ting.

         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  new-
       line. If startoffset is non-zero, the limiting newline is not necessar-
       ily 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 effi-
       ciency, 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_DOL-
       LAR_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 com-
       piled.  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 pre-
       vents  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 combina-
       tion 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 paren-
       theses  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  imme-
       diately  if it cannot find it, without actually running the main match-
       ing 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  optimiza-
       tions  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  pat-
       tern  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 encoun-
       tered 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 dis-
       able  the error that is given if an escape sequence for an invalid Uni-
       code 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  pos-
       sible only in UTF-8 and UTF-32 modes, because these values are not rep-
       resentable 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 char-
       acters. 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  proper-
       ties  for  upper/lower casing operations on characters with code points
       greater than 127, even when PCRE2_UTF is not set. This makes it  possi-
       ble,  for  example,  to  process strings in the 16-bit UCS-2 code. This
       option is available only if PCRE2 has been compiled with  Unicode  sup-
       port (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 con-
       text 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  valid-
       ity.

       If  the extra option PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES is set, surro-
       gate 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  func-
       tionality 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 hexadeci-
       mal 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 inconsis-
       tent  in  handling  such items: for example, \j is treated as a literal
       "j", and non-hexadecimal digits in \x{} are just ignored, though  warn-
       ings  are given in both cases if Perl's warning switch is enabled. How-
       ever, 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 unex-
       pected 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 lit-
       eral 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 com-
       piled 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  pat-
       tern 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  pat-
       terns  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 charac-
       ters 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 dif-
       ferent.

       The built-in tables can be overridden by tables supplied by the  appli-
       cation  that  calls  PCRE2.  These may be created in a different locale
       from the default.  As more and more applications change to  using  Uni-
       code, 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  com-
       piled 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 num-
       bers:

         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 com-
       piled 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_ALLOP-
       TIONS 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() func-
       tion.

       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_ALLOP-
       TIONS, 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 match-
       ing  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 con-
       structed, 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 vari-
       ables.

         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 argu-
       ment 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, respec-
       tively.

         PCRE2_INFO_JITSIZE

       If the compiled pattern was successfully  processed  by  pcre2_jit_com-
       pile(),  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 argu-
       ment 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 con-
       tains 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 match-
       ing 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  pro-
       cessed,  the first lookbehind moves back by two characters, matches one
       character, then the nested lookbehind also moves back  by  two  charac-
       ters. 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 parenthe-
       ses. The names are just an additional way of identifying the  parenthe-
       ses, which still acquire numbers. Several convenience functions such as
       pcre2_substring_get_byname() are provided for extracting captured  sub-
       strings  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_NAME-
       COUNT 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  cap-
       turing 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.  Differ-
       ent names for groups of the same number are not permitted.

       Duplicate  names  for capture groups with different numbers are permit-
       ted, 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 num-
       bers.

       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 mean-
       ing "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  pat-
       tern  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 enumer-
       ation  block,  and  its second argument is the user_data value that was
       passed to pcre2_callout_enumerate(). The contents of the  callout  enu-
       meration  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 endi-
       anness, 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  documen-
       tation.  Note  that  PCRE2 serialization does not convert compiled pat-
       terns 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 func-
       tions 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  sub-
       strings.

       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 second argument of pcre2_match_data_create() is a pointer to a gen-
       eral  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 pat-
       tern (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 dif-
       ferent 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 sec-
       tion 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  pro-
       cessing 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 off-
       set  must  point to the start of a character, or to the end of the sub-
       ject (in UTF-32 mode, one code unit equals one character, so  all  off-
       sets  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 start-
       ing 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 suc-
       ceed 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 set-
       ting 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  sup-
       ported  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  guaran-
       teed,  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 success-
       ful  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  set-
       ting 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 with-
       out having set PCRE2_MULTILINE at compile time causes dollar  never  to
       match. This option affects only the behaviour of the dollar metacharac-
       ter. 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 doc-
       umentation.

       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 addi-
       tion,  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_PAR-
       TIAL_HARD) is set, matching continues by testing any remaining alterna-
       tives.  Only  if  no complete match can be found is PCRE2_ERROR_PARTIAL
       returned instead of PCRE2_ERROR_NOMATCH.  In  other  words,  PCRE2_PAR-
       TIAL_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 consid-
       ered to be more important that an alternative complete match.

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

NEWLINE HANDLING WHEN MATCHING

       When  PCRE2 is built, a default newline convention is set; this is usu-
       ally 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  be-
       haviour  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  con-
       tains an explicit CR or LF reference, and so advances only by one char-
       acter 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 char-
       acters 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 val-
       ues, 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 con-
       tains.

       Within the ovector, the first in each pair of values is set to the off-
       set 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  val-
       ues  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 pat-
       tern. 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 sub-
       strings, 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  opera-
       tion,  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 cap-
       turing parentheses, no more than ovector[0] to ovector[2n+1] are set by
       pcre2_match(). The other elements retain whatever  values  they  previ-
       ously  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 com-
       piled 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 see-
       ing any marks. You can disable the start-of-match optimizations by set-
       ting 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  con-
       verted  to a text string by calling the pcre2_get_error_message() func-
       tion (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  com-
       piled  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 documenta-
       tion for more details.

         PCRE2_ERROR_MATCHLIMIT

       The backtracking match limit was reached.

         PCRE2_ERROR_NOMEMORY

       If a pattern contains many nested backtracking points, heap  memory  is
       used  to  remember them. This error is given when the memory allocation
       function (default or  custom)  fails.  Note  that  a  different  error,
       PCRE2_ERROR_HEAPLIMIT,  is given if the amount of memory needed exceeds
       the   heap   limit.   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  pat-
       tern 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 com-
       plicated 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_mes-
       sage().  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 func-
       tion 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  mes-
       sage  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 refer-
       ring 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 sub-
       string 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  argu-
       ments  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  con-
       tains 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 sub-
       strings 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 argu-
       ment 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 mem-
       ory 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  num-
       ber.  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 argu-
       ment 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 distin-
       guish  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  nega-
       tive 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 lookbe-
       hind 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 permit-
       ted,  and  match_data may be passed as NULL, in which case a match data
       block is obtained and freed within this function, using memory  manage-
       ment  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 vec-
       tor) is then  used  for  the  first  substitution  instead  of  calling
       pcre2_match()  from  within pcre2_substitute(). This allows an applica-
       tion 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_SUBSTI-
       TUTE_GLOBAL  is  also set, pcre2_match() is called after the first sub-
       stitution 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  substitu-
       tion  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 paren-
       theses 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_SUB-
       STITUTE_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 vari-
       able 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_NOMEM-
       ORY immediately. If this option  is  set,  however,  pcre2_substitute()
       continues to go through the motions of matching and substituting (with-
       out, of course, writing anything) in order to compute the size of  buf-
       fer  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 appli-
       cation, it may be more efficient to allocate a large  buffer  and  free
       the   excess   afterwards,   instead  of  using  PCRE2_SUBSTITUTE_OVER-
       FLOW_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 rel-
       evant 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 cap-
       ture groups and names from (*MARK) or other control verbs in  the  pat-
       tern. 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  inter-
       preted 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  replace-
       ments  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, search-
       ing 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 off-
       set 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 off-
       set 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-alphanu-
       meric  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, respec-
       tively, 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  let-
       ters  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 exam-
       ple, 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  speci-
       fies  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 irrele-
       vant 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 inser-
       tion, unless PCRE2_SUBSTITUTE_UNKNOWN_UNSET is set.

       PCRE2_ERROR_UNSET is returned for an unset substring insertion (includ-
       ing an unknown substring when  PCRE2_SUBSTITUTE_UNKNOWN_UNSET  is  set)
       when  the  simple  (non-extended)  syntax  is  used  and  PCRE2_SUBSTI-
       TUTE_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_REP-
       MISSINGBRACE  (closing curly bracket not found), PCRE2_ERROR_BADSUBSTI-
       TUTION   (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 nec-
       essarily 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 point-
       ers 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_SUB-
       STITUTE_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, return-
       ing 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  sub-
       ject. 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 func-
       tion, 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 pat-
       tern.  When your callout function is called, extract and save the  cur-
       rent  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 compati-
       ble with Perl. Some of the features of  PCRE2  patterns  are  not  sup-
       ported. 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 com-
       mon  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 por-
       tion 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 alterna-
       tive  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 sub-
       string 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 sub-
       strings 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: 14 December 2021
       Copyright (c) 1997-2021 University of Cambridge.

PCRE2 10.40                    14 December 2021                    PCRE2API(3)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2022 Hurricane Electric. All Rights Reserved.