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
       pcre_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_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),  the  Unicode
       properties of all characters can be tested with \p and \P, or, alterna-
       tively, 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  opera-
       tions  on  characters  with code points greater than 127 to use Unicode
       properties. These effects apply even when PCRE2_UTF is not set.

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

       PCRE2 contains a built-in set of character  tables  that  are  used  by
       default.   These  are  sufficient  for many applications. Normally, the
       internal tables recognize only ASCII characters. However, when PCRE2 is
       built, it is possible to cause the internal tables to be rebuilt in the
       default "C" locale of the local system, which may cause them to be 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 part of  the
       subject  and  any  substrings  that were captured. 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. One pair of offsets is
       required to identify the string that matched the whole pattern, with an
       additional  pair for each captured substring. For example, a value of 4
       creates enough space to record the matched portion of the subject  plus
       three  captured  substrings. A minimum of at least 1 pair is imposed by
       pcre2_match_data_create(), so it is always possible to return the over-
       all matched string.

       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. The sec-
       ond  argument is again a pointer to a general context, but in this case
       if NULL is passed, the memory is obtained using the same allocator that
       was used for the compiled pattern (custom or default).

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

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

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

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

MATCHING A PATTERN: THE TRADITIONAL FUNCTION

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

       The  function pcre2_match() is called to match a subject string against
       a compiled pattern, which is passed in the code argument. You can  call
       pcre2_match() with the same code argument as many times as you like, in
       order to find multiple matches in the subject string or to  match  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.

       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 "Mississipi" the first call to pcre2_match()
       finds the first occurrence. If pcre2_match() is called again with  just
       the  remainder  of  the  subject,  namely  "issipi", 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 occur-
       rence  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. This
       can be given as PCRE2_ZERO_TERMINATED  for  a  zero-terminated  string.
       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 been  used  for  an
       external  call  to  pcre2_match().  The  data  in  the match_data block
       (return code, offset vector) is used for the first substitution instead
       of calling pcre2_match() from within pcre2_substitute(). This allows an
       application to check for a match before choosing to substitute, without
       having to repeat the match.

       The  contents  of  the  externally  supplied  match  data block are not
       changed  when  PCRE2_SUBSTITUTE_MATCHED  is   set.   If   PCRE2_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.

       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.  This has different characteristics to the normal  algo-
       rithm,  and  is not compatible with Perl. Some of the features of PCRE2
       patterns are not supported.  Nevertheless, there are  times  when  this
       kind  of  matching  can be useful. For a discussion of the two matching
       algorithms, and a list of features that pcre2_dfa_match() does not sup-
       port, 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 pcre_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
       University Computing Service
       Cambridge, England.

REVISION

       Last updated: 04 November 2020
       Copyright (c) 1997-2020 University of Cambridge.

PCRE2 10.36                    04 November 2020                    PCRE2API(3)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2021 Hurricane Electric. All Rights Reserved.