[BACK]Return to pcre.txt CVS log [TXT] [DIR] Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc

Diff for /embedaddon/pcre/doc/pcre.txt between versions 1.1.1.1 and 1.1.1.3

version 1.1.1.1, 2012/02/21 23:05:52 version 1.1.1.3, 2012/10/09 09:19:17
Line 25  INTRODUCTION Line 25  INTRODUCTION
        items, and there is an option for requesting some  minor  changes  that         items, and there is an option for requesting some  minor  changes  that
        give better JavaScript compatibility.         give better JavaScript compatibility.
   
          Starting with release 8.30, it is possible to compile two separate PCRE
          libraries:  the  original,  which  supports  8-bit  character   strings
          (including  UTF-8  strings),  and a second library that supports 16-bit
          character strings (including UTF-16 strings). The build process  allows
          either  one  or both to be built. The majority of the work to make this
          possible was done by Zoltan Herczeg.
   
          The two libraries contain identical sets of functions, except that  the
          names  in  the  16-bit  library start with pcre16_ instead of pcre_. To
          avoid over-complication and reduce the documentation maintenance  load,
          most of the documentation describes the 8-bit library, with the differ-
          ences for the 16-bit library described separately in the  pcre16  page.
          References  to  functions or structures of the form pcre[16]_xxx should
          be  read  as  meaning  "pcre_xxx  when  using  the  8-bit  library  and
          pcre16_xxx when using the 16-bit library".
   
        The  current implementation of PCRE corresponds approximately with Perl         The  current implementation of PCRE corresponds approximately with Perl
       5.12, including support for UTF-8 encoded strings and  Unicode  general       5.12, including support for UTF-8/16 encoded strings and  Unicode  gen-
       category  properties.  However,  UTF-8  and  Unicode  support has to be       eral  category properties. However, UTF-8/16 and Unicode support has to
       explicitly enabled; it is not the default. The  Unicode  tables  corre-       be explicitly enabled; it is not the default. The Unicode tables corre-
        spond to Unicode release 6.0.0.         spond to Unicode release 6.0.0.
   
        In  addition to the Perl-compatible matching function, PCRE contains an         In  addition to the Perl-compatible matching function, PCRE contains an
Line 39  INTRODUCTION Line 55  INTRODUCTION
   
        PCRE  is  written  in C and released as a C library. A number of people         PCRE  is  written  in C and released as a C library. A number of people
        have written wrappers and interfaces of various kinds.  In  particular,         have written wrappers and interfaces of various kinds.  In  particular,
       Google  Inc.   have  provided  a comprehensive C++ wrapper. This is now       Google  Inc.   have  provided a comprehensive C++ wrapper for the 8-bit
       included as part of the PCRE distribution. The pcrecpp page has details       library. This is now included as part of  the  PCRE  distribution.  The
       of  this  interface.  Other  people's contributions can be found in the       pcrecpp  page  has  details of this interface. Other people's contribu-
       Contrib directory at the primary FTP site, which is:       tions can be found in the Contrib directory at the  primary  FTP  site,
        which is:
   
        ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre         ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre
   
       Details of exactly which Perl regular expression features are  and  are       Details  of  exactly which Perl regular expression features are and are
        not supported by PCRE are given in separate documents. See the pcrepat-         not supported by PCRE are given in separate documents. See the pcrepat-
       tern and pcrecompat pages. There is a syntax summary in the  pcresyntax       tern  and pcrecompat pages. There is a syntax summary in the pcresyntax
        page.         page.
   
       Some  features  of  PCRE can be included, excluded, or changed when the       Some features of PCRE can be included, excluded, or  changed  when  the
       library is built. The pcre_config() function makes it  possible  for  a       library  is  built.  The pcre_config() function makes it possible for a
       client  to  discover  which  features are available. The features them-       client to discover which features are  available.  The  features  them-
       selves are described in the pcrebuild page. Documentation about  build-       selves  are described in the pcrebuild page. Documentation about build-
       ing  PCRE  for various operating systems can be found in the README and       ing PCRE for various operating systems can be found in the  README  and
        NON-UNIX-USE files in the source distribution.         NON-UNIX-USE files in the source distribution.
   
       The library contains a number of undocumented  internal  functions  and       The  libraries contains a number of undocumented internal functions and
       data  tables  that  are  used by more than one of the exported external       data tables that are used by more than one  of  the  exported  external
       functions, but which are not intended  for  use  by  external  callers.       functions,  but  which  are  not  intended for use by external callers.
       Their  names  all begin with "_pcre_", which hopefully will not provoke       Their names all begin with "_pcre_" or "_pcre16_", which hopefully will
       any name clashes. In some environments, it is possible to control which       not  provoke  any name clashes. In some environments, it is possible to
       external  symbols  are  exported when a shared library is built, and in       control which external symbols are exported when a  shared  library  is
       these cases the undocumented symbols are not exported.       built, and in these cases the undocumented symbols are not exported.
   
   
 USER DOCUMENTATION  USER DOCUMENTATION
   
       The user documentation for PCRE comprises a number  of  different  sec-       The  user  documentation  for PCRE comprises a number of different sec-
       tions.  In the "man" format, each of these is a separate "man page". In       tions. In the "man" format, each of these is a separate "man page".  In
       the HTML format, each is a separate page, linked from the  index  page.       the  HTML  format, each is a separate page, linked from the index page.
       In  the  plain  text format, all the sections, except the pcredemo sec-       In the plain text format, all the sections, except  the  pcredemo  sec-
        tion, are concatenated, for ease of searching. The sections are as fol-         tion, are concatenated, for ease of searching. The sections are as fol-
        lows:         lows:
   
          pcre              this document           pcre              this document
            pcre16            details of the 16-bit library
          pcre-config       show PCRE installation configuration information           pcre-config       show PCRE installation configuration information
          pcreapi           details of PCRE's native C API           pcreapi           details of PCRE's native C API
          pcrebuild         options for building PCRE           pcrebuild         options for building PCRE
          pcrecallout       details of the callout feature           pcrecallout       details of the callout feature
          pcrecompat        discussion of Perl compatibility           pcrecompat        discussion of Perl compatibility
         pcrecpp           details of the C++ wrapper         pcrecpp           details of the C++ wrapper for the 8-bit library
          pcredemo          a demonstration C program that uses PCRE           pcredemo          a demonstration C program that uses PCRE
         pcregrep          description of the pcregrep command         pcregrep          description of the pcregrep command (8-bit only)
          pcrejit           discussion of the just-in-time optimization support           pcrejit           discussion of the just-in-time optimization support
          pcrelimits        details of size and other limits           pcrelimits        details of size and other limits
          pcrematching      discussion of the two matching algorithms           pcrematching      discussion of the two matching algorithms
Line 92  USER DOCUMENTATION Line 110  USER DOCUMENTATION
          pcrepattern       syntax and semantics of supported           pcrepattern       syntax and semantics of supported
                              regular expressions                               regular expressions
          pcreperform       discussion of performance issues           pcreperform       discussion of performance issues
         pcreposix         the POSIX-compatible C API         pcreposix         the POSIX-compatible C API for the 8-bit library
          pcreprecompile    details of saving and re-using precompiled patterns           pcreprecompile    details of saving and re-using precompiled patterns
          pcresample        discussion of the pcredemo program           pcresample        discussion of the pcredemo program
          pcrestack         discussion of stack usage           pcrestack         discussion of stack usage
          pcresyntax        quick syntax reference           pcresyntax        quick syntax reference
          pcretest          description of the pcretest testing command           pcretest          description of the pcretest testing command
         pcreunicode       discussion of Unicode and UTF-8 support         pcreunicode       discussion of Unicode and UTF-8/16 support
   
       In  addition,  in the "man" and HTML formats, there is a short page for       In addition, in the "man" and HTML formats, there is a short  page  for
       each C library function, listing its arguments and results.       each 8-bit C library function, listing its arguments and results.
   
   
 AUTHOR  AUTHOR
Line 110  AUTHOR Line 128  AUTHOR
        University Computing Service         University Computing Service
        Cambridge CB2 3QH, England.         Cambridge CB2 3QH, England.
   
       Putting an actual email address here seems to have been a spam  magnet,       Putting  an actual email address here seems to have been a spam magnet,
       so  I've  taken  it away. If you want to email me, use my two initials,       so I've taken it away. If you want to email me, use  my  two  initials,
        followed by the two digits 10, at the domain cam.ac.uk.         followed by the two digits 10, at the domain cam.ac.uk.
   
   
 REVISION  REVISION
   
       Last updated: 24 August 2011       Last updated: 10 January 2012
       Copyright (c) 1997-2011 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
   PCRE(3)                                                                PCRE(3)
   
   
   NAME
          PCRE - Perl-compatible regular expressions
   
          #include <pcre.h>
   
   
   PCRE 16-BIT API BASIC FUNCTIONS
   
          pcre16 *pcre16_compile(PCRE_SPTR16 pattern, int options,
               const char **errptr, int *erroffset,
               const unsigned char *tableptr);
   
          pcre16 *pcre16_compile2(PCRE_SPTR16 pattern, int options,
               int *errorcodeptr,
               const char **errptr, int *erroffset,
               const unsigned char *tableptr);
   
          pcre16_extra *pcre16_study(const pcre16 *code, int options,
               const char **errptr);
   
          void pcre16_free_study(pcre16_extra *extra);
   
          int pcre16_exec(const pcre16 *code, const pcre16_extra *extra,
               PCRE_SPTR16 subject, int length, int startoffset,
               int options, int *ovector, int ovecsize);
   
          int pcre16_dfa_exec(const pcre16 *code, const pcre16_extra *extra,
               PCRE_SPTR16 subject, int length, int startoffset,
               int options, int *ovector, int ovecsize,
               int *workspace, int wscount);
   
   
   PCRE 16-BIT API STRING EXTRACTION FUNCTIONS
   
          int pcre16_copy_named_substring(const pcre16 *code,
               PCRE_SPTR16 subject, int *ovector,
               int stringcount, PCRE_SPTR16 stringname,
               PCRE_UCHAR16 *buffer, int buffersize);
   
          int pcre16_copy_substring(PCRE_SPTR16 subject, int *ovector,
               int stringcount, int stringnumber, PCRE_UCHAR16 *buffer,
               int buffersize);
   
          int pcre16_get_named_substring(const pcre16 *code,
               PCRE_SPTR16 subject, int *ovector,
               int stringcount, PCRE_SPTR16 stringname,
               PCRE_SPTR16 *stringptr);
   
          int pcre16_get_stringnumber(const pcre16 *code,
               PCRE_SPTR16 name);
   
          int pcre16_get_stringtable_entries(const pcre16 *code,
               PCRE_SPTR16 name, PCRE_UCHAR16 **first, PCRE_UCHAR16 **last);
   
          int pcre16_get_substring(PCRE_SPTR16 subject, int *ovector,
               int stringcount, int stringnumber,
               PCRE_SPTR16 *stringptr);
   
          int pcre16_get_substring_list(PCRE_SPTR16 subject,
               int *ovector, int stringcount, PCRE_SPTR16 **listptr);
   
          void pcre16_free_substring(PCRE_SPTR16 stringptr);
   
          void pcre16_free_substring_list(PCRE_SPTR16 *stringptr);
   
   
   PCRE 16-BIT API AUXILIARY FUNCTIONS
   
          pcre16_jit_stack *pcre16_jit_stack_alloc(int startsize, int maxsize);
   
          void pcre16_jit_stack_free(pcre16_jit_stack *stack);
   
          void pcre16_assign_jit_stack(pcre16_extra *extra,
               pcre16_jit_callback callback, void *data);
   
          const unsigned char *pcre16_maketables(void);
   
          int pcre16_fullinfo(const pcre16 *code, const pcre16_extra *extra,
               int what, void *where);
   
          int pcre16_refcount(pcre16 *code, int adjust);
   
          int pcre16_config(int what, void *where);
   
          const char *pcre16_version(void);
   
          int pcre16_pattern_to_host_byte_order(pcre16 *code,
               pcre16_extra *extra, const unsigned char *tables);
   
   
   PCRE 16-BIT API INDIRECTED FUNCTIONS
   
          void *(*pcre16_malloc)(size_t);
   
          void (*pcre16_free)(void *);
   
          void *(*pcre16_stack_malloc)(size_t);
   
          void (*pcre16_stack_free)(void *);
   
          int (*pcre16_callout)(pcre16_callout_block *);
   
   
   PCRE 16-BIT API 16-BIT-ONLY FUNCTION
   
          int pcre16_utf16_to_host_byte_order(PCRE_UCHAR16 *output,
               PCRE_SPTR16 input, int length, int *byte_order,
               int keep_boms);
   
   
   THE PCRE 16-BIT LIBRARY
   
          Starting  with  release  8.30, it is possible to compile a PCRE library
          that supports 16-bit character strings, including  UTF-16  strings,  as
          well  as  or instead of the original 8-bit library. The majority of the
          work to make  this  possible  was  done  by  Zoltan  Herczeg.  The  two
          libraries contain identical sets of functions, used in exactly the same
          way. Only the names of the functions and the data types of their  argu-
          ments  and results are different. To avoid over-complication and reduce
          the documentation maintenance load,  most  of  the  PCRE  documentation
          describes  the  8-bit  library,  with only occasional references to the
          16-bit library. This page describes what is different when you use  the
          16-bit library.
   
          WARNING:  A  single  application can be linked with both libraries, but
          you must take care when processing any particular pattern to use  func-
          tions  from  just one library. For example, if you want to study a pat-
          tern that was compiled with  pcre16_compile(),  you  must  do  so  with
          pcre16_study(), not pcre_study(), and you must free the study data with
          pcre16_free_study().
   
   
   THE HEADER FILE
   
          There is only one header file, pcre.h. It contains prototypes  for  all
          the  functions  in  both  libraries,  as  well as definitions of flags,
          structures, error codes, etc.
   
   
   THE LIBRARY NAME
   
          In Unix-like systems, the 16-bit library is called libpcre16,  and  can
          normally  be  accesss  by adding -lpcre16 to the command for linking an
          application that uses PCRE.
   
   
   STRING TYPES
   
          In the 8-bit library, strings are passed to PCRE library  functions  as
          vectors  of  bytes  with  the  C  type "char *". In the 16-bit library,
          strings are passed as vectors of unsigned 16-bit quantities. The  macro
          PCRE_UCHAR16  specifies  an  appropriate  data type, and PCRE_SPTR16 is
          defined as "const PCRE_UCHAR16 *". In very  many  environments,  "short
          int" is a 16-bit data type. When PCRE is built, it defines PCRE_UCHAR16
          as "short int", but checks that it really is a 16-bit data type. If  it
          is not, the build fails with an error message telling the maintainer to
          modify the definition appropriately.
   
   
   STRUCTURE TYPES
   
          The types of the opaque structures that are used  for  compiled  16-bit
          patterns  and  JIT stacks are pcre16 and pcre16_jit_stack respectively.
          The  type  of  the  user-accessible  structure  that  is  returned   by
          pcre16_study()  is  pcre16_extra, and the type of the structure that is
          used for passing data to a callout  function  is  pcre16_callout_block.
          These structures contain the same fields, with the same names, as their
          8-bit counterparts. The only difference is that pointers  to  character
          strings are 16-bit instead of 8-bit types.
   
   
   16-BIT FUNCTIONS
   
          For  every function in the 8-bit library there is a corresponding func-
          tion in the 16-bit library with a name that starts with pcre16_ instead
          of  pcre_.  The  prototypes are listed above. In addition, there is one
          extra function, pcre16_utf16_to_host_byte_order(). This  is  a  utility
          function  that converts a UTF-16 character string to host byte order if
          necessary. The other 16-bit  functions  expect  the  strings  they  are
          passed to be in host byte order.
   
          The input and output arguments of pcre16_utf16_to_host_byte_order() may
          point to the same address, that is, conversion in place  is  supported.
          The output buffer must be at least as long as the input.
   
          The  length  argument  specifies the number of 16-bit data units in the
          input string; a negative value specifies a zero-terminated string.
   
          If byte_order is NULL, it is assumed that the string starts off in host
          byte  order. This may be changed by byte-order marks (BOMs) anywhere in
          the string (commonly as the first character).
   
          If byte_order is not NULL, a non-zero value of the integer to which  it
          points  means  that  the input starts off in host byte order, otherwise
          the opposite order is assumed. Again, BOMs in  the  string  can  change
          this. The final byte order is passed back at the end of processing.
   
          If  keep_boms  is  not  zero,  byte-order  mark characters (0xfeff) are
          copied into the output string. Otherwise they are discarded.
   
          The result of the function is the number of 16-bit  units  placed  into
          the  output  buffer,  including  the  zero terminator if the string was
          zero-terminated.
   
   
   SUBJECT STRING OFFSETS
   
          The offsets within subject strings that are returned  by  the  matching
          functions are in 16-bit units rather than bytes.
   
   
   NAMED SUBPATTERNS
   
          The  name-to-number translation table that is maintained for named sub-
          patterns uses 16-bit characters.  The  pcre16_get_stringtable_entries()
          function returns the length of each entry in the table as the number of
          16-bit data units.
   
   
   OPTION NAMES
   
          There   are   two   new   general   option   names,   PCRE_UTF16    and
          PCRE_NO_UTF16_CHECK,     which     correspond    to    PCRE_UTF8    and
          PCRE_NO_UTF8_CHECK in the 8-bit library. In  fact,  these  new  options
          define  the  same bits in the options word. There is a discussion about
          the validity of UTF-16 strings in the pcreunicode page.
   
          For the pcre16_config() function there is an  option  PCRE_CONFIG_UTF16
          that  returns  1  if UTF-16 support is configured, otherwise 0. If this
          option is given to pcre_config(), or if the PCRE_CONFIG_UTF8 option  is
          given to pcre16_config(), the result is the PCRE_ERROR_BADOPTION error.
   
   
   CHARACTER CODES
   
          In  16-bit  mode,  when  PCRE_UTF16  is  not  set, character values are
          treated in the same way as in 8-bit, non UTF-8 mode, except, of course,
          that  they  can  range from 0 to 0xffff instead of 0 to 0xff. Character
          types for characters less than 0xff can therefore be influenced by  the
          locale  in  the  same way as before.  Characters greater than 0xff have
          only one case, and no "type" (such as letter or digit).
   
          In UTF-16 mode, the character code  is  Unicode,  in  the  range  0  to
          0x10ffff,  with  the  exception of values in the range 0xd800 to 0xdfff
          because those are "surrogate" values that are used in pairs  to  encode
          values greater than 0xffff.
   
          A  UTF-16 string can indicate its endianness by special code knows as a
          byte-order mark (BOM). The PCRE functions do not handle this, expecting
          strings   to   be  in  host  byte  order.  A  utility  function  called
          pcre16_utf16_to_host_byte_order() is provided to help  with  this  (see
          above).
   
   
   ERROR NAMES
   
          The  errors PCRE_ERROR_BADUTF16_OFFSET and PCRE_ERROR_SHORTUTF16 corre-
          spond to their 8-bit  counterparts.  The  error  PCRE_ERROR_BADMODE  is
          given  when  a  compiled pattern is passed to a function that processes
          patterns in the other mode, for example, if  a  pattern  compiled  with
          pcre_compile() is passed to pcre16_exec().
   
          There  are  new  error  codes whose names begin with PCRE_UTF16_ERR for
          invalid UTF-16 strings, corresponding to the  PCRE_UTF8_ERR  codes  for
          UTF-8  strings that are described in the section entitled "Reason codes
          for invalid UTF-8 strings" in the main pcreapi page. The UTF-16  errors
          are:
   
            PCRE_UTF16_ERR1  Missing low surrogate at end of string
            PCRE_UTF16_ERR2  Invalid low surrogate follows high surrogate
            PCRE_UTF16_ERR3  Isolated low surrogate
            PCRE_UTF16_ERR4  Invalid character 0xfffe
   
   
   ERROR TEXTS
   
          If  there is an error while compiling a pattern, the error text that is
          passed back by pcre16_compile() or pcre16_compile2() is still an  8-bit
          character string, zero-terminated.
   
   
   CALLOUTS
   
          The  subject  and  mark fields in the callout block that is passed to a
          callout function point to 16-bit vectors.
   
   
   TESTING
   
          The pcretest program continues to operate with 8-bit input  and  output
          files,  but it can be used for testing the 16-bit library. If it is run
          with the command line option -16, patterns and subject strings are con-
          verted from 8-bit to 16-bit before being passed to PCRE, and the 16-bit
          library functions are used instead of the 8-bit ones.  Returned  16-bit
          strings are converted to 8-bit for output. If the 8-bit library was not
          compiled, pcretest defaults to 16-bit and the -16 option is ignored.
   
          When PCRE is being built, the RunTest script that is  called  by  "make
          check"  uses  the pcretest -C option to discover which of the 8-bit and
          16-bit libraries has been built, and runs the tests appropriately.
   
   
   NOT SUPPORTED IN 16-BIT MODE
   
          Not all the features of the 8-bit library are available with the 16-bit
          library.  The  C++  and  POSIX wrapper functions support only the 8-bit
          library, and the pcregrep program is at present 8-bit only.
   
   
   AUTHOR
   
          Philip Hazel
          University Computing Service
          Cambridge CB2 3QH, England.
   
   
   REVISION
   
          Last updated: 14 April 2012
          Copyright (c) 1997-2012 University of Cambridge.
   ------------------------------------------------------------------------------
   
   
 PCREBUILD(3)                                                      PCREBUILD(3)  PCREBUILD(3)                                                      PCREBUILD(3)
   
   
Line 158  PCRE BUILD-TIME OPTIONS Line 502  PCRE BUILD-TIME OPTIONS
        is not described.         is not described.
   
   
   BUILDING 8-BIT and 16-BIT LIBRARIES
   
          By  default,  a  library  called libpcre is built, containing functions
          that take string arguments contained in vectors  of  bytes,  either  as
          single-byte  characters,  or interpreted as UTF-8 strings. You can also
          build a separate library, called libpcre16, in which strings  are  con-
          tained  in  vectors of 16-bit data units and interpreted either as sin-
          gle-unit characters or UTF-16 strings, by adding
   
            --enable-pcre16
   
          to the configure command. If you do not want the 8-bit library, add
   
            --disable-pcre8
   
          as well. At least one of the two libraries must be built. Note that the
          C++  and  POSIX wrappers are for the 8-bit library only, and that pcre-
          grep is an 8-bit program. None of these are built if  you  select  only
          the 16-bit library.
   
   
 BUILDING SHARED AND STATIC LIBRARIES  BUILDING SHARED AND STATIC LIBRARIES
   
        The  PCRE building process uses libtool to build both shared and static         The  PCRE building process uses libtool to build both shared and static
Line 172  BUILDING SHARED AND STATIC LIBRARIES Line 537  BUILDING SHARED AND STATIC LIBRARIES
   
 C++ SUPPORT  C++ SUPPORT
   
       By default, the configure script will search for a C++ compiler and C++       By  default,  if the 8-bit library is being built, the configure script
       header files. If it finds them, it automatically builds the C++ wrapper       will search for a C++ compiler and C++ header files. If it finds  them,
       library for PCRE. You can disable this by adding       it  automatically  builds  the C++ wrapper library (which supports only
        8-bit strings). You can disable this by adding
   
          --disable-cpp           --disable-cpp
   
        to the configure command.         to the configure command.
   
   
UTF-8 SUPPORTUTF-8 and UTF-16 SUPPORT
   
       To build PCRE with support for UTF-8 Unicode character strings, add       To build PCRE with support for UTF Unicode character strings, add
   
         --enable-utf8         --enable-utf
   
       to  the  configure  command.  Of  itself, this does not make PCRE treat       to the configure command.  This  setting  applies  to  both  libraries,
       strings as UTF-8. As well as compiling PCRE with this option, you  also       adding support for UTF-8 to the 8-bit library and support for UTF-16 to
       have  have to set the PCRE_UTF8 option when you call the pcre_compile()       the 16-bit library. There are no separate options  for  enabling  UTF-8
       or pcre_compile2() functions.       and  UTF-16  independently because that would allow ridiculous settings
        such as  requesting  UTF-16  support  while  building  only  the  8-bit
        library.  It  is not possible to build one library with UTF support and
        the other without in the same configuration. (For backwards compatibil-
        ity, --enable-utf8 is a synonym of --enable-utf.)
   
       If you set --enable-utf8 when compiling in an EBCDIC environment,  PCRE       Of  itself,  this  setting does not make PCRE treat strings as UTF-8 or
       expects its input to be either ASCII or UTF-8 (depending on the runtime       UTF-16. As well as compiling PCRE with this option, you also have  have
       option). It is not possible to support both EBCDIC and UTF-8  codes  in       to set the PCRE_UTF8 or PCRE_UTF16 option when you call one of the pat-
       the  same  version  of  the  library.  Consequently,  --enable-utf8 and       tern compiling functions.
 
        If you set --enable-utf when compiling in an EBCDIC  environment,  PCRE
        expects  its  input  to be either ASCII or UTF-8 (depending on the run-
        time option). It is not possible to support both EBCDIC and UTF-8 codes
        in  the  same  version  of  the library. Consequently, --enable-utf and
        --enable-ebcdic are mutually exclusive.         --enable-ebcdic are mutually exclusive.
   
   
 UNICODE CHARACTER PROPERTY SUPPORT  UNICODE CHARACTER PROPERTY SUPPORT
   
       UTF-8 support allows PCRE to process character values greater than  255       UTF support allows the libraries to process character codepoints up  to
       in  the  strings that it handles. On its own, however, it does not pro-       0x10ffff  in the strings that they handle. On its own, however, it does
       vide any facilities for accessing the properties of such characters. If       not provide any facilities for accessing the properties of such charac-
       you  want  to  be able to use the pattern escapes \P, \p, and \X, which       ters. If you want to be able to use the pattern escapes \P, \p, and \X,
       refer to Unicode character properties, you must add       which refer to Unicode character properties, you must add
   
          --enable-unicode-properties           --enable-unicode-properties
   
       to the configure command. This implies UTF-8 support, even if you  have       to the configure command. This implies UTF support, even  if  you  have
        not explicitly requested it.         not explicitly requested it.
   
        Including  Unicode  property  support  adds around 30K of tables to the         Including  Unicode  property  support  adds around 30K of tables to the
Line 282  WHAT \R MATCHES Line 657  WHAT \R MATCHES
   
 POSIX MALLOC USAGE  POSIX MALLOC USAGE
   
       When PCRE is called through the POSIX interface (see the pcreposix doc-       When  the  8-bit library is called through the POSIX interface (see the
       umentation), additional working storage is  required  for  holding  the       pcreposix documentation), additional working storage  is  required  for
       pointers  to capturing substrings, because PCRE requires three integers       holding  the  pointers  to  capturing substrings, because PCRE requires
       per substring, whereas the POSIX interface provides only  two.  If  the       three integers per substring, whereas the POSIX interface provides only
       number of expected substrings is small, the wrapper function uses space       two.  If  the number of expected substrings is small, the wrapper func-
       on the stack, because this is faster than using malloc() for each call.       tion uses space on the stack, because this is faster  than  using  mal-
       The default threshold above which the stack is no longer used is 10; it       loc()  for each call. The default threshold above which the stack is no
       can be changed by adding a setting such as       longer used is 10; it can be changed by adding a setting such as
   
          --with-posix-malloc-threshold=20           --with-posix-malloc-threshold=20
   
Line 303  HANDLING VERY LARGE PATTERNS Line 678  HANDLING VERY LARGE PATTERNS
        nation metacharacter). By default, two-byte values are used  for  these         nation metacharacter). By default, two-byte values are used  for  these
        offsets,  leading  to  a  maximum size for a compiled pattern of around         offsets,  leading  to  a  maximum size for a compiled pattern of around
        64K. This is sufficient to handle all but the most  gigantic  patterns.         64K. This is sufficient to handle all but the most  gigantic  patterns.
       Nevertheless,  some  people do want to process truyl enormous patterns,       Nevertheless,  some  people do want to process truly enormous patterns,
        so it is possible to compile PCRE to use three-byte or  four-byte  off-         so it is possible to compile PCRE to use three-byte or  four-byte  off-
        sets by adding a setting such as         sets by adding a setting such as
   
          --with-link-size=3           --with-link-size=3
   
       to  the  configure  command.  The value given must be 2, 3, or 4. Using       to  the  configure command. The value given must be 2, 3, or 4. For the
       longer offsets slows down the operation of PCRE because it has to  load       16-bit library, a value of 3 is rounded up to 4. Using  longer  offsets
       additional bytes when handling them.       slows down the operation of PCRE because it has to load additional data
        when handling them.
   
   
 AVOIDING EXCESSIVE STACK USAGE  AVOIDING EXCESSIVE STACK USAGE
   
        When matching with the pcre_exec() function, PCRE implements backtrack-         When matching with the pcre_exec() function, PCRE implements backtrack-
       ing by making recursive calls to an internal function  called  match().       ing  by  making recursive calls to an internal function called match().
       In  environments  where  the size of the stack is limited, this can se-       In environments where the size of the stack is limited,  this  can  se-
       verely limit PCRE's operation. (The Unix environment does  not  usually       verely  limit  PCRE's operation. (The Unix environment does not usually
        suffer from this problem, but it may sometimes be necessary to increase         suffer from this problem, but it may sometimes be necessary to increase
       the maximum stack size.  There is a discussion in the  pcrestack  docu-       the  maximum  stack size.  There is a discussion in the pcrestack docu-
       mentation.)  An alternative approach to recursion that uses memory from       mentation.) An alternative approach to recursion that uses memory  from
       the heap to remember data, instead of using recursive  function  calls,       the  heap  to remember data, instead of using recursive function calls,
       has  been  implemented to work round the problem of limited stack size.       has been implemented to work round the problem of limited  stack  size.
        If you want to build a version of PCRE that works this way, add         If you want to build a version of PCRE that works this way, add
   
          --disable-stack-for-recursion           --disable-stack-for-recursion
   
       to the configure command. With this configuration, PCRE  will  use  the       to  the  configure  command. With this configuration, PCRE will use the
       pcre_stack_malloc  and pcre_stack_free variables to call memory manage-       pcre_stack_malloc and pcre_stack_free variables to call memory  manage-
       ment functions. By default these point to malloc() and free(), but  you       ment  functions. By default these point to malloc() and free(), but you
        can replace the pointers so that your own functions are used instead.         can replace the pointers so that your own functions are used instead.
   
       Separate  functions  are  provided  rather  than  using pcre_malloc and       Separate functions are  provided  rather  than  using  pcre_malloc  and
       pcre_free because the  usage  is  very  predictable:  the  block  sizes       pcre_free  because  the  usage  is  very  predictable:  the block sizes
       requested  are  always  the  same,  and  the blocks are always freed in       requested are always the same, and  the  blocks  are  always  freed  in
       reverse order. A calling program might be able to  implement  optimized       reverse  order.  A calling program might be able to implement optimized
       functions  that  perform  better  than  malloc()  and free(). PCRE runs       functions that perform better  than  malloc()  and  free().  PCRE  runs
        noticeably more slowly when built in this way. This option affects only         noticeably more slowly when built in this way. This option affects only
        the pcre_exec() function; it is not relevant for pcre_dfa_exec().         the pcre_exec() function; it is not relevant for pcre_dfa_exec().
   
   
 LIMITING PCRE RESOURCE USAGE  LIMITING PCRE RESOURCE USAGE
   
       Internally,  PCRE has a function called match(), which it calls repeat-       Internally, PCRE has a function called match(), which it calls  repeat-
       edly  (sometimes  recursively)  when  matching  a  pattern   with   the       edly   (sometimes   recursively)  when  matching  a  pattern  with  the
       pcre_exec()  function.  By controlling the maximum number of times this       pcre_exec() function. By controlling the maximum number of  times  this
       function may be called during a single matching operation, a limit  can       function  may be called during a single matching operation, a limit can
       be  placed  on  the resources used by a single call to pcre_exec(). The       be placed on the resources used by a single call  to  pcre_exec().  The
       limit can be changed at run time, as described in the pcreapi  documen-       limit  can be changed at run time, as described in the pcreapi documen-
       tation.  The default is 10 million, but this can be changed by adding a       tation. The default is 10 million, but this can be changed by adding  a
        setting such as         setting such as
   
          --with-match-limit=500000           --with-match-limit=500000
   
       to  the  configure  command.  This  setting  has  no  effect   on   the       to   the   configure  command.  This  setting  has  no  effect  on  the
        pcre_dfa_exec() matching function.         pcre_dfa_exec() matching function.
   
       In  some  environments  it is desirable to limit the depth of recursive       In some environments it is desirable to limit the  depth  of  recursive
        calls of match() more strictly than the total number of calls, in order         calls of match() more strictly than the total number of calls, in order
       to  restrict  the maximum amount of stack (or heap, if --disable-stack-       to restrict the maximum amount of stack (or heap,  if  --disable-stack-
        for-recursion is specified) that is used. A second limit controls this;         for-recursion is specified) that is used. A second limit controls this;
       it  defaults  to  the  value  that is set for --with-match-limit, which       it defaults to the value that  is  set  for  --with-match-limit,  which
       imposes no additional constraints. However, you can set a  lower  limit       imposes  no  additional constraints. However, you can set a lower limit
        by adding, for example,         by adding, for example,
   
          --with-match-limit-recursion=10000           --with-match-limit-recursion=10000
   
       to  the  configure  command.  This  value can also be overridden at run       to the configure command. This value can  also  be  overridden  at  run
        time.         time.
   
   
 CREATING CHARACTER TABLES AT BUILD TIME  CREATING CHARACTER TABLES AT BUILD TIME
   
       PCRE uses fixed tables for processing characters whose code values  are       PCRE  uses fixed tables for processing characters whose code values are
       less  than 256. By default, PCRE is built with a set of tables that are       less than 256. By default, PCRE is built with a set of tables that  are
       distributed in the file pcre_chartables.c.dist. These  tables  are  for       distributed  in  the  file pcre_chartables.c.dist. These tables are for
        ASCII codes only. If you add         ASCII codes only. If you add
   
          --enable-rebuild-chartables           --enable-rebuild-chartables
   
       to  the  configure  command, the distributed tables are no longer used.       to the configure command, the distributed tables are  no  longer  used.
       Instead, a program called dftables is compiled and  run.  This  outputs       Instead,  a  program  called dftables is compiled and run. This outputs
        the source for new set of tables, created in the default locale of your         the source for new set of tables, created in the default locale of your
       C runtime system. (This method of replacing the tables does not work if       C  run-time  system. (This method of replacing the tables does not work
       you  are cross compiling, because dftables is run on the local host. If       if you are cross compiling, because dftables is run on the local  host.
       you need to create alternative tables when cross  compiling,  you  will       If you need to create alternative tables when cross compiling, you will
        have to do so "by hand".)         have to do so "by hand".)
   
   
 USING EBCDIC CODE  USING EBCDIC CODE
   
       PCRE  assumes  by  default that it will run in an environment where the       PCRE assumes by default that it will run in an  environment  where  the
       character code is ASCII (or Unicode, which is  a  superset  of  ASCII).       character  code  is  ASCII  (or Unicode, which is a superset of ASCII).
       This  is  the  case for most computer operating systems. PCRE can, how-       This is the case for most computer operating systems.  PCRE  can,  how-
        ever, be compiled to run in an EBCDIC environment by adding         ever, be compiled to run in an EBCDIC environment by adding
   
          --enable-ebcdic           --enable-ebcdic
   
        to the configure command. This setting implies --enable-rebuild-charta-         to the configure command. This setting implies --enable-rebuild-charta-
       bles.  You  should  only  use  it if you know that you are in an EBCDIC       bles. You should only use it if you know that  you  are  in  an  EBCDIC
       environment (for example,  an  IBM  mainframe  operating  system).  The       environment  (for  example,  an  IBM  mainframe  operating system). The
       --enable-ebcdic option is incompatible with --enable-utf8.       --enable-ebcdic option is incompatible with --enable-utf.
   
   
 PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT  PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT
Line 416  PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT Line 792  PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT
          --enable-pcregrep-libbz2           --enable-pcregrep-libbz2
   
        to the configure command. These options naturally require that the rel-         to the configure command. These options naturally require that the rel-
       evant libraries are installed on your system. Configuration  will  fail       evant  libraries  are installed on your system. Configuration will fail
        if they are not.         if they are not.
   
   
 PCREGREP BUFFER SIZE  PCREGREP BUFFER SIZE
   
       pcregrep  uses  an internal buffer to hold a "window" on the file it is       pcregrep uses an internal buffer to hold a "window" on the file  it  is
        scanning, in order to be able to output "before" and "after" lines when         scanning, in order to be able to output "before" and "after" lines when
       it  finds  a match. The size of the buffer is controlled by a parameter       it finds a match. The size of the buffer is controlled by  a  parameter
        whose default value is 20K. The buffer itself is three times this size,         whose default value is 20K. The buffer itself is three times this size,
        but because of the way it is used for holding "before" lines, the long-         but because of the way it is used for holding "before" lines, the long-
       est line that is guaranteed to be processable is  the  parameter  size.       est  line  that  is guaranteed to be processable is the paramete       est  line  that  is guaranteed to be processable is the paramete
        You can change the default parameter value by adding, for example,         You can change the default parameter value by adding, for example,
   
          --with-pcregrep-bufsize=50K           --with-pcregrep-bufsize=50K
Line 442  PCRETEST OPTION FOR LIBREADLINE SUPPORT Line 818  PCRETEST OPTION FOR LIBREADLINE SUPPORT
   
          --enable-pcretest-libreadline           --enable-pcretest-libreadline
   
       to the configure command,  pcretest  is  linked  with  the  libreadline       to  the  configure  command,  pcretest  is  linked with the libreadline
       library,  and  when its input is from a terminal, it reads it using the       library, and when its input is from a terminal, it reads it  using  the
        readline() function. This provides line-editing and history facilities.         readline() function. This provides line-editing and history facilities.
        Note that libreadline is GPL-licensed, so if you distribute a binary of         Note that libreadline is GPL-licensed, so if you distribute a binary of
        pcretest linked in this way, there may be licensing issues.         pcretest linked in this way, there may be licensing issues.
   
       Setting this option causes the -lreadline option to  be  added  to  the       Setting  this  option  causes  the -lreadline option to be added to the
       pcretest  build.  In many operating environments with a sytem-installed       pcretest build. In many operating environments with  a  sytem-installed
        libreadline this is sufficient. However, in some environments (e.g.  if         libreadline this is sufficient. However, in some environments (e.g.  if
       an  unmodified  distribution version of readline is in use), some extra       an unmodified distribution version of readline is in use),  some  extra
       configuration may be necessary. The INSTALL file for  libreadline  says       configuration  may  be necessary. The INSTALL file for libreadline says
        this:         this:
   
          "Readline uses the termcap functions, but does not link with the           "Readline uses the termcap functions, but does not link with the
          termcap or curses library itself, allowing applications which link           termcap or curses library itself, allowing applications which link
          with readline the to choose an appropriate library."           with readline the to choose an appropriate library."
   
       If  your environment has not been set up so that an appropriate library       If your environment has not been set up so that an appropriate  library
        is automatically included, you may need to add something like         is automatically included, you may need to add something like
   
          LIBS="-ncurses"           LIBS="-ncurses"
Line 469  PCRETEST OPTION FOR LIBREADLINE SUPPORT Line 845  PCRETEST OPTION FOR LIBREADLINE SUPPORT
   
 SEE ALSO  SEE ALSO
   
       pcreapi(3), pcre_config(3).       pcreapi(3), pcre16, pcre_config(3).
   
   
 AUTHOR  AUTHOR
Line 481  AUTHOR Line 857  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 06 September 2011       Last updated: 07 January 2012
       Copyright (c) 1997-2011 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 498  PCRE MATCHING ALGORITHMS Line 874  PCRE MATCHING ALGORITHMS
        This document describes the two different algorithms that are available         This document describes the two different algorithms that are available
        in PCRE for matching a compiled regular expression against a given sub-         in PCRE for matching a compiled regular expression against a given sub-
        ject  string.  The  "standard"  algorithm  is  the  one provided by the         ject  string.  The  "standard"  algorithm  is  the  one provided by the
       pcre_exec() function.  This works in the same was  as  Perl's  matching       pcre_exec() and pcre16_exec() functions. These work in the same was  as
       function, and provides a Perl-compatible matching operation.       Perl's matching function, and provide a Perl-compatible matching opera-
        tion. The just-in-time (JIT) optimization  that  is  described  in  the
        pcrejit documentation is compatible with these functions.
   
       An  alternative  algorithm is provided by the pcre_dfa_exec() function;       An  alternative  algorithm  is  provided  by  the  pcre_dfa_exec()  and
       this operates in a different way, and is not  Perl-compatible.  It  has       pcre16_dfa_exec() functions; they operate in a different way,  and  are
       advantages  and disadvantages compared with the standard algorithm, and       not  Perl-compatible. This alternative has advantages and disadvantages
       these are described below.       compared with the standard algorithm, and these are described below.
   
        When there is only one possible way in which a given subject string can         When there is only one possible way in which a given subject string can
        match  a pattern, the two algorithms give the same answer. A difference         match  a pattern, the two algorithms give the same answer. A difference
Line 632  THE ALTERNATIVE MATCHING ALGORITHM Line 1010  THE ALTERNATIVE MATCHING ALGORITHM
        6. Callouts are supported, but the value of the  capture_top  field  is         6. Callouts are supported, but the value of the  capture_top  field  is
        always 1, and the value of the capture_last field is always -1.         always 1, and the value of the capture_last field is always -1.
   
       7.  The \C escape sequence, which (in the standard algorithm) matches a       7.  The  \C  escape  sequence, which (in the standard algorithm) always
       single byte, even in UTF-8  mode,  is  not  supported  in  UTF-8  mode,       matches a single data unit, even in UTF-8 or UTF-16 modes, is not  sup-
       because  the alternative algorithm moves through the subject string one       ported  in these modes, because the alternative algorithm moves through
       character at a time, for all active paths through the tree.       the subject string one character (not data unit) at  a  time,  for  all
        active paths through the tree.
   
       8. Except for (*FAIL), the backtracking control verbs such as  (*PRUNE)       8.  Except for (*FAIL), the backtracking control verbs such as (*PRUNE)
       are  not  supported.  (*FAIL)  is supported, and behaves like a failing       are not supported. (*FAIL) is supported, and  behaves  like  a  failing
        negative assertion.         negative assertion.
   
   
 ADVANTAGES OF THE ALTERNATIVE ALGORITHM  ADVANTAGES OF THE ALTERNATIVE ALGORITHM
   
       Using the alternative matching algorithm provides the following  advan-       Using  the alternative matching algorithm provides the following advan-
        tages:         tages:
   
        1. All possible matches (at a single point in the subject) are automat-         1. All possible matches (at a single point in the subject) are automat-
       ically found, and in particular, the longest match is  found.  To  find       ically  found,  and  in particular, the longest match is found. To find
        more than one match using the standard algorithm, you have to do kludgy         more than one match using the standard algorithm, you have to do kludgy
        things with callouts.         things with callouts.
   
       2. Because the alternative algorithm  scans  the  subject  string  just       2.  Because  the  alternative  algorithm  scans the subject string just
       once,  and  never  needs to backtrack, it is possible to pass very long       once, and never needs to backtrack (except for lookbehinds), it is pos-
       subject strings to the matching function in  several  pieces,  checking       sible  to  pass  very  long subject strings to the matching function in
       for  partial  matching  each time. Although it is possible to do multi-       several pieces, checking for partial matching each time. Although it is
       segment matching using the standard algorithm (pcre_exec()), by retain-       possible  to  do multi-segment matching using the standard algorithm by
       ing  partially matched substrings, it is more complicated. The pcrepar-       retaining partially matched substrings, it  is  more  complicated.  The
       tial documentation gives details  of  partial  matching  and  discusses       pcrepartial  documentation  gives  details of partial matching and dis-
       multi-segment matching.       cusses multi-segment matching.
   
   
 DISADVANTAGES OF THE ALTERNATIVE ALGORITHM  DISADVANTAGES OF THE ALTERNATIVE ALGORITHM
   
        The alternative algorithm suffers from a number of disadvantages:         The alternative algorithm suffers from a number of disadvantages:
   
       1.  It  is  substantially  slower  than the standard algorithm. This is       1. It is substantially slower than  the  standard  algorithm.  This  is
       partly because it has to search for all possible matches, but  is  also       partly  because  it has to search for all possible matches, but is also
        because it is less susceptible to optimization.         because it is less susceptible to optimization.
   
        2. Capturing parentheses and back references are not supported.         2. Capturing parentheses and back references are not supported.
Line 685  AUTHOR Line 1064  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 19 November 2011       Last updated: 08 January 2012
       Copyright (c) 1997-2010 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 696  PCREAPI(3)                                             Line 1075  PCREAPI(3)                                            
 NAME  NAME
        PCRE - Perl-compatible regular expressions         PCRE - Perl-compatible regular expressions
   
          #include <pcre.h>
   
   
 PCRE NATIVE API BASIC FUNCTIONS  PCRE NATIVE API BASIC FUNCTIONS
   
        #include <pcre.h>  
   
        pcre *pcre_compile(const char *pattern, int options,         pcre *pcre_compile(const char *pattern, int options,
             const char **errptr, int *erroffset,              const char **errptr, int *erroffset,
             const unsigned char *tableptr);              const unsigned char *tableptr);
Line 719  PCRE NATIVE API BASIC FUNCTIONS Line 1098  PCRE NATIVE API BASIC FUNCTIONS
             const char *subject, int length, int startoffset,              const char *subject, int length, int startoffset,
             int options, int *ovector, int ovecsize);              int options, int *ovector, int ovecsize);
   
   
 PCRE NATIVE API AUXILIARY FUNCTIONS  
   
        pcre_jit_stack *pcre_jit_stack_alloc(int startsize, int maxsize);  
   
        void pcre_jit_stack_free(pcre_jit_stack *stack);  
   
        void pcre_assign_jit_stack(pcre_extra *extra,  
             pcre_jit_callback callback, void *data);  
   
        int pcre_dfa_exec(const pcre *code, const pcre_extra *extra,         int pcre_dfa_exec(const pcre *code, const pcre_extra *extra,
             const char *subject, int length, int startoffset,              const char *subject, int length, int startoffset,
             int options, int *ovector, int ovecsize,              int options, int *ovector, int ovecsize,
             int *workspace, int wscount);              int *workspace, int wscount);
   
   
   PCRE NATIVE API STRING EXTRACTION FUNCTIONS
   
        int pcre_copy_named_substring(const pcre *code,         int pcre_copy_named_substring(const pcre *code,
             const char *subject, int *ovector,              const char *subject, int *ovector,
             int stringcount, const char *stringname,              int stringcount, const char *stringname,
Line 765  PCRE NATIVE API AUXILIARY FUNCTIONS Line 1137  PCRE NATIVE API AUXILIARY FUNCTIONS
   
        void pcre_free_substring_list(const char **stringptr);         void pcre_free_substring_list(const char **stringptr);
   
   
   PCRE NATIVE API AUXILIARY FUNCTIONS
   
          pcre_jit_stack *pcre_jit_stack_alloc(int startsize, int maxsize);
   
          void pcre_jit_stack_free(pcre_jit_stack *stack);
   
          void pcre_assign_jit_stack(pcre_extra *extra,
               pcre_jit_callback callback, void *data);
   
        const unsigned char *pcre_maketables(void);         const unsigned char *pcre_maketables(void);
   
        int pcre_fullinfo(const pcre *code, const pcre_extra *extra,         int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
             int what, void *where);              int what, void *where);
   
        int pcre_info(const pcre *code, int *optptr, int *firstcharptr);  
   
        int pcre_refcount(pcre *code, int adjust);         int pcre_refcount(pcre *code, int adjust);
   
        int pcre_config(int what, void *where);         int pcre_config(int what, void *where);
   
       char *pcre_version(void);       const char *pcre_version(void);
   
          int pcre_pattern_to_host_byte_order(pcre *code,
               pcre_extra *extra, const unsigned char *tables);
   
   
 PCRE NATIVE API INDIRECTED FUNCTIONS  PCRE NATIVE API INDIRECTED FUNCTIONS
   
        void *(*pcre_malloc)(size_t);         void *(*pcre_malloc)(size_t);
Line 792  PCRE NATIVE API INDIRECTED FUNCTIONS Line 1175  PCRE NATIVE API INDIRECTED FUNCTIONS
        int (*pcre_callout)(pcre_callout_block *);         int (*pcre_callout)(pcre_callout_block *);
   
   
   PCRE 8-BIT AND 16-BIT LIBRARIES
   
          From  release  8.30,  PCRE  can  be  compiled as a library for handling
          16-bit character strings as  well  as,  or  instead  of,  the  original
          library that handles 8-bit character strings. To avoid too much compli-
          cation, this document describes the 8-bit versions  of  the  functions,
          with only occasional references to the 16-bit library.
   
          The  16-bit  functions  operate in the same way as their 8-bit counter-
          parts; they just use different  data  types  for  their  arguments  and
          results, and their names start with pcre16_ instead of pcre_. For every
          option that has UTF8 in its name (for example, PCRE_UTF8), there  is  a
          corresponding 16-bit name with UTF8 replaced by UTF16. This facility is
          in fact just cosmetic; the 16-bit option names define the same bit val-
          ues.
   
          References to bytes and UTF-8 in this document should be read as refer-
          ences to 16-bit data  quantities  and  UTF-16  when  using  the  16-bit
          library,  unless specified otherwise. More details of the specific dif-
          ferences for the 16-bit library are given in the pcre16 page.
   
   
 PCRE API OVERVIEW  PCRE API OVERVIEW
   
        PCRE has its own native API, which is described in this document. There         PCRE has its own native API, which is described in this document. There
       are also some wrapper functions that correspond to  the  POSIX  regular       are  also some wrapper functions (for the 8-bit library only) that cor-
       expression  API,  but they do not give access to all the functionality.       respond to the POSIX regular expression  API,  but  they  do  not  give
       They are described in the pcreposix documentation. Both of  these  APIs       access  to  all  the functionality. They are described in the pcreposix
       define  a  set  of  C function calls. A C++ wrapper is also distributed       documentation. Both of these APIs define a set of C function  calls.  A
       with PCRE. It is documented in the pcrecpp page.       C++ wrapper (again for the 8-bit library only) is also distributed with
        PCRE. It is documented in the pcrecpp page.
   
        The native API C function prototypes are defined  in  the  header  file         The native API C function prototypes are defined  in  the  header  file
       pcre.h,  and  on Unix systems the library itself is called libpcre.  It       pcre.h,  and  on Unix-like systems the (8-bit) library itself is called
       can normally be accessed by adding -lpcre to the command for linking an       libpcre. It can normally be accessed by adding -lpcre  to  the  command
       application  that  uses  PCRE.  The  header  file  defines  the  macros       for  linking an application that uses PCRE. The header file defines the
       PCRE_MAJOR and PCRE_MINOR to contain the major and minor  release  num-       macros PCRE_MAJOR and PCRE_MINOR to contain the major and minor release
       bers  for  the  library.  Applications can use these to include support       numbers  for the library. Applications can use these to include support
        for different releases of PCRE.         for different releases of PCRE.
   
        In a Windows environment, if you want to statically link an application         In a Windows environment, if you want to statically link an application
Line 865  PCRE API OVERVIEW Line 1271  PCRE API OVERVIEW
        built are used.         built are used.
   
        The  function  pcre_fullinfo()  is used to find out information about a         The  function  pcre_fullinfo()  is used to find out information about a
       compiled pattern; pcre_info() is an obsolete version that returns  only       compiled pattern. The function pcre_version() returns a  pointer  to  a
       some  of  the available information, but is retained for backwards com-       string containing the version of PCRE and its date of release.
       patibility.  The function pcre_version() returns a pointer to a  string 
       containing the version of PCRE and its date of release. 
   
        The  function  pcre_refcount()  maintains  a  reference count in a data         The  function  pcre_refcount()  maintains  a  reference count in a data
        block containing a compiled pattern. This is provided for  the  benefit         block containing a compiled pattern. This is provided for  the  benefit
Line 907  NEWLINES Line 1311  NEWLINES
        feed) character, the two-character sequence CRLF, any of the three pre-         feed) character, the two-character sequence CRLF, any of the three pre-
        ceding,  or any Unicode newline sequence. The Unicode newline sequences         ceding,  or any Unicode newline sequence. The Unicode newline sequences
        are the three just mentioned, plus the single characters  VT  (vertical         are the three just mentioned, plus the single characters  VT  (vertical
       tab,  U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS (line       tab, U+000B), FF (form feed, U+000C), NEL (next line, U+0085), LS (line
        separator, U+2028), and PS (paragraph separator, U+2029).         separator, U+2028), and PS (paragraph separator, U+2029).
   
        Each of the first three conventions is used by at least  one  operating         Each of the first three conventions is used by at least  one  operating
Line 955  SAVING PRECOMPILED PATTERNS FOR LATER USE Line 1359  SAVING PRECOMPILED PATTERNS FOR LATER USE
        The compiled form of a regular expression can be saved and re-used at a         The compiled form of a regular expression can be saved and re-used at a
        later  time,  possibly by a different program, and even on a host other         later  time,  possibly by a different program, and even on a host other
        than the one on which  it  was  compiled.  Details  are  given  in  the         than the one on which  it  was  compiled.  Details  are  given  in  the
       pcreprecompile  documentation.  However, compiling a regular expression       pcreprecompile  documentation,  which  includes  a  description  of the
       with one version of PCRE for use with a different version is not  guar-       pcre_pattern_to_host_byte_order() function. However, compiling a  regu-
       anteed to work and may cause crashes.       lar  expression  with one version of PCRE for use with a different ver-
        sion is not guaranteed to work and may cause crashes.
   
   
 CHECKING BUILD-TIME OPTIONS  CHECKING BUILD-TIME OPTIONS
   
        int pcre_config(int what, void *where);         int pcre_config(int what, void *where);
   
       The  function pcre_config() makes it possible for a PCRE client to dis-       The function pcre_config() makes it possible for a PCRE client to  dis-
        cover which optional features have been compiled into the PCRE library.         cover which optional features have been compiled into the PCRE library.
       The  pcrebuild documentation has more details about these optional fea-       The pcrebuild documentation has more details about these optional  fea-
        tures.         tures.
   
       The first argument for pcre_config() is an  integer,  specifying  which       The  first  argument  for pcre_config() is an integer, specifyin       The  first  argument  for pcre_config() is an integer, specifyin
        information is required; the second argument is a pointer to a variable         information is required; the second argument is a pointer to a variable
       into which the information is  placed.  The  following  information  is       into  which  the  information  is placed. The returned value is zero on
        success, or the negative error code PCRE_ERROR_BADOPTION if  the  value
        in  the  first argument is not recognized. The following information is
        available:         available:
   
          PCRE_CONFIG_UTF8           PCRE_CONFIG_UTF8
   
       The  output is an integer that is set to one if UTF-8 support is avail-       The output is an integer that is set to one if UTF-8 support is  avail-
       able; otherwise it is set to zero.       able;  otherwise  it  is  set  to  zero. If this option is given to the
        16-bit  version  of  this  function,  pcre16_config(),  the  result  is
        PCRE_ERROR_BADOPTION.
   
            PCRE_CONFIG_UTF16
   
          The output is an integer that is set to one if UTF-16 support is avail-
          able; otherwise it is set to zero. This value should normally be  given
          to the 16-bit version of this function, pcre16_config(). If it is given
          to the 8-bit version of this function, the result is  PCRE_ERROR_BADOP-
          TION.
   
          PCRE_CONFIG_UNICODE_PROPERTIES           PCRE_CONFIG_UNICODE_PROPERTIES
   
       The output is an integer that is set to  one  if  support  for  Unicode       The  output  is  an  integer  that is s       The  output  is  an  integer  that is set to one if support for Unicode
        character properties is available; otherwise it is set to zero.         character properties is available; otherwise it is set to zero.
   
          PCRE_CONFIG_JIT           PCRE_CONFIG_JIT
Line 989  CHECKING BUILD-TIME OPTIONS Line 1406  CHECKING BUILD-TIME OPTIONS
        The output is an integer that is set to one if support for just-in-time         The output is an integer that is set to one if support for just-in-time
        compiling is available; otherwise it is set to zero.         compiling is available; otherwise it is set to zero.
   
            PCRE_CONFIG_JITTARGET
   
          The  output is a pointer to a zero-terminated "const char *" string. If
          JIT support is available, the string contains the name of the architec-
          ture  for  which the JIT compiler is configured, for example "x86 32bit
          (little endian + unaligned)". If JIT  support  is  not  available,  the
          result is NULL.
   
          PCRE_CONFIG_NEWLINE           PCRE_CONFIG_NEWLINE
   
       The output is an integer whose value specifies  the  default  character       The  output  is  an integer whose value specifies the default character
       sequence  that is recognized as meaning "newline". The four values that       sequence that is recognized as meaning "newline". The four values  that
        are supported are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF,         are supported are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF,
       and  -1  for  ANY.  Though they are derived from ASCII, the same values       and -1 for ANY.  Though they are derived from ASCII,  the  same  values
        are returned in EBCDIC environments. The default should normally corre-         are returned in EBCDIC environments. The default should normally corre-
        spond to the standard sequence for your operating system.         spond to the standard sequence for your operating system.
   
          PCRE_CONFIG_BSR           PCRE_CONFIG_BSR
   
        The output is an integer whose value indicates what character sequences         The output is an integer whose value indicates what character sequences
       the \R escape sequence matches by default. A value of 0 means  that  \R       the  \R  escape sequence matches by default. A value of 0 means that \R
       matches  any  Unicode  line ending sequence; a value of 1 means that \R       matches any Unicode line ending sequence; a value of 1  means  that  \R
        matches only CR, LF, or CRLF. The default can be overridden when a pat-         matches only CR, LF, or CRLF. The default can be overridden when a pat-
        tern is compiled or matched.         tern is compiled or matched.
   
          PCRE_CONFIG_LINK_SIZE           PCRE_CONFIG_LINK_SIZE
   
       The  output  is  an  integer that contains the number of bytes used for       The output is an integer that contains the number  of  bytes  used  for
       internal linkage in compiled regular expressions. The value is 2, 3, or       internal  linkage  in  compiled  regular  expressions.  For  the  8-bit
       4.  Larger  values  allow larger regular expressions to be compiled, at       library, the value can be 2, 3, or 4. For the 16-bit library, the value
       the expense of slower matching. The default value of  2  is  sufficient       is either 2 or 4 and is still a number of bytes. The default value of 2
       for  all  but  the  most massive patterns, since it allows the compiled       is sufficient for all but the most massive patterns,  since  it  allows
       pattern to be up to 64K in size.       the  compiled  pattern  to  be  up to 64K in size.  Larger values allow
        larger regular expressions to be compiled, at  the  expense  of  slower
        matching.
   
          PCRE_CONFIG_POSIX_MALLOC_THRESHOLD           PCRE_CONFIG_POSIX_MALLOC_THRESHOLD
   
       The output is an integer that contains the threshold  above  which  the       The  output  is  an integer that contains the threshold above which the
       POSIX  interface  uses malloc() for output vectors. Further details are       POSIX interface uses malloc() for output vectors. Further  details  are
        given in the pcreposix documentation.         given in the pcreposix documentation.
   
          PCRE_CONFIG_MATCH_LIMIT           PCRE_CONFIG_MATCH_LIMIT
   
       The output is a long integer that gives the default limit for the  num-       The  output is a long integer that gives the default limit for the num-
       ber  of  internal  matching  function calls in a pcre_exec() execution.       ber of internal matching function calls  in  a  pcre_exec()  execution.
        Further details are given with pcre_exec() below.         Further details are given with pcre_exec() below.
   
          PCRE_CONFIG_MATCH_LIMIT_RECURSION           PCRE_CONFIG_MATCH_LIMIT_RECURSION
   
        The output is a long integer that gives the default limit for the depth         The output is a long integer that gives the default limit for the depth
       of   recursion  when  calling  the  internal  matching  function  in  a       of  recursion  when  calling  the  internal  matching  function  in   a
       pcre_exec() execution.  Further  details  are  given  with  pcre_exec()       pcre_exec()  execution.  Further  details  are  given  with pcre_exec()
        below.         below.
   
          PCRE_CONFIG_STACKRECURSE           PCRE_CONFIG_STACKRECURSE
   
       The  output is an integer that is set to one if internal recursion when       The output is an integer that is set to one if internal recursion  when
        running pcre_exec() is implemented by recursive function calls that use         running pcre_exec() is implemented by recursive function calls that use
       the  stack  to remember their state. This is the usual way that PCRE is       the stack to remember their state. This is the usual way that  PCRE  is
        compiled. The output is zero if PCRE was compiled to use blocks of data         compiled. The output is zero if PCRE was compiled to use blocks of data
       on  the  heap  instead  of  recursive  function  calls.  In  this case,       on the  heap  instead  of  recursive  function  calls.  In  this  case,
       pcre_stack_malloc and  pcre_stack_free  are  called  to  manage  memory       pcre_stack_malloc  and  pcre_stack_free  are  called  to  manage memory
        blocks on the heap, thus avoiding the use of the stack.         blocks on the heap, thus avoiding the use of the stack.
   
   
Line 1058  COMPILING A PATTERN Line 1485  COMPILING A PATTERN
   
        Either of the functions pcre_compile() or pcre_compile2() can be called         Either of the functions pcre_compile() or pcre_compile2() can be called
        to compile a pattern into an internal form. The only difference between         to compile a pattern into an internal form. The only difference between
       the  two interfaces is that pcre_compile2() has an additional argument,       the two interfaces is that pcre_compile2() has an additional  argument,
       errorcodeptr, via which a numerical error  code  can  be  returned.  To       errorcodeptr,  via  which  a  numerical  error code can be returned. To
       avoid  too  much repetition, we refer just to pcre_compile() below, but       avoid too much repetition, we refer just to pcre_compile()  below,  but
        the information applies equally to pcre_compile2().         the information applies equally to pcre_compile2().
   
        The pattern is a C string terminated by a binary zero, and is passed in         The pattern is a C string terminated by a binary zero, and is passed in
       the  pattern  argument.  A  pointer to a single block of memory that is       the pattern argument. A pointer to a single block  of  memory  that  is
       obtained via pcre_malloc is returned. This contains the  compiled  code       obtained  via  pcre_malloc is returned. This contains the compiled code
        and related data. The pcre type is defined for the returned block; this         and related data. The pcre type is defined for the returned block; this
        is a typedef for a structure whose contents are not externally defined.         is a typedef for a structure whose contents are not externally defined.
        It is up to the caller to free the memory (via pcre_free) when it is no         It is up to the caller to free the memory (via pcre_free) when it is no
        longer required.         longer required.
   
       Although the compiled code of a PCRE regex is relocatable, that is,  it       Although  the compiled code of a PCRE regex is relocatable, that is, it
        does not depend on memory location, the complete pcre data block is not         does not depend on memory location, the complete pcre data block is not
       fully relocatable, because it may contain a copy of the tableptr  argu-       fully  relocatable, because it may contain a copy of the tableptr argu-
        ment, which is an address (see below).         ment, which is an address (see below).
   
        The options argument contains various bit settings that affect the com-         The options argument contains various bit settings that affect the com-
       pilation. It should be zero if no options are required.  The  available       pilation.  It  should be zero if no options are required. The available
       options  are  described  below. Some of them (in particular, those that       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       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       unset from within the pattern (see  the  detailed  description  in  the
       pcrepattern documentation). For those options that can be different  in       pcrepattern  documentation). For those options that can be different in
       different  parts  of  the pattern, the contents of the options argument       different parts of the pattern, the contents of  the  options  argument
        specifies their settings at the start of compilation and execution. The         specifies their settings at the start of compilation and execution. The
       PCRE_ANCHORED,  PCRE_BSR_xxx, PCRE_NEWLINE_xxx, PCRE_NO_UTF8_CHECK, and       PCRE_ANCHORED, PCRE_BSR_xxx, PCRE_NEWLINE_xxx, PCRE_NO_UTF8_CHECK,  and
       PCRE_NO_START_OPT options can be set at the time of matching as well as       PCRE_NO_START_OPTIMIZE  options  can  be set at the time of matching as
       at compile time.       well as at compile time.
   
        If errptr is NULL, pcre_compile() returns NULL immediately.  Otherwise,         If errptr is NULL, pcre_compile() returns NULL immediately.  Otherwise,
       if compilation of a pattern fails,  pcre_compile()  returns  NULL,  and       if  compilation  of  a  pattern fails, pcre_compile() retur       if  compilation  of  a  pattern fails, pcre_compile() retur
        sets the variable pointed to by errptr to point to a textual error mes-         sets the variable pointed to by errptr to point to a textual error mes-
        sage. This is a static string that is part of the library. You must not         sage. This is a static string that is part of the library. You must not
       try  to  free it. Normally, the offset from the start of the pattern to       try to free it. Normally, the offset from the start of the  pattern  to
       the byte that was being processed when  the  error  was  discovered  is       the  byte  that  was  being  processed when the error was discovered is
       placed  in the variable pointed to by erroffset, which must not be NULL       placed in the variable pointed to by erroffset, which must not be  NULL
       (if it is, an immediate error is given). However, for an invalid  UTF-8       (if  it is, an immediate error is given). However, for an invalid UTF-8
       string,  the offset is that of the first byte of the failing character.       string, the offset is that of the first byte of the failing character.
       Also, some errors are not detected until checks are  carried  out  when 
       the  whole  pattern  has been scanned; in these cases the offset passed 
       back is the length of the pattern. 
   
          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 bytes, not characters, even in  UTF-8  mode.         Note that the offset is in bytes, not characters, even in  UTF-8  mode.
        It may sometimes point into the middle of a UTF-8 character.         It may sometimes point into the middle of a UTF-8 character.
   
Line 1199  COMPILING A PATTERN Line 1625  COMPILING A PATTERN
   
          PCRE_EXTENDED           PCRE_EXTENDED
   
       If  this  bit  is  set,  whitespace  data characters in the pattern are       If  this  bit  is  set,  white space data characters in the pattern are
       totally ignored except when escaped or inside a character class. White-       totally ignored except when escaped or inside a character class.  White
        space does not include the VT character (code 11). In addition, charac-         space does not include the VT character (code 11). In addition, charac-
        ters between an unescaped # outside a character class and the next new-         ters between an unescaped # outside a character class and the next new-
        line,  inclusive,  are  also  ignored.  This is equivalent to Perl's /x         line,  inclusive,  are  also  ignored.  This is equivalent to Perl's /x
Line 1216  COMPILING A PATTERN Line 1642  COMPILING A PATTERN
   
        This option makes it possible to include  comments  inside  complicated         This option makes it possible to include  comments  inside  complicated
        patterns.   Note,  however,  that this applies only to data characters.         patterns.   Note,  however,  that this applies only to data characters.
       Whitespace  characters  may  never  appear  within  special   character       White space  characters  may  never  appear  within  special  character
        sequences in a pattern, for example within the sequence (?( that intro-         sequences in a pattern, for example within the sequence (?( that intro-
        duces a conditional subpattern.         duces a conditional subpattern.
   
Line 1301  COMPILING A PATTERN Line 1727  COMPILING A PATTERN
        that any of the three preceding sequences should be recognized. Setting         that any of the three preceding sequences should be recognized. Setting
        PCRE_NEWLINE_ANY  specifies that any Unicode newline sequence should be         PCRE_NEWLINE_ANY  specifies that any Unicode newline sequence should be
        recognized. The Unicode newline sequences are the three just mentioned,         recognized. The Unicode newline sequences are the three just mentioned,
       plus  the  single  characters  VT (vertical tab, U+000B), FF (formfeed,       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         U+000C), NEL (next line, U+0085), LS (line separator, U+2028),  and  PS
       (paragraph  separator,  U+2029).  The  last  two are recognized only in       (paragraph  separator, U+2029). For the 8-bit library, the last two are
       UTF-8 mode.       recognized only in UTF-8 mode.
   
        The newline setting in the  options  word  uses  three  bits  that  are         The newline setting in the  options  word  uses  three  bits  that  are
        treated as a number, giving eight possibilities. Currently only six are         treated as a number, giving eight possibilities. Currently only six are
Line 1315  COMPILING A PATTERN Line 1741  COMPILING A PATTERN
        cause an error.         cause an error.
   
        The only time that a line break in a pattern  is  specially  recognized         The only time that a line break in a pattern  is  specially  recognized
       when  compiling  is when PCRE_EXTENDED is set. CR and LF are whitespace       when  compiling is when PCRE_EXTENDED is set. CR and LF are white space
        characters, and so are ignored in this mode. Also, an unescaped #  out-         characters, and so are ignored in this mode. Also, an unescaped #  out-
        side  a  character class indicates a comment that lasts until after the         side  a  character class indicates a comment that lasts until after the
        next line break sequence. In other circumstances, line break  sequences         next line break sequence. In other circumstances, line break  sequences
Line 1361  COMPILING A PATTERN Line 1787  COMPILING A PATTERN
          PCRE_UTF8           PCRE_UTF8
   
        This option causes PCRE to regard both the pattern and the  subject  as         This option causes PCRE to regard both the pattern and the  subject  as
       strings  of  UTF-8 characters instead of single-byte character strings.       strings of UTF-8 characters instead of single-byte strings. However, it
       However, it is available only when PCRE is built to include UTF-8  sup-       is available only when PCRE is built to include UTF  support.  If  not,
       port.  If not, the use of this option provokes an error. Details of how       the  use  of  this option provokes an error. Details of how this option
       this option changes the behaviour of PCRE are given in the  pcreunicode       changes the behaviour of PCRE are given in the pcreunicode page.
       page. 
   
          PCRE_NO_UTF8_CHECK           PCRE_NO_UTF8_CHECK
   
        When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is         When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is
       automatically checked. There is a  discussion  about  the  validity  of       automatically  checked.  There  is  a  discussion about the validity of
       UTF-8  strings  in  the main pcre page. If an invalid UTF-8 sequence of       UTF-8 strings in the pcreunicode page. If an invalid UTF-8 sequence  is
       bytes is found, pcre_compile() returns an error. If  you  already  know       found,  pcre_compile()  returns an error. If you already know that your
       that your pattern is valid, and you want to skip this check for perfor-       pattern is valid, and you want to skip this check for performance  rea-
       mance reasons, you can set the PCRE_NO_UTF8_CHECK option.  When  it  is       sons,  you  can set the PCRE_NO_UTF8_CHECK option.  When it is set, the
       set,  the  effect  of  passing  an invalid UTF-8 string as a pattern is       effect of passing an invalid UTF-8 string as a pattern is undefined. It
       undefined. It may cause your program to crash. Note  that  this  option       may  cause  your  program  to  crash. Note that this option can also be
       can  also be passed to pcre_exec() and pcre_dfa_exec(), to suppress the       passed to pcre_exec() and pcre_dfa_exec(),  to  suppress  the  validity
       UTF-8 validity checking of subject strings.       checking of subject strings.
   
   
 COMPILATION ERROR CODES  COMPILATION ERROR CODES
   
       The following table lists the error  codes  than  may  be  returned  by       The  following  table  lists  the  error  codes than may be returned by
       pcre_compile2(),  along with the error messages that may be returned by       pcre_compile2(), along with the error messages that may be returned  by
       both compiling functions. As PCRE has developed, some error codes  have       both  compiling  functions.  Note  that error messages are always 8-bit
       fallen out of use. To avoid confusion, they have not been re-used.       ASCII strings, even in 16-bit mode. As PCRE has developed,  some  error
        codes  have  fallen  out of use. To avoid confusion, they have not been
        re-used.
   
           0  no error            0  no error
           1  \ at end of pattern            1  \ at end of pattern
Line 1420  COMPILATION ERROR CODES Line 1847  COMPILATION ERROR CODES
          29  (?R or (?[+-]digits must be followed by )           29  (?R or (?[+-]digits must be followed by )
          30  unknown POSIX class name           30  unknown POSIX class name
          31  POSIX collating elements are not supported           31  POSIX collating elements are not supported
         32  this version of PCRE is not compiled with PCRE_UTF8 support         32  this version of PCRE is compiled without UTF support
          33  [this code is not in use]           33  [this code is not in use]
          34  character value in \x{...} sequence is too large           34  character value in \x{...} sequence is too large
          35  invalid condition (?(0)           35  invalid condition (?(0)
Line 1432  COMPILATION ERROR CODES Line 1859  COMPILATION ERROR CODES
          41  unrecognized character after (?P           41  unrecognized character after (?P
          42  syntax error in subpattern name (missing terminator)           42  syntax error in subpattern name (missing terminator)
          43  two named subpatterns have the same name           43  two named subpatterns have the same name
         44  invalid UTF-8 string         44  invalid UTF-8 string (specifically UTF-8)
          45  support for \P, \p, and \X has not been compiled           45  support for \P, \p, and \X has not been compiled
          46  malformed \P or \p sequence           46  malformed \P or \p sequence
          47  unknown property name after \P or \p           47  unknown property name after \P or \p
          48  subpattern name is too long (maximum 32 characters)           48  subpattern name is too long (maximum 32 characters)
          49  too many named subpatterns (maximum 10000)           49  too many named subpatterns (maximum 10000)
          50  [this code is not in use]           50  [this code is not in use]
         51  octal value is greater than \377 (not in UTF-8 mode)         51  octal value is greater than \377 in 8-bit non-UTF-8 mode
          52  internal error: overran compiling workspace           52  internal error: overran compiling workspace
          53  internal error: previously-checked referenced subpattern           53  internal error: previously-checked referenced subpattern
                not found                 not found
Line 1458  COMPILATION ERROR CODES Line 1885  COMPILATION ERROR CODES
          65  different names for subpatterns of the same number are           65  different names for subpatterns of the same number are
                not allowed                 not allowed
          66  (*MARK) must have an argument           66  (*MARK) must have an argument
         67  this version of PCRE is not compiled with PCRE_UCP support         67  this version of PCRE is not compiled with Unicode property
                support
          68  \c must be followed by an ASCII character           68  \c must be followed by an ASCII character
          69  \k is not followed by a braced, angle-bracketed, or quoted name           69  \k is not followed by a braced, angle-bracketed, or quoted name
            70  internal error: unknown opcode in find_fixedlength()
            71  \N is not supported in a class
            72  too many forward references
            73  disallowed Unicode code point (>= 0xd800 && <= 0xdfff)
            74  invalid UTF-16 string (specifically UTF-16)
            75  name is too long in (*MARK), (*PRUNE), (*SKIP), or (*THEN)
            76  character value in \u.... sequence is too large
   
       The  numbers  32  and 10000 in errors 48 and 49 are defaults; different       The numbers 32 and 10000 in errors 48 and 49  are  defaults;  different
        values may be used if the limits were changed when PCRE was built.         values may be used if the limits were changed when PCRE was built.
   
   
Line 1471  STUDYING A PATTERN Line 1906  STUDYING A PATTERN
        pcre_extra *pcre_study(const pcre *code, int options         pcre_extra *pcre_study(const pcre *code, int options
             const char **errptr);              const char **errptr);
   
       If a compiled pattern is going to be used several times,  it  is  worth       If  a  compiled  pattern is going to be used several times, it is worth
        spending more time analyzing it in order to speed up the time taken for         spending more time analyzing it in order to speed up the time taken for
       matching. The function pcre_study() takes a pointer to a compiled  pat-       matching.  The function pcre_study() takes a pointer to a compiled pat-
        tern as its first argument. If studying the pattern produces additional         tern as its first argument. If studying the pattern produces additional
       information that will help speed up matching,  pcre_study()  returns  a       information  that  will  help speed up matching, pcre_study() returns a
       pointer  to a pcre_extra block, in which the study_data field points to       pointer to a pcre_extra block, in which the study_data field points  to
        the results of the study.         the results of the study.
   
        The  returned  value  from  pcre_study()  can  be  passed  directly  to         The  returned  value  from  pcre_study()  can  be  passed  directly  to
       pcre_exec()  or  pcre_dfa_exec(). However, a pcre_extra block also con-       pcre_exec() or pcre_dfa_exec(). However, a pcre_extra block  also  con-
       tains other fields that can be set by the caller before  the  block  is       tains  other  fields  that can be set by the caller before the block is
        passed; these are described below in the section on matching a pattern.         passed; these are described below in the section on matching a pattern.
   
       If  studying  the  pattern  does  not  produce  any useful information,       If studying the  pattern  does  not  produce  any  useful  information,
        pcre_study() returns NULL. In that circumstance, if the calling program         pcre_study() returns NULL. In that circumstance, if the calling program
       wants   to   pass   any   of   the   other  fields  to  pcre_exec()  or       wants  to  pass  any  of   the   other   fields   to   pcre_exec()   or
        pcre_dfa_exec(), it must set up its own pcre_extra block.         pcre_dfa_exec(), it must set up its own pcre_extra block.
   
       The second argument of pcre_study() contains option bits. There is only       The  second  argument  of  pcre_study() contains option bits. There are
       one  option:  PCRE_STUDY_JIT_COMPILE.  If this is set, and the just-in-       three options:
       time compiler is  available,  the  pattern  is  further  compiled  into 
       machine  code  that  executes much faster than the pcre_exec() matching 
       function. If the just-in-time compiler is not available, this option is 
       ignored. All other bits in the options argument must be zero. 
   
       JIT  compilation  is  a heavyweight optimization. It can take some time         PCRE_STUDY_JIT_COMPILE
       for patterns to be analyzed, and for one-off matches  and  simple  pat-         PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE
       terns  the benefit of faster execution might be offset by a much slower         PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE
 
        If any of these are set, and the just-in-time  compiler  is  available,
        the  pattern  is  further compiled into machine code that executes much
        faster than the pcre_exec()  interpretive  matching  function.  If  the
        just-in-time  compiler is not available, these options are ignored. All
        other bits in the options argument must be zero.
 
        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
        study time.  Not all patterns can be optimized by the JIT compiler. For         study time.  Not all patterns can be optimized by the JIT compiler. For
       those  that cannot be handled, matching automatically falls back to the       those that cannot be handled, matching automatically falls back to  the
       pcre_exec() interpreter. For more details, see the  pcrejit  documenta-       pcre_exec()  interpreter.  For more details, see the pcrejit documenta-
        tion.         tion.
   
       The  third argument for pcre_study() is a pointer for an error message.       The third argument for pcre_study() is a pointer for an error  message.
       If studying succeeds (even if no data is  returned),  the  variable  it       If  studying  succeeds  (even  if no data is returned), the variable it
       points  to  is  set  to NULL. Otherwise it is set to point to a textual       points to is set to NULL. Otherwise it is set to  point  to  a  textual
        error message. This is a static string that is part of the library. You         error message. This is a static string that is part of the library. You
       must  not  try  to  free it. You should test the error pointer for NULL       must not try to free it. You should test the  error  pointer  for  NULL
        after calling pcre_study(), to be sure that it has run successfully.         after calling pcre_study(), to be sure that it has run successfully.
   
       When you are finished with a pattern, you can free the memory used  for       When  you are finished with a pattern, you can free the memory used for
        the study data by calling pcre_free_study(). This function was added to         the study data by calling pcre_free_study(). This function was added to
       the API for release 8.20. For earlier versions,  the  memory  could  be       the  API  for  release  8.20. For earlier versions, the memory could be
       freed  with  pcre_free(), just like the pattern itself. This will still       freed with pcre_free(), just like the pattern itself. This  will  still
       work in cases where PCRE_STUDY_JIT_COMPILE  is  not  used,  but  it  is       work  in  cases where JIT optimization is not used, but it is advisable
       advisable to change to the new function when convenient.       to change to the new function when convenient.
   
       This  is  a typical way in which pcre_study() is used (except that in a       This is a typical way in which pcre_study() is used (except that  in  a
        real application there should be tests for errors):         real application there should be tests for errors):
   
          int rc;           int rc;
Line 1538  STUDYING A PATTERN Line 1979  STUDYING A PATTERN
        Studying a pattern does two things: first, a lower bound for the length         Studying a pattern does two things: first, a lower bound for the length
        of subject string that is needed to match the pattern is computed. This         of subject string that is needed to match the pattern is computed. This
        does not mean that there are any strings of that length that match, but         does not mean that there are any strings of that length that match, but
       it  does  guarantee that no shorter strings match. The value is used by       it does guarantee that no shorter strings match. The value is  used  by
       pcre_exec() and pcre_dfa_exec() to avoid  wasting  time  by  trying  to       pcre_exec()  and  pcre_dfa_exec()  to  avoid  wasting time by trying to
       match  strings  that are shorter than the lower bound. You can find out       match strings that are shorter than the lower bound. You can  find  out
        the value in a calling program via the pcre_fullinfo() function.         the value in a calling program via the pcre_fullinfo() function.
   
        Studying a pattern is also useful for non-anchored patterns that do not         Studying a pattern is also useful for non-anchored patterns that do not
       have  a  single fixed starting character. A bitmap of possible starting       have a single fixed starting character. A bitmap of  possible  starting
       bytes is created. This speeds up finding a position in the  subject  at       bytes  is  created. This speeds up finding a position in the subject at
       which to start matching.       which to start matching. (In 16-bit mode, the bitmap is used for 16-bit
        values less than 256.)
   
       These  two optimizations apply to both pcre_exec() and pcre_dfa_exec().       These  two optimizations apply to both pcre_exec() and pcre_dfa_exec(),
       However, they are not used by pcre_exec()  if  pcre_study()  is  called       and the information is also used by the JIT  compiler.   The  optimiza-
       with  the  PCRE_STUDY_JIT_COMPILE option, and just-in-time compiling is       tions can be disabled by setting the PCRE_NO_START_OPTIMIZE option when
       successful.  The  optimizations  can  be  disabled   by   setting   the       calling pcre_exec() or pcre_dfa_exec(), but if this is done, JIT execu-
       PCRE_NO_START_OPTIMIZE    option    when    calling    pcre_exec()   or       tion  is  also disabled. You might want to do this if your pattern con-
       pcre_dfa_exec(). You might want to do this  if  your  pattern  contains       tains callouts or (*MARK) and you want to make use of these  facilities
       callouts  or (*MARK) (which cannot be handled by the JIT compiler), and       in    cases    where    matching   fails.   See   the   discussion   of
       you want to make use of these facilities in cases where matching fails.       PCRE_NO_START_OPTIMIZE below.
       See the discussion of PCRE_NO_START_OPTIMIZE below. 
   
   
 LOCALE SUPPORT  LOCALE SUPPORT
   
       PCRE  handles  caseless matching, and determines whether characters are       PCRE handles caseless matching, and determines whether  characters  are
       letters, digits, or whatever, by reference to a set of tables,  indexed       letters,  digits, or whatever, by reference to a set of tables, indexed
       by  character  value.  When running in UTF-8 mode, this applies only to       by character value. When running in UTF-8 mode, this  applies  only  to
       characters with codes less than 128. By  default,  higher-valued  codes       characters  with  codes  less than 128. By default, higher-valued codes
        never match escapes such as \w or \d, but they can be tested with \p if         never match escapes such as \w or \d, but they can be tested with \p if
       PCRE is built with Unicode character property  support.  Alternatively,       PCRE  is  built with Unicode character property support. Alternatively,
       the  PCRE_UCP  option  can  be  set at compile time; this causes \w and       the PCRE_UCP option can be set at compile  time;  this  causes  \w  and
        friends to use Unicode property support instead of built-in tables. The         friends to use Unicode property support instead of built-in tables. The
        use of locales with Unicode is discouraged. If you are handling charac-         use of locales with Unicode is discouraged. If you are handling charac-
       ters with codes greater than 128, you should either use UTF-8 and  Uni-       ters  with codes greater than 128, you should either use UTF-8 and Uni-
        code, or use locales, but not try to mix the two.         code, or use locales, but not try to mix the two.
   
       PCRE  contains  an  internal set of tables that are used when the final       PCRE contains an internal set of tables that are used  when  the  final
       argument of pcre_compile() is  NULL.  These  are  sufficient  for  many       argument  of  pcre_compile()  is  NULL.  These  are sufficient for many
        applications.  Normally, the internal tables recognize only ASCII char-         applications.  Normally, the internal tables recognize only ASCII char-
        acters. However, when PCRE is built, it is possible to cause the inter-         acters. However, when PCRE is built, it is possible to cause the inter-
        nal tables to be rebuilt in the default "C" locale of the local system,         nal tables to be rebuilt in the default "C" locale of the local system,
        which may cause them to be different.         which may cause them to be different.
   
       The internal tables can always be overridden by tables supplied by  the       The  internal tables can always be overridden by tables supplied by the
        application that calls PCRE. These may be created in a different locale         application that calls PCRE. These may be created in a different locale
       from the default. As more and more applications change  to  using  Uni-       from  the  default.  As more and more applications change to using Uni-
        code, the need for this locale support is expected to die away.         code, the need for this locale support is expected to die away.
   
       External  tables  are  built by calling the pcre_maketables() function,       External tables are built by calling  the  pcre_maketables()  function,
       which has no arguments, in the relevant locale. The result can then  be       which  has no arguments, in the relevant locale. The result can then be
       passed  to  pcre_compile()  or  pcre_exec()  as often as necessary. For       passed to pcre_compile() or pcre_exec()  as  often  as  necessary.  For
       example, to build and use tables that are appropriate  for  the  French       example,  to  build  and use tables that are appropriate for the French
       locale  (where  accented  characters  with  values greater than 128 are       locale (where accented characters with  values  greater  than  128  are
        treated as letters), the following code could be used:         treated as letters), the following code could be used:
   
          setlocale(LC_CTYPE, "fr_FR");           setlocale(LC_CTYPE, "fr_FR");
          tables = pcre_maketables();           tables = pcre_maketables();
          re = pcre_compile(..., tables);           re = pcre_compile(..., tables);
   
       The locale name "fr_FR" is used on Linux and other  Unix-like  systems;       The  locale  name "fr_FR" is used on Linux and other Unix-lik       The  locale  name "fr_FR" is used on Linux and other Unix-lik
        if you are using Windows, the name for the French locale is "french".         if you are using Windows, the name for the French locale is "french".
   
       When  pcre_maketables()  runs,  the  tables are built in memory that is       When pcre_maketables() runs, the tables are built  in  memory  that  is
       obtained via pcre_malloc. It is the caller's responsibility  to  ensure       obtained  via  pcre_malloc. It is the caller's responsibility to ensure
       that  the memory containing the tables remains available for as long as       that the memory containing the tables remains available for as long  as
        it is needed.         it is needed.
   
        The pointer that is passed to pcre_compile() is saved with the compiled         The pointer that is passed to pcre_compile() is saved with the compiled
       pattern,  and the same tables are used via this pointer by pcre_study()       pattern, and the same tables are used via this pointer by  pcre_study()
        and normally also by pcre_exec(). Thus, by default, for any single pat-         and normally also by pcre_exec(). Thus, by default, for any single pat-
        tern, compilation, studying and matching all happen in the same locale,         tern, compilation, studying and matching all happen in the same locale,
        but different patterns can be compiled in different locales.         but different patterns can be compiled in different locales.
   
       It is possible to pass a table pointer or NULL (indicating the  use  of       It  is  possible to pass a table pointer or NULL (indicating the use of
       the  internal  tables)  to  pcre_exec(). Although not intended for this       the internal tables) to pcre_exec(). Although  not  intended  for  this
       purpose, this facility could be used to match a pattern in a  different       purpose,  this facility could be used to match a pattern in a different
        locale from the one in which it was compiled. Passing table pointers at         locale from the one in which it was compiled. Passing table pointers at
        run time is discussed below in the section on matching a pattern.         run time is discussed below in the section on matching a pattern.
   
Line 1622  INFORMATION ABOUT A PATTERN Line 2063  INFORMATION ABOUT A PATTERN
        int pcre_fullinfo(const pcre *code, const pcre_extra *extra,         int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
             int what, void *where);              int what, void *where);
   
       The pcre_fullinfo() function returns information about a compiled  pat-       The  pcre_fullinfo() function returns information about a compiled pat-
       tern. It replaces the obsolete pcre_info() function, which is neverthe-       tern. It replaces the pcre_info() function, which was removed from  the
       less retained for backwards compability (and is documented below).       library at version 8.30, after more than 10 years of obsolescence.
   
       The first argument for pcre_fullinfo() is a  pointer  to  the  compiled       The  first  argument  for  pcre_fullinfo() is a pointer to the compiled
       pattern.  The second argument is the result of pcre_study(), or NULL if       pattern. The second argument is the result of pcre_study(), or NULL  if
       the pattern was not studied. The third argument specifies  which  piece       the  pattern  was not studied. The third argument specifies which piece
       of  information  is required, and the fourth argument is a pointer to a       of information is required, and the fourth argument is a pointer  to  a
       variable to receive the data. The yield of the  function  is  zero  for       variable  to  receive  the  data. The yield of the function is zero for
        success, or one of the following negative numbers:         success, or one of the following negative numbers:
   
         PCRE_ERROR_NULL       the argument code was NULL         PCRE_ERROR_NULL           the argument code was NULL
                               the argument where was NULL                                   the argument where was NULL
         PCRE_ERROR_BADMAGIC   the "magic number" was not found         PCRE_ERROR_BADMAGIC       the "magic number" was not found
         PCRE_ERROR_BADOPTION  the value of what was invalid         PCRE_ERROR_BADENDIANNESS  the pattern was compiled with different
                                    endianness
          PCRE_ERROR_BADOPTION      the value of what was invalid
   
       The  "magic  number" is placed at the start of each compiled pattern as       The "magic number" is placed at the start of each compiled  pattern  as
       an simple check against passing an arbitrary memory pointer. Here is  a       an  simple check against passing an arbitrary memory pointer. The endi-
       typical  call  of pcre_fullinfo(), to obtain the length of the compiled       anness error can occur if a compiled pattern is saved and reloaded on a
       pattern:       different  host.  Here  is a typical call of pcre_fullinfo(), to obtain
        the length of the compiled pattern:
   
          int rc;           int rc;
          size_t length;           size_t length;
Line 1675  INFORMATION ABOUT A PATTERN Line 2119  INFORMATION ABOUT A PATTERN
   
          PCRE_INFO_FIRSTBYTE           PCRE_INFO_FIRSTBYTE
   
       Return information about the first byte of any matched  string,  for  a       Return information about the first data unit of any matched string, for
       non-anchored  pattern. The fourth argument should point to an int vari-       a  non-anchored  pattern.  (The name of this option refers to the 8-bit
       able. (This option used to be called PCRE_INFO_FIRSTCHAR; the old  name       library, where data units are bytes.) The fourth argument should  point
       is still recognized for backwards compatibility.)       to an int variable.
   
       If  there  is  a  fixed first byte, for example, from a pattern such as       If  there  is  a  fixed first value, for example, the letter "c" from a
       (cat|cow|coyote), its value is returned. Otherwise, if either       pattern such as (cat|cow|coyote), its value is returned. In  the  8-bit
        library,  the  value is always less than 256; in the 16-bit library the
        value can be up to 0xffff.
   
          If there is no fixed first value, and if either
   
        (a) the pattern was compiled with the PCRE_MULTILINE option, and  every         (a) the pattern was compiled with the PCRE_MULTILINE option, and  every
        branch starts with "^", or         branch starts with "^", or
   
Line 1696  INFORMATION ABOUT A PATTERN Line 2144  INFORMATION ABOUT A PATTERN
          PCRE_INFO_FIRSTTABLE           PCRE_INFO_FIRSTTABLE
   
        If the pattern was studied, and this resulted in the construction of  a         If the pattern was studied, and this resulted in the construction of  a
       256-bit table indicating a fixed set of bytes for the first byte in any       256-bit  table indicating a fixed set of values for the first data unit
       matching string, a pointer to the table is returned. Otherwise NULL  is       in any matching string, a pointer to the table is  returned.  Otherwise
       returned.  The fourth argument should point to an unsigned char * vari-       NULL  is returned. The fourth argument should point to an unsigned char
       able.       * variable.
   
          PCRE_INFO_HASCRORLF           PCRE_INFO_HASCRORLF
   
Line 1716  INFORMATION ABOUT A PATTERN Line 2164  INFORMATION ABOUT A PATTERN
   
          PCRE_INFO_JIT           PCRE_INFO_JIT
   
       Return  1  if  the  pattern was studied with the PCRE_STUDY_JIT_COMPILE       Return  1  if  the pattern was studied with one of the JIT options, and
       option, and just-in-time compiling was successful. The fourth  argument       just-in-time compiling was successful. The fourth argument should point
       should  point  to  an  int variable. A return value of 0 means that JIT       to  an  int variable. A return value of 0 means that JIT support is not
       support is not available in this version of PCRE, or that  the  pattern       available in this version of PCRE, or that the pattern was not  studied
       was not studied with the PCRE_STUDY_JIT_COMPILE option, or that the JIT       with  a JIT option, or that the JIT compiler could not handle this par-
       compiler could not handle this particular pattern. See the pcrejit doc-       ticular pattern. See the pcrejit documentation for details of what  can
       umentation for details of what can and cannot be handled.       and cannot be handled.
   
          PCRE_INFO_JITSIZE           PCRE_INFO_JITSIZE
   
       If the pattern was successfully studied with the PCRE_STUDY_JIT_COMPILE       If  the  pattern was successfully studied with a JIT option, return the
       option, return the size of the  JIT  compiled  code,  otherwise  return       size of the JIT compiled code, otherwise return zero. The fourth  argu-
       zero. The fourth argument should point to a size_t variable.       ment should point to a size_t variable.
   
          PCRE_INFO_LASTLITERAL           PCRE_INFO_LASTLITERAL
   
       Return  the  value of the rightmost literal byte that must exist in any       Return  the value of the rightmost literal data unit that must exist in
       matched string, other than at its  start,  if  such  a  byte  has  been       any matched string, other than at its start, if such a value  has  been
        recorded. The fourth argument should point to an int variable. If there         recorded. The fourth argument should point to an int variable. If there
       is no such byte, -1 is returned. For anchored patterns, a last  literal       is no such value, -1 is returned. For anchored patterns, a last literal
       byte  is  recorded only if it follows something of variable length. For       value  is recorded only if it follows something of variable length. For
        example, for the pattern /^a\d+z\d+/ the returned value is "z", but for         example, for the pattern /^a\d+z\d+/ the returned value is "z", but for
        /^a\dz\d/ the returned value is -1.         /^a\dz\d/ the returned value is -1.
   
            PCRE_INFO_MAXLOOKBEHIND
   
          Return  the  number of characters (NB not bytes) in the longest lookbe-
          hind assertion in the pattern. Note that the simple assertions  \b  and
          \B  require a one-character lookbehind. This information is useful when
          doing multi-segment matching using the partial matching facilities.
   
          PCRE_INFO_MINLENGTH           PCRE_INFO_MINLENGTH
   
       If  the  pattern  was studied and a minimum length for matching subject       If the pattern was studied and a minimum length  for  matching  subject
       strings was computed, its value is  returned.  Otherwise  the  returned       strings  was  computed,  its  value is returned. Otherwise the returned
       value  is  -1. The value is a number of characters, not bytes (this may       value is -1. The value is a number of characters, which in  UTF-8  mode
       be relevant in UTF-8 mode). The fourth argument should point to an  int       may  be  different from the number of bytes. The fourth argument should
       variable.  A  non-negative  value is a lower bound to the length of any       point to an int variable. A non-negative value is a lower bound to  the
       matching string. There may not be any strings of that  length  that  do       length  of  any  matching  string. There may not be any strings of that
       actually match, but every string that does match is at least that long.       length that do actually match, but every string that does match  is  at
        least that long.
   
          PCRE_INFO_NAMECOUNT           PCRE_INFO_NAMECOUNT
          PCRE_INFO_NAMEENTRYSIZE           PCRE_INFO_NAMEENTRYSIZE
Line 1768  INFORMATION ABOUT A PATTERN Line 2224  INFORMATION ABOUT A PATTERN
        gives the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size         gives the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size
        of  each  entry;  both  of  these  return  an int value. The entry size         of  each  entry;  both  of  these  return  an int value. The entry size
        depends on the length of the longest name. PCRE_INFO_NAMETABLE  returns         depends on the length of the longest name. PCRE_INFO_NAMETABLE  returns
       a  pointer  to  the  first  entry of the table (a pointer to char). The       a pointer to the first entry of the table. This is a pointer to char in
       first two bytes of each entry are the number of the capturing parenthe-       the 8-bit library, where the first two bytes of each entry are the num-
       sis,  most  significant byte first. The rest of the entry is the corre-       ber  of  the capturing parenthesis, most significant byte first. In the
       sponding name, zero terminated.       16-bit library, the pointer points to 16-bit data 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. Duplicate names may appear if  (?|         The names are in alphabetical order. Duplicate names may appear if  (?|
        is used to create multiple groups with the same number, as described in         is used to create multiple groups with the same number, as described in
Line 1784  INFORMATION ABOUT A PATTERN Line 2242  INFORMATION ABOUT A PATTERN
        terns may have lower numbers.         terns may have lower numbers.
   
        As a simple example of the name/number table,  consider  the  following         As a simple example of the name/number table,  consider  the  following
       pattern  (assume  PCRE_EXTENDED is set, so white space - including new-       pattern after compilation by the 8-bit library (assume PCRE_EXTENDED is
       lines - is ignored):       set, so white space - including newlines - is ignored):
   
          (?<date> (?<year>(\d\d)?\d\d) -           (?<date> (?<year>(\d\d)?\d\d) -
          (?<month>\d\d) - (?<day>\d\d) )           (?<month>\d\d) - (?<day>\d\d) )
Line 1838  INFORMATION ABOUT A PATTERN Line 2296  INFORMATION ABOUT A PATTERN
   
          PCRE_INFO_SIZE           PCRE_INFO_SIZE
   
       Return  the  size  of  the compiled pattern. The fourth argument should       Return  the size of the compiled pattern in bytes (for both libraries).
       point to a size_t variable. This value does not include the size of the       The fourth argument should point to a size_t variable. This value  does
       pcre  structure  that  is returned by pcre_compile(). The value that is       not  include  the  size  of  the  pcre  structure  that  is returned by
       passed as the argument to pcre_malloc() when pcre_compile() is  getting       pcre_compile(). The value that is passed as the argument  to  pcre_mal-
       memory  in  which  to  place the compiled data is the value returned by       loc()  when pcre_compile() is getting memory in which to place the com-
       this option plus the size of the pcre structure.  Studying  a  compiled       piled data is the value returned by this option plus the  size  of  the
       pattern, with or without JIT, does not alter the value returned by this       pcre  structure. Studying a compiled pattern, with or without JIT, does
       option.       not alter the value returned by this option.
   
          PCRE_INFO_STUDYSIZE           PCRE_INFO_STUDYSIZE
   
       Return the size of the data block pointed to by the study_data field in       Return the size in bytes of the data block pointed to by the study_data
       a  pcre_extra  block. If pcre_extra is NULL, or there is no study data,       field  in  a  pcre_extra  block.  If pcre_extra is NULL, or there is no
       zero is returned. The fourth argument should point to  a  size_t  vari-       study data, zero is returned. The fourth argument  should  point  to  a
       able.   The  study_data field is set by pcre_study() to record informa-       size_t  variable. The study_data field is set by pcre_study() to record
       tion that will speed up matching (see the section entitled "Studying  a       information that will speed  up  matching  (see  the  section  entitled
       pattern" above). The format of the study_data block is private, but its       "Studying a pattern" above). The format of the study_data block is pri-
       length is made available via this option so that it can  be  saved  and       vate, but its length is made available via this option so that  it  can
       restored (see the pcreprecompile documentation for details).       be  saved  and  restored  (see  the  pcreprecompile  documentation  for
        details).
   
   
 OBSOLETE INFO FUNCTION  
   
        int pcre_info(const pcre *code, int *optptr, int *firstcharptr);  
   
        The  pcre_info()  function is now obsolete because its interface is too  
        restrictive to return all the available data about a compiled  pattern.  
        New   programs   should  use  pcre_fullinfo()  instead.  The  yield  of  
        pcre_info() is the number of capturing subpatterns, or one of the  fol-  
        lowing negative numbers:  
   
          PCRE_ERROR_NULL       the argument code was NULL  
          PCRE_ERROR_BADMAGIC   the "magic number" was not found  
   
        If  the  optptr  argument is not NULL, a copy of the options with which  
        the pattern was compiled is placed in the integer  it  points  to  (see  
        PCRE_INFO_OPTIONS above).  
   
        If  the  pattern  is  not anchored and the firstcharptr argument is not  
        NULL, it is used to pass back information about the first character  of  
        any matched string (see PCRE_INFO_FIRSTBYTE above).  
   
   
 REFERENCE COUNTS  REFERENCE COUNTS
   
        int pcre_refcount(pcre *code, int adjust);         int pcre_refcount(pcre *code, int adjust);
   
       The  pcre_refcount()  function is used to maintain a reference count in       The pcre_refcount() function is used to maintain a reference  count  in
        the data block that contains a compiled pattern. It is provided for the         the data block that contains a compiled pattern. It is provided for the
       benefit  of  applications  that  operate  in an object-oriented manner,       benefit of applications that  operate  in  an  object-oriented  manner,
        where different parts of the application may be using the same compiled         where different parts of the application may be using the same compiled
        pattern, but you want to free the block when they are all done.         pattern, but you want to free the block when they are all done.
   
        When a pattern is compiled, the reference count field is initialized to         When a pattern is compiled, the reference count field is initialized to
       zero.  It is changed only by calling this function, whose action is  to       zero.   It is changed only by calling this function, whose action is to
       add  the  adjust  value  (which may be positive or negative) to it. The       add the adjust value (which may be positive or  negative)  to  it.  The
        yield of the function is the new value. However, the value of the count         yield of the function is the new value. However, the value of the count
       is  constrained to lie between 0 and 65535, inclusive. If the new value       is constrained to lie between 0 and 65535, inclusive. If the new  value
        is outside these limits, it is forced to the appropriate limit value.         is outside these limits, it is forced to the appropriate limit value.
   
       Except when it is zero, the reference count is not correctly  preserved       Except  when it is zero, the reference count is not correctly preserved
       if  a  pattern  is  compiled on one host and then transferred to a host       if a pattern is compiled on one host and then  transferred  to  a  host
        whose byte-order is different. (This seems a highly unlikely scenario.)         whose byte-order is different. (This seems a highly unlikely scenario.)
   
   
Line 1909  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2346  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
             const char *subject, int length, int startoffset,              const char *subject, int length, int startoffset,
             int options, int *ovector, int ovecsize);              int options, int *ovector, int ovecsize);
   
       The function pcre_exec() is called to match a subject string against  a       The  function pcre_exec() is called to match a subject string against a
       compiled  pattern, which is passed in the code argument. If the pattern       compiled pattern, which is passed in the code argument. If the  pattern
       was studied, the result of the study should  be  passed  in  the  extra       was  studied,  the  result  of  the study should be passed in the extra
       argument.  You  can call pcre_exec() with the same code and extra argu-       argument. You can call pcre_exec() with the same code and  extra  argu-
       ments as many times as you like, in order to  match  different  subject       ments  as  many  times as you like, in order to match different subject
        strings with the same pattern.         strings with the same pattern.
   
       This  function  is  the  main  matching facility of the library, and it       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       operates  in  a  Perl-like  manner. For specialist use there is also an
       alternative  matching function, which is described below in the section       alternative matching function, which is described below in the  section
        about the pcre_dfa_exec() function.         about the pcre_dfa_exec() function.
   
       In most applications, the pattern will have been compiled (and  option-       In  most applications, the pattern will have been compiled (and option-
       ally  studied)  in the same process that calls pcre_exec(). However, it       ally studied) in the same process that calls pcre_exec().  However,  it
        is possible to save compiled patterns and study data, and then use them         is possible to save compiled patterns and study data, and then use them
       later  in  different processes, possibly even on different hosts. For a       later in different processes, possibly even on different hosts.  For  a
        discussion about this, see the pcreprecompile documentation.         discussion about this, see the pcreprecompile documentation.
   
        Here is an example of a simple call to pcre_exec():         Here is an example of a simple call to pcre_exec():
Line 1943  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2380  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
   
    Extra data for pcre_exec()     Extra data for pcre_exec()
   
       If the extra argument is not NULL, it must point to a  pcre_extra  data       If  the  extra argument is not NULL, it must point to a pcre_extra data
       block.  The pcre_study() function returns such a block (when it doesn't       block. The pcre_study() function returns such a block (when it  doesn't
       return NULL), but you can also create one for yourself, and pass  addi-       return  NULL), but you can also create one for yourself, and pass addi-
       tional  information  in it. The pcre_extra block contains the following       tional information in it. The pcre_extra block contains  the  following
        fields (not necessarily in this order):         fields (not necessarily in this order):
   
          unsigned long int flags;           unsigned long int flags;
Line 1958  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2395  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
          const unsigned char *tables;           const unsigned char *tables;
          unsigned char **mark;           unsigned char **mark;
   
       The flags field is a bitmap that specifies which of  the  other  fields       In  the  16-bit  version  of  this  structure,         In  the  16-bit  version  of  this  structure,  the mark field has type
       are set. The flag bits are:       "PCRE_UCHAR16 **".
   
         PCRE_EXTRA_STUDY_DATA       The flags field is used to specify which of the other fields  are  set.
        The flag bits are:
 
          PCRE_EXTRA_CALLOUT_DATA
          PCRE_EXTRA_EXECUTABLE_JIT           PCRE_EXTRA_EXECUTABLE_JIT
            PCRE_EXTRA_MARK
          PCRE_EXTRA_MATCH_LIMIT           PCRE_EXTRA_MATCH_LIMIT
          PCRE_EXTRA_MATCH_LIMIT_RECURSION           PCRE_EXTRA_MATCH_LIMIT_RECURSION
         PCRE_EXTRA_CALLOUT_DATA         PCRE_EXTRA_STUDY_DATA
          PCRE_EXTRA_TABLES           PCRE_EXTRA_TABLES
          PCRE_EXTRA_MARK  
   
        Other  flag  bits should be set to zero. The study_data field and some-         Other  flag  bits should be set to zero. The study_data field and some-
        times the executable_jit field are set in the pcre_extra block that  is         times the executable_jit field are set in the pcre_extra block that  is
        returned  by pcre_study(), together with the appropriate flag bits. You         returned  by pcre_study(), together with the appropriate flag bits. You
        should not set these yourself, but you may add to the block by  setting         should not set these yourself, but you may add to the block by  setting
       the other fields and their corresponding flag bits.       other fields and their corresponding flag bits.
   
        The match_limit field provides a means of preventing PCRE from using up         The match_limit field provides a means of preventing PCRE from using up
        a vast amount of resources when running patterns that are not going  to         a vast amount of resources when running patterns that are not going  to
Line 1989  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2429  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
        zero for each position in the subject string.         zero for each position in the subject string.
   
        When pcre_exec() is called with a pattern that was successfully studied         When pcre_exec() is called with a pattern that was successfully studied
       with  the  PCRE_STUDY_JIT_COMPILE  option, the way that the matching is       with  a  JIT  option, the way that the matching is executed is entirely
       executed is entirely different. However, there is still the possibility       different.  However, there is still the possibility of runaway matching
       of  runaway  matching  that  goes  on  for a very long time, and so the       that goes on for a very long time, and so the match_limit value is also
       match_limit value is also used in this case (but in a different way) to       used in this case (but in a different way) to limit how long the match-
       limit how long the matching can continue.       ing can continue.
   
        The  default  value  for  the  limit can be set when PCRE is built; the         The  default  value  for  the  limit can be set when PCRE is built; the
        default default is 10 million, which handles all but the  most  extreme         default default is 10 million, which handles all but the  most  extreme
Line 2011  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2451  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
        Limiting the recursion depth limits the amount of  machine  stack  that         Limiting the recursion depth limits the amount of  machine  stack  that
        can  be used, or, when PCRE has been compiled to use memory on the heap         can  be used, or, when PCRE has been compiled to use memory on the heap
        instead of the stack, the amount of heap memory that can be used.  This         instead of the stack, the amount of heap memory that can be used.  This
       limit  is not relevant, and is ignored, if the pattern was successfully       limit  is not relevant, and is ignored, when matching is done using JIT
       studied with PCRE_STUDY_JIT_COMPILE.       compiled code.
   
        The default value for match_limit_recursion can be  set  when  PCRE  is         The default value for match_limit_recursion can be  set  when  PCRE  is
        built;  the  default  default  is  the  same  value  as the default for         built;  the  default  default  is  the  same  value  as the default for
Line 2036  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2476  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
        tion for a discussion of saving compiled patterns for later use.         tion for a discussion of saving compiled patterns for later use.
   
        If  PCRE_EXTRA_MARK  is  set in the flags field, the mark field must be         If  PCRE_EXTRA_MARK  is  set in the flags field, the mark field must be
       set to point to a char * variable. If the pattern  contains  any  back-       set to point to a suitable variable. If the pattern contains any  back-
        tracking  control verbs such as (*MARK:NAME), and the execution ends up         tracking  control verbs such as (*MARK:NAME), and the execution ends up
        with a name to pass back, a pointer to the  name  string  (zero  termi-         with a name to pass back, a pointer to the  name  string  (zero  termi-
        nated)  is  placed  in  the  variable pointed to by the mark field. The         nated)  is  placed  in  the  variable pointed to by the mark field. The
        names are within the compiled pattern; if you wish  to  retain  such  a         names are within the compiled pattern; if you wish  to  retain  such  a
        name  you must copy it before freeing the memory of a compiled pattern.         name  you must copy it before freeing the memory of a compiled pattern.
        If there is no name to pass back, the variable pointed to by  the  mark         If there is no name to pass back, the variable pointed to by  the  mark
       field  set  to NULL. For details of the backtracking control verbs, see       field  is  set  to NULL. For details of the backtracking control verbs,
       the section entitled "Backtracking control" in the pcrepattern documen-       see the section entitled "Backtracking control" in the pcrepattern doc-
       tation.       umentation.
   
    Option bits for pcre_exec()     Option bits for pcre_exec()
   
        The  unused  bits of the options argument for pcre_exec() must be zero.         The  unused  bits of the options argument for pcre_exec() must be zero.
        The only bits that may  be  set  are  PCRE_ANCHORED,  PCRE_NEWLINE_xxx,         The only bits that may  be  set  are  PCRE_ANCHORED,  PCRE_NEWLINE_xxx,
        PCRE_NOTBOL,    PCRE_NOTEOL,    PCRE_NOTEMPTY,   PCRE_NOTEMPTY_ATSTART,         PCRE_NOTBOL,    PCRE_NOTEOL,    PCRE_NOTEMPTY,   PCRE_NOTEMPTY_ATSTART,
       PCRE_NO_START_OPTIMIZE,  PCRE_NO_UTF8_CHECK,   PCRE_PARTIAL_SOFT,   and       PCRE_NO_START_OPTIMIZE,  PCRE_NO_UTF8_CHECK,   PCRE_PARTIAL_HARD,   and
       PCRE_PARTIAL_HARD.       PCRE_PARTIAL_SOFT.
   
       If the pattern was successfully studied with the PCRE_STUDY_JIT_COMPILE       If  the  pattern  was successfully studied with one of the just-in-time
       option,  the   only   supported   options   for   JIT   execution   are       (JIT) compile options, the only supported options for JIT execution are
       PCRE_NO_UTF8_CHECK,   PCRE_NOTBOL,   PCRE_NOTEOL,   PCRE_NOTEMPTY,  and       PCRE_NO_UTF8_CHECK,     PCRE_NOTBOL,     PCRE_NOTEOL,    PCRE_NOTEMPTY,
       PCRE_NOTEMPTY_ATSTART. Note in particular that partial matching is  not       PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and PCRE_PARTIAL_SOFT. If  an
       supported.  If an unsupported option is used, JIT execution is disabled       unsupported  option  is  used, JIT execution is disabled and the normal
       and the normal interpretive code in pcre_exec() is run.       interpretive code in pcre_exec() is run.
   
          PCRE_ANCHORED           PCRE_ANCHORED
   
Line 2183  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2623  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
        where  the  result is "no match", the callouts do occur, and that items         where  the  result is "no match", the callouts do occur, and that items
        such as (*COMMIT) and (*MARK) are considered at every possible starting         such as (*COMMIT) and (*MARK) are considered at every possible starting
        position  in  the  subject  string. If PCRE_NO_START_OPTIMIZE is set at         position  in  the  subject  string. If PCRE_NO_START_OPTIMIZE is set at
       compile time, it cannot be unset at matching time.       compile time,  it  cannot  be  unset  at  matching  time.  The  use  of
        PCRE_NO_START_OPTIMIZE disables JIT execution; when it is set, matching
        is always done using interpretively.
   
        Setting PCRE_NO_START_OPTIMIZE can change the  outcome  of  a  matching         Setting PCRE_NO_START_OPTIMIZE can change the  outcome  of  a  matching
        operation.  Consider the pattern         operation.  Consider the pattern
Line 2217  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2659  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
   
        When PCRE_UTF8 is set at compile time, the validity of the subject as a         When PCRE_UTF8 is set at compile time, the validity of the subject as a
        UTF-8  string is automatically checked when pcre_exec() is subsequently         UTF-8  string is automatically checked when pcre_exec() is subsequently
       called.  The value of startoffset is also checked  to  ensure  that  it       called.  The entire string is checked before any other processing takes
       points  to  the start of a UTF-8 character. There is a discussion about       place.  The  value  of  startoffset  is  also checked to ensure that it
       the validity of UTF-8 strings in the section on UTF-8  support  in  the       points to the start of a UTF-8 character. There is a  discussion  about
       main  pcre  page.  If  an  invalid  UTF-8  sequence  of bytes is found,       the  validity  of  UTF-8 strings in the pcreunicode page. If an invalid
       pcre_exec() returns  the  error  PCRE_ERROR_BADUTF8  or,  if  PCRE_PAR-       sequence  of  bytes   is   found,   pcre_exec()   returns   the   error
       TIAL_HARD  is set and the problem is a truncated UTF-8 character at the       PCRE_ERROR_BADUTF8 or, if PCRE_PARTIAL_HARD is set and the problem is a
       end of the subject, PCRE_ERROR_SHORTUTF8. In  both  cases,  information       truncated character at the end of the subject, PCRE_ERROR_SHORTUTF8. In
       about  the  precise  nature  of the error may also be returned (see the       both  cases, information about the precise nature of the error may also
       descriptions of these errors in the section entitled Error return  val-       be returned (see the descriptions of these errors in the section  enti-
       ues from pcre_exec() below).  If startoffset contains a value that does       tled  Error return values from pcre_exec() below).  If startoffset con-
       not point to the start of a UTF-8 character (or to the end of the  sub-       tains a value that does not point to the start of a UTF-8 character (or
       ject), PCRE_ERROR_BADUTF8_OFFSET is returned.       to the end of the subject), PCRE_ERROR_BADUTF8_OFFSET is returned.
   
        If  you  already  know that your subject is valid, and you want to skip         If  you  already  know that your subject is valid, and you want to skip
        these   checks   for   performance   reasons,   you   can    set    the         these   checks   for   performance   reasons,   you   can    set    the
Line 2236  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2678  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
        do this for the second and subsequent calls to pcre_exec() if  you  are         do this for the second and subsequent calls to pcre_exec() if  you  are
        making  repeated  calls  to  find  all  the matches in a single subject         making  repeated  calls  to  find  all  the matches in a single subject
        string. However, you should be  sure  that  the  value  of  startoffset         string. However, you should be  sure  that  the  value  of  startoffset
       points  to  the start of a UTF-8 character (or the end of the subject).       points  to  the  start of a character (or the end of the subject). When
       When PCRE_NO_UTF8_CHECK is set, the effect of passing an invalid  UTF-8       PCRE_NO_UTF8_CHECK is set, the effect of passing an invalid string as a
       string  as  a  subject or an invalid value of startoffset is undefined.       subject  or  an invalid value of startoffset is undefined. Your program
       Your program may crash.       may crash.
   
          PCRE_PARTIAL_HARD           PCRE_PARTIAL_HARD
          PCRE_PARTIAL_SOFT           PCRE_PARTIAL_SOFT
Line 2269  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2711  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
    The string to be matched by pcre_exec()     The string to be matched by pcre_exec()
   
        The subject string is passed to pcre_exec() as a pointer in subject,  a         The subject string is passed to pcre_exec() as a pointer in subject,  a
       length (in bytes) in length, and a starting byte offset in startoffset.       length  in  bytes in length, and a starting byte offset in startoffset.
        If this is  negative  or  greater  than  the  length  of  the  subject,         If this is  negative  or  greater  than  the  length  of  the  subject,
        pcre_exec()  returns  PCRE_ERROR_BADOFFSET. When the starting offset is         pcre_exec()  returns  PCRE_ERROR_BADOFFSET. When the starting offset is
        zero, the search for a match starts at the beginning  of  the  subject,         zero, the search for a match starts at the beginning  of  the  subject,
Line 2358  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2800  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
        If  the vector is too small to hold all the captured substring offsets,         If  the vector is too small to hold all the captured substring offsets,
        it is used as far as possible (up to two-thirds of its length), and the         it is used as far as possible (up to two-thirds of its length), and the
        function  returns a value of zero. If neither the actual string matched         function  returns a value of zero. If neither the actual string matched
       not any captured substrings are of interest, pcre_exec() may be  called       nor any captured substrings are of interest, pcre_exec() may be  called
        with  ovector passed as NULL and ovecsize as zero. However, if the pat-         with  ovector passed as NULL and ovecsize as zero. However, if the pat-
        tern contains back references and the ovector  is  not  big  enough  to         tern contains back references and the ovector  is  not  big  enough  to
        remember  the related substrings, PCRE has to get additional memory for         remember  the related substrings, PCRE has to get additional memory for
Line 2549  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2991  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
          PCRE_ERROR_JIT_STACKLIMIT (-27)           PCRE_ERROR_JIT_STACKLIMIT (-27)
   
        This error is returned when a pattern  that  was  successfully  studied         This error is returned when a pattern  that  was  successfully  studied
       using  the PCRE_STUDY_JIT_COMPILE option is being matched, but the mem-       using  a  JIT compile option is being matched, but the memory available
       ory available for  the  just-in-time  processing  stack  is  not  large       for the just-in-time processing stack is  not  large  enough.  See  the
       enough. See the pcrejit documentation for more details.       pcrejit documentation for more details.
   
       Error numbers -16 to -20 and -22 are not used by pcre_exec().         PCRE_ERROR_BADMODE        (-28)
   
          This error is given if a pattern that was compiled by the 8-bit library
          is passed to a 16-bit library function, or vice versa.
   
            PCRE_ERROR_BADENDIANNESS  (-29)
   
          This error is given if  a  pattern  that  was  compiled  and  saved  is
          reloaded  on  a  host  with  different endianness. The utility function
          pcre_pattern_to_host_byte_order() can be used to convert such a pattern
          so that it runs on the new host.
   
          Error numbers -16 to -20, -22, and -30 are not used by pcre_exec().
   
    Reason codes for invalid UTF-8 strings     Reason codes for invalid UTF-8 strings
   
          This  section  applies  only  to  the  8-bit library. The corresponding
          information for the 16-bit library is given in the pcre16 page.
   
        When pcre_exec() returns either PCRE_ERROR_BADUTF8 or PCRE_ERROR_SHORT-         When pcre_exec() returns either PCRE_ERROR_BADUTF8 or PCRE_ERROR_SHORT-
       UTF8, and the size of the output vector (ovecsize) is at least  2,  the       UTF8,  and  the size of the output vector (ovecsize) is at least 2, the
       offset  of  the  start  of the invalid UTF-8 character is placed in the       offset of the start of the invalid UTF-8 character  is  placed  in  the
        first output vector element (ovector[0]) and a reason code is placed in         first output vector element (ovector[0]) and a reason code is placed in
       the  second  element  (ovector[1]). The reason codes are given names in       the second element (ovector[1]). The reason codes are  given  names  in
        the pcre.h header file:         the pcre.h header file:
   
          PCRE_UTF8_ERR1           PCRE_UTF8_ERR1
Line 2570  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 3027  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
          PCRE_UTF8_ERR4           PCRE_UTF8_ERR4
          PCRE_UTF8_ERR5           PCRE_UTF8_ERR5
   
       The string ends with a truncated UTF-8 character;  the  code  specifies       The  string  ends  with a truncated UTF-8 character; the code specifies
       how  many bytes are missing (1 to 5). Although RFC 3629 restricts UTF-8       how many bytes are missing (1 to 5). Although RFC 3629 restricts  UTF-8
       characters to be no longer than 4 bytes, the  encoding  scheme  (origi-       characters  to  be  no longer than 4 bytes, the encoding scheme (origi-
       nally  defined  by  RFC  2279)  allows  for  up to 6 bytes, and this is       nally defined by RFC 2279) allows for  up  to  6  bytes,  and  this  is
        checked first; hence the possibility of 4 or 5 missing bytes.         checked first; hence the possibility of 4 or 5 missing bytes.
   
          PCRE_UTF8_ERR6           PCRE_UTF8_ERR6
Line 2583  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 3040  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
          PCRE_UTF8_ERR10           PCRE_UTF8_ERR10
   
        The two most significant bits of the 2nd, 3rd, 4th, 5th, or 6th byte of         The two most significant bits of the 2nd, 3rd, 4th, 5th, or 6th byte of
       the  character  do  not have the binary value 0b10 (that is, either the       the character do not have the binary value 0b10 (that  is,  either  the
        most significant bit is 0, or the next bit is 1).         most significant bit is 0, or the next bit is 1).
   
          PCRE_UTF8_ERR11           PCRE_UTF8_ERR11
          PCRE_UTF8_ERR12           PCRE_UTF8_ERR12
   
       A character that is valid by the RFC 2279 rules is either 5 or 6  bytes       A  character that is valid by the RFC 2279 rules is either 5 or 6 bytes
        long; these code points are excluded by RFC 3629.         long; these code points are excluded by RFC 3629.
   
          PCRE_UTF8_ERR13           PCRE_UTF8_ERR13
   
       A  4-byte character has a value greater than 0x10fff; these code points       A 4-byte character has a value greater than 0x10fff; these code  points
        are excluded by RFC 3629.         are excluded by RFC 3629.
   
          PCRE_UTF8_ERR14           PCRE_UTF8_ERR14
   
       A 3-byte character has a value in the  range  0xd800  to  0xdfff;  this       A  3-byte  character  has  a  value i       A  3-byte  character  has  a  value i
       range  of code points are reserved by RFC 3629 for use with UTF-16, and       range of code points are reserved by RFC 3629 for use with UTF-16,  and
        so are excluded from UTF-8.         so are excluded from UTF-8.
   
          PCRE_UTF8_ERR15           PCRE_UTF8_ERR15
Line 2609  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 3066  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
          PCRE_UTF8_ERR18           PCRE_UTF8_ERR18
          PCRE_UTF8_ERR19           PCRE_UTF8_ERR19
   
       A 2-, 3-, 4-, 5-, or 6-byte character is "overlong", that is, it  codes       A  2-, 3-, 4-, 5-, or 6-byte character is "overlong", that is, it codes
       for  a  value that can be represented by fewer bytes, which is invalid.       for a value that can be represented by fewer bytes, which  is  invalid.
       For example, the two bytes 0xc0, 0xae give the value 0x2e,  whose  cor-       For  example,  the two bytes 0xc0, 0xae give the value 0x2e, whose cor-
        rect coding uses just one byte.         rect coding uses just one byte.
   
          PCRE_UTF8_ERR20           PCRE_UTF8_ERR20
   
        The two most significant bits of the first byte of a character have the         The two most significant bits of the first byte of a character have the
       binary value 0b10 (that is, the most significant bit is 1 and the  sec-       binary  value 0b10 (that is, the most significant bit is 1 and the sec-
       ond  is  0). Such a byte can only validly occur as the second or subse-       ond is 0). Such a byte can only validly occur as the second  or  subse-
        quent byte of a multi-byte character.         quent byte of a multi-byte character.
   
          PCRE_UTF8_ERR21           PCRE_UTF8_ERR21
   
       The first byte of a character has the value 0xfe or 0xff. These  values       The  first byte of a character has the value 0xfe or 0xff. These values
        can never occur in a valid UTF-8 string.         can never occur in a valid UTF-8 string.
   
   
Line 2640  EXTRACTING CAPTURED SUBSTRINGS BY NUMBER Line 3097  EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
        int pcre_get_substring_list(const char *subject,         int pcre_get_substring_list(const char *subject,
             int *ovector, int stringcount, const char ***listptr);              int *ovector, int stringcount, const char ***listptr);
   
       Captured  substrings  can  be  accessed  directly  by using the offsets       Captured substrings can be  accessed  directly  by  using  the  offsets
       returned by pcre_exec() in  ovector.  For  convenience,  the  functions       returned  by  pcre_exec()  in  ovector.  For convenience, the functions
        pcre_copy_substring(),    pcre_get_substring(),    and    pcre_get_sub-         pcre_copy_substring(),    pcre_get_substring(),    and    pcre_get_sub-
       string_list() are provided for extracting captured substrings  as  new,       string_list()  are  provided for extracting captured substrings as new,
       separate,  zero-terminated strings. These functions identify substrings       separate, zero-terminated strings. These functions identify  substrings
       by number. The next section describes functions  for  extracting  named       by  number.  The  next section describes functions for extracting named
        substrings.         substrings.
   
       A  substring that contains a binary zero is correctly extracted and has       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       a  further zero added on the end, but the result is not, of course, a C
       string.   However,  you  can  process such a string by referring to the       string.  However, you can process such a string  by  referring  to  the
       length that is  returned  by  pcre_copy_substring()  and  pcre_get_sub-       length  that  is  returned  by  pcre_copy_substring() and pcre_get_sub-
        string().  Unfortunately, the interface to pcre_get_substring_list() is         string().  Unfortunately, the interface to pcre_get_substring_list() is
       not adequate for handling strings containing binary zeros, because  the       not  adequate for handling strings containing binary zeros, because the
        end of the final string is not independently indicated.         end of the final string is not independently indicated.
   
       The  first  three  arguments  are the same for all three of these func-       The first three arguments are the same for all  three  of  these  func-
       tions: subject is the subject string that has  just  been  successfully       tions:  subject  is  the subject string that has just been successfully
        matched, ovector is a pointer to the vector of integer offsets that was         matched, ovector is a pointer to the vector of integer offsets that was
        passed to pcre_exec(), and stringcount is the number of substrings that         passed to pcre_exec(), and stringcount is the number of substrings that
       were  captured  by  the match, including the substring that matched the       were captured by the match, including the substring  that  matched  the
        entire regular expression. This is the value returned by pcre_exec() if         entire regular expression. This is the value returned by pcre_exec() if
       it  is greater than zero. If pcre_exec() returned zero, indicating that       it is greater than zero. If pcre_exec() returned zero, indicating  that
       it ran out of space in ovector, the value passed as stringcount  should       it  ran out of space in ovector, the value passed as stringcount should
        be the number of elements in the vector divided by three.         be the number of elements in the vector divided by three.
   
       The  functions pcre_copy_substring() and pcre_get_substring() extract a       The functions pcre_copy_substring() and pcre_get_substring() extract  a
       single substring, whose number is given as  stringnumber.  A  value  of       single  substring,  whose  number  is given as stringnumber. A value of
       zero  extracts  the  substring that matched the entire pattern, whereas       zero extracts the substring that matched the  entire  pattern,  whereas
       higher values  extract  the  captured  substrings.  For  pcre_copy_sub-       higher  values  extract  the  captured  substrings.  For pcre_copy_sub-
       string(),  the  string  is  placed  in buffer, whose length is given by       string(), the string is placed in buffer,  whose  length  is  given  by
       buffersize, while for pcre_get_substring() a new  block  of  memory  is       buffersize,  while  for  pcre_get_substring()  a new block of memory is
       obtained  via  pcre_malloc,  and its address is returned via stringptr.       obtained via pcre_malloc, and its address is  returned  via  stringptr.
       The yield of the function is the length of the  string,  not  including       The  yield  of  the function is the length of the string, not including
        the terminating zero, or one of these error codes:         the terminating zero, or one of these error codes:
   
          PCRE_ERROR_NOMEMORY       (-6)           PCRE_ERROR_NOMEMORY       (-6)
   
       The  buffer  was too small for pcre_copy_substring(), or the attempt to       The buffer was too small for pcre_copy_substring(), or the  attempt  to
        get memory failed for pcre_get_substring().         get memory failed for pcre_get_substring().
   
          PCRE_ERROR_NOSUBSTRING    (-7)           PCRE_ERROR_NOSUBSTRING    (-7)
   
        There is no substring whose number is stringnumber.         There is no substring whose number is stringnumber.
   
       The pcre_get_substring_list()  function  extracts  all  available  sub-       The  pcre_get_substring_list()  function  extracts  all  available sub-
       strings  and  builds  a list of pointers to them. All this is done in a       strings and builds a list of pointers to them. All this is  done  in  a
        single block of memory that is obtained via pcre_malloc. The address of         single block of memory that is obtained via pcre_malloc. The address of
       the  memory  block  is returned via listptr, which is also the start 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       the  list  of  string pointers. The end of the list is marked by a NULL
       pointer.  The  yield  of  the function is zero if all went well, or the       pointer. The yield of the function is zero if all  went  well,  or  the
        error code         error code
   
          PCRE_ERROR_NOMEMORY       (-6)           PCRE_ERROR_NOMEMORY       (-6)
   
        if the attempt to get the memory block failed.         if the attempt to get the memory block failed.
   
       When any of these functions encounter a substring that is unset,  which       When  any of these functions encounter a substring that is unset, which
       can  happen  when  capturing subpattern number n+1 matches some part of       can happen when capturing subpattern number n+1 matches  some  part  of
       the subject, but subpattern n has not been used at all, they return  an       the  subject, but subpattern n has not been used at all, they return an
        empty string. This can be distinguished from a genuine zero-length sub-         empty string. This can be distinguished from a genuine zero-length sub-
       string by inspecting the appropriate offset in ovector, which is  nega-       string  by inspecting the appropriate offset in ovector, which is nega-
        tive for unset substrings.         tive for unset substrings.
   
       The  two convenience functions pcre_free_substring() and pcre_free_sub-       The two convenience functions pcre_free_substring() and  pcre_free_sub-
       string_list() can be used to free the memory  returned  by  a  previous       string_list()  can  be  used  to free the memory returned by a previous
        call  of  pcre_get_substring()  or  pcre_get_substring_list(),  respec-         call  of  pcre_get_substring()  or  pcre_get_substring_list(),  respec-
       tively. They do nothing more than  call  the  function  pointed  to  by       tively.  They  do  nothing  more  than  call the function pointed to by
       pcre_free,  which  of course could be called directly from a C program.       pcre_free, which of course could be called directly from a  C  program.
       However, PCRE is used in some situations where it is linked via a  spe-       However,  PCRE is used in some situations where it is linked via a spe-
       cial   interface  to  another  programming  language  that  cannot  use       cial  interface  to  another  programming  language  that  cannot   use
       pcre_free directly; it is for these cases that the functions  are  pro-       pcre_free  directly;  it is for these cases that the functions are pro-
        vided.         vided.
   
   
Line 2730  EXTRACTING CAPTURED SUBSTRINGS BY NAME Line 3187  EXTRACTING CAPTURED SUBSTRINGS BY NAME
             int stringcount, const char *stringname,              int stringcount, const char *stringname,
             const char **stringptr);              const char **stringptr);
   
       To  extract a substring by name, you first have to find associated num-       To extract a substring by name, you first have to find associated  num-
        ber.  For example, for this pattern         ber.  For example, for this pattern
   
          (a+)b(?<xxx>\d+)...           (a+)b(?<xxx>\d+)...
Line 2739  EXTRACTING CAPTURED SUBSTRINGS BY NAME Line 3196  EXTRACTING CAPTURED SUBSTRINGS BY NAME
        be unique (PCRE_DUPNAMES was not set), you can find the number from the         be unique (PCRE_DUPNAMES was not set), you can find the number from the
        name by calling pcre_get_stringnumber(). The first argument is the com-         name by calling pcre_get_stringnumber(). The first argument is the com-
        piled pattern, and the second is the name. The yield of the function is         piled pattern, and the second is the name. The yield of the function is
       the subpattern number, or PCRE_ERROR_NOSUBSTRING (-7) if  there  is  no       the  subpattern  number,  or PCRE_ERROR_NOSUBSTRING (-7)       the  subpattern  number,  or PCRE_ERROR_NOSUBSTRING (-7)
        subpattern of that name.         subpattern of that name.
   
        Given the number, you can extract the substring directly, or use one of         Given the number, you can extract the substring directly, or use one of
        the functions described in the previous section. For convenience, there         the functions described in the previous section. For convenience, there
        are also two functions that do the whole job.         are also two functions that do the whole job.
   
       Most    of    the    arguments   of   pcre_copy_named_substring()   and       Most   of   the   arguments    of    pcre_copy_named_substring()    and
       pcre_get_named_substring() are the same  as  those  for  the  similarly       pcre_get_named_substring()  are  the  same  as  those for the similarly
       named  functions  that extract by number. As these are described in the       named functions that extract by number. As these are described  in  the
       previous section, they are not re-described here. There  are  just  two       previous  section,  they  are not re-described here. There are just two
        differences:         differences:
   
       First,  instead  of a substring number, a substring name is given. Sec-       First, instead of a substring number, a substring name is  given.  Sec-
        ond, there is an extra argument, given at the start, which is a pointer         ond, there is an extra argument, given at the start, which is a pointer
       to  the compiled pattern. This is needed in order to gain access to the       to the compiled pattern. This is needed in order to gain access to  the
        name-to-number translation table.         name-to-number translation table.
   
       These functions call pcre_get_stringnumber(), and if it succeeds,  they       These  functions call pcre_get_stringnumber(), and if it succeeds, they
       then  call  pcre_copy_substring() or pcre_get_substring(), as appropri-       then call pcre_copy_substring() or pcre_get_substring(),  as  appropri-
       ate. NOTE: If PCRE_DUPNAMES is set and there are duplicate  names,  the       ate.  NOTE:  If PCRE_DUPNAMES is set and there are duplicate names, the
        behaviour may not be what you want (see the next section).         behaviour may not be what you want (see the next section).
   
        Warning: If the pattern uses the (?| feature to set up multiple subpat-         Warning: If the pattern uses the (?| feature to set up multiple subpat-
       terns with the same number, as described in the  section  on  duplicate       terns  with  the  same number, as described in the section on duplicate
       subpattern  numbers  in  the  pcrepattern page, you cannot use names to       subpattern numbers in the pcrepattern page, you  cannot  use  names  to
       distinguish the different subpatterns, because names are  not  included       distinguish  the  different subpatterns, because names are not included
       in  the compiled code. The matching process uses only numbers. For this       in the compiled code. The matching process uses only numbers. For  this
       reason, the use of different names for subpatterns of the  same  number       reason,  the  use of different names for subpatterns of the same number
        causes an error at compile time.         causes an error at compile time.
   
   
Line 2776  DUPLICATE SUBPATTERN NAMES Line 3233  DUPLICATE SUBPATTERN NAMES
        int pcre_get_stringtable_entries(const pcre *code,         int pcre_get_stringtable_entries(const pcre *code,
             const char *name, char **first, char **last);              const char *name, char **first, char **last);
   
       When  a  pattern  is  compiled with the PCRE_DUPNAMES option, names for       When a pattern is compiled with the  PCRE_DUPNAMES  option,  names  for
       subpatterns are not required to be unique. (Duplicate names are  always       subpatterns  are not required to be unique. (Duplicate names are always
       allowed  for subpatterns with the same number, created by using the (?|       allowed for subpatterns with the same number, created by using the  (?|
       feature. Indeed, if such subpatterns are named, they  are  required  to       feature.  Indeed,  if  such subpatterns are named, they are required to
        use the same names.)         use the same names.)
   
        Normally, patterns with duplicate names are such that in any one match,         Normally, patterns with duplicate names are such that in any one match,
       only one of the named subpatterns participates. An example is shown  in       only  one of the named subpatterns participates. An example is shown in
        the pcrepattern documentation.         the pcrepattern documentation.
   
       When    duplicates   are   present,   pcre_copy_named_substring()   and       When   duplicates   are   present,   pcre_copy_named_substring()    and
       pcre_get_named_substring() return the first substring corresponding  to       pcre_get_named_substring()  return the first substring corresponding to
       the  given  name  that  is set. If none are set, PCRE_ERROR_NOSUBSTRING       the given name that is set. If  none  are  set,  PCRE_ERROR_NOSUBSTRING
       (-7) is returned; no  data  is  returned.  The  pcre_get_stringnumber()       (-7)  is  returned;  no  data  is returned. The pcre_get_stringnumber()
       function  returns one of the numbers that are associated with the name,       function returns one of the numbers that are associated with the  name,
        but it is not defined which it is.         but it is not defined which it is.
   
       If you want to get full details of all captured substrings for a  given       If  you want to get full details of all captured substrings for a given
       name,  you  must  use  the pcre_get_stringtable_entries() function. The       name, you must use  the  pcre_get_stringtable_entries()  function.  The
        first argument is the compiled pattern, and the second is the name. The         first argument is the compiled pattern, and the second is the name. The
       third  and  fourth  are  pointers to variables which are updated by the       third and fourth are pointers to variables which  are  updated  by  the
        function. After it has run, they point to the first and last entries in         function. After it has run, they point to the first and last entries in
       the  name-to-number  table  for  the  given  name.  The function itself       the name-to-number table  for  the  given  name.  The  function  itself
       returns the length of each entry,  or  PCRE_ERROR_NOSUBSTRING  (-7)  if       returns  the  length  of  each entry, or PCRE_ERROR_NOSUBSTRING (-7) if
       there  are none. The format of the table is described above in the sec-       there are none. The format of the table is described above in the  sec-
       tion entitled Information about a pattern above.  Given all  the  rele-       tion  entitled  Information about a pattern above.  Given all the rele-
       vant  entries  for the name, you can extract each of their numbers, and       vant entries for the name, you can extract each of their  numbers,  and
        hence the captured data, if any.         hence the captured data, if any.
   
   
 FINDING ALL POSSIBLE MATCHES  FINDING ALL POSSIBLE MATCHES
   
       The traditional matching function uses a  similar  algorithm  to  Perl,       The  traditional  matching  funct       The  traditional  matching  funct
        which stops when it finds the first match, starting at a given point in         which stops when it finds the first match, starting at a given point in
       the subject. If you want to find all possible matches, or  the  longest       the  subject.  If you want to find all possible matches, or the longest
       possible  match,  consider using the alternative matching function (see       possible match, consider using the alternative matching  function  (see
       below) instead. If you cannot use the alternative function,  but  still       below)  instead.  If you cannot use the alternative function, but still
       need  to  find all possible matches, you can kludge it up by making use       need to find all possible matches, you can kludge it up by  making  use
        of the callout facility, which is described in the pcrecallout documen-         of the callout facility, which is described in the pcrecallout documen-
        tation.         tation.
   
        What you have to do is to insert a callout right at the end of the pat-         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-       tern.   When your callout function is called, extract and save the cur-
       rent  matched  substring.  Then  return  1, which forces pcre_exec() to       rent matched substring. Then return  1,  which  forces  pcre_exec()  to
       backtrack and try other alternatives. Ultimately, when it runs  out  of       backtrack  and  try other alternatives. Ultimately, when it runs out of
        matches, pcre_exec() will yield PCRE_ERROR_NOMATCH.         matches, pcre_exec() will yield PCRE_ERROR_NOMATCH.
   
   
   OBTAINING AN ESTIMATE OF STACK USAGE
   
          Matching certain patterns using pcre_exec() can use a  lot  of  process
          stack,  which  in  certain  environments can be rather limited in size.
          Some users find it helpful to have an estimate of the amount  of  stack
          that  is  used  by  pcre_exec(),  to help them set recursion limits, as
          described in the pcrestack documentation. The estimate that  is  output
          by pcretest when called with the -m and -C options is obtained by call-
          ing pcre_exec with the values NULL, NULL, NULL, -999, and -999 for  its
          first five arguments.
   
          Normally,  if  its  first  argument  is  NULL,  pcre_exec() immediately
          returns the negative error code PCRE_ERROR_NULL, but with this  special
          combination  of  arguments,  it returns instead a negative number whose
          absolute value is the approximate stack frame size in bytes.  (A  nega-
          tive  number  is  used so that it is clear that no match has happened.)
          The value is approximate because in  some  cases,  recursive  calls  to
          pcre_exec() occur when there are one or two additional variables on the
          stack.
   
          If PCRE has been compiled to use the heap  instead  of  the  stack  for
          recursion,  the  value  returned  is  the  size  of  each block that is
          obtained from the heap.
   
   
 MATCHING A PATTERN: THE ALTERNATIVE FUNCTION  MATCHING A PATTERN: THE ALTERNATIVE FUNCTION
   
        int pcre_dfa_exec(const pcre *code, const pcre_extra *extra,         int pcre_dfa_exec(const pcre *code, const pcre_extra *extra,
Line 2831  MATCHING A PATTERN: THE ALTERNATIVE FUNCTION Line 3313  MATCHING A PATTERN: THE ALTERNATIVE FUNCTION
             int options, int *ovector, int ovecsize,              int options, int *ovector, int ovecsize,
             int *workspace, int wscount);              int *workspace, int wscount);
   
       The  function  pcre_dfa_exec()  is  called  to  match  a subject string       The function pcre_dfa_exec()  is  called  to  match  a  subject  string
       against a compiled pattern, using a matching algorithm that  scans  the       against  a  compiled pattern, using a matching algorithm that scans the
       subject  string  just  once, and does not backtrack. This has different       subject string just once, and does not backtrack.  This  has  different
       characteristics to the normal algorithm, and  is  not  compatible  with       characteristics  to  the  normal  algorithm, and is not compatible with
       Perl.  Some  of the features of PCRE patterns are not supported. Never-       Perl. Some of the features of PCRE patterns are not  supported.  Never-
       theless, there are times when this kind of matching can be useful.  For       theless,  there are times when this kind of matching can be useful. For
       a  discussion  of  the  two matching algorithms, and a list of features       a discussion of the two matching algorithms, and  a  list  of  features
       that pcre_dfa_exec() does not support, see the pcrematching  documenta-       that  pcre_dfa_exec() does not support, see the pcrematching documenta-
        tion.         tion.
   
       The  arguments  for  the  pcre_dfa_exec()  function are the same as for       The arguments for the pcre_dfa_exec() function  are  the  same  as  for
        pcre_exec(), plus two extras. The ovector argument is used in a differ-         pcre_exec(), plus two extras. The ovector argument is used in a differ-
       ent  way,  and  this is described below. The other common arguments are       ent way, and this is described below. The other  common  arguments  are
       used in the same way as for pcre_exec(), so their  description  is  not       used  in  the  same way as for pcre_exec(), so their description is not
        repeated here.         repeated here.
   
       The  two  additional  arguments provide workspace for the function. The       The two additional arguments provide workspace for  the  function.  The
       workspace vector should contain at least 20 elements. It  is  used  for       workspace  vector  should  contain at least 20 elements. It is used for
        keeping  track  of  multiple  paths  through  the  pattern  tree.  More         keeping  track  of  multiple  paths  through  the  pattern  tree.  More
       workspace will be needed for patterns and subjects where  there  are  a       workspace  will  be  needed for patterns and subjects where there are a
        lot of potential matches.         lot of potential matches.
   
        Here is an example of a simple call to pcre_dfa_exec():         Here is an example of a simple call to pcre_dfa_exec():
Line 2872  MATCHING A PATTERN: THE ALTERNATIVE FUNCTION Line 3354  MATCHING A PATTERN: THE ALTERNATIVE FUNCTION
   
    Option bits for pcre_dfa_exec()     Option bits for pcre_dfa_exec()
   
       The  unused  bits  of  the options argument for pcre_dfa_exec() must be       The unused bits of the options argument  for  pcre_dfa_exec()  must  be
       zero. The only bits  that  may  be  set  are  PCRE_ANCHORED,  PCRE_NEW-       zero.  The  only  bits  that  may  be  set are PCRE_ANCHORED, PCRE_NEW-
        LINE_xxx,        PCRE_NOTBOL,        PCRE_NOTEOL,        PCRE_NOTEMPTY,         LINE_xxx,        PCRE_NOTBOL,        PCRE_NOTEOL,        PCRE_NOTEMPTY,
       PCRE_NOTEMPTY_ATSTART,      PCRE_NO_UTF8_CHECK,       PCRE_BSR_ANYCRLF,       PCRE_NOTEMPTY_ATSTART,       PCRE_NO_UTF8_CHECK,      PCRE_BSR_ANYCRLF,
       PCRE_BSR_UNICODE,  PCRE_NO_START_OPTIMIZE, PCRE_PARTIAL_HARD, PCRE_PAR-       PCRE_BSR_UNICODE, PCRE_NO_START_OPTIMIZE, PCRE_PARTIAL_HARD,  PCRE_PAR-
       TIAL_SOFT, PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART.  All but  the  last       TIAL_SOFT,  PCRE_DFA_SHORTEST,  and PCRE_DFA_RESTART.  All but the last
       four  of  these  are  exactly  the  same  as  for pcre_exec(), so their       four of these are  exactly  the  same  as  for  pcre_exec(),  so  their
        description is not repeated here.         description is not repeated here.
   
          PCRE_PARTIAL_HARD           PCRE_PARTIAL_HARD
          PCRE_PARTIAL_SOFT           PCRE_PARTIAL_SOFT
   
       These have the same general effect as they do for pcre_exec(), but  the       These  have the same general effect as they do for pcre_exec(), but the
       details  are  slightly  different.  When  PCRE_PARTIAL_HARD  is set for       details are slightly  different.  When  PCRE_PARTIAL_HARD  is  set  for
       pcre_dfa_exec(), it returns PCRE_ERROR_PARTIAL if the end of  the  sub-       pcre_dfa_exec(),  it  returns PCRE_ERROR_PARTIAL if the end of the sub-
       ject  is  reached  and there is still at least one matching possibility       ject is reached and there is still at least  one  matching  possibility
        that requires additional characters. This happens even if some complete         that requires additional characters. This happens even if some complete
        matches have also been found. When PCRE_PARTIAL_SOFT is set, the return         matches have also been found. When PCRE_PARTIAL_SOFT is set, the return
        code PCRE_ERROR_NOMATCH is converted into PCRE_ERROR_PARTIAL if the end         code PCRE_ERROR_NOMATCH is converted into PCRE_ERROR_PARTIAL if the end
       of  the  subject  is  reached, there have been no complete matches, but       of the subject is reached, there have been  no  complete  matches,  but
       there is still at least one matching possibility. The  portion  of  the       there  is  still  at least one matching possibility. The portion of the
       string  that  was inspected when the longest partial match was found is       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       set  as  the  first  matching  string  in  both cases.  There is a more
       detailed  discussion  of partial and multi-segment matching, with exam-       detailed discussion of partial and multi-segment matching,  with  exam-
        ples, in the pcrepartial documentation.         ples, in the pcrepartial documentation.
   
          PCRE_DFA_SHORTEST           PCRE_DFA_SHORTEST
   
       Setting the PCRE_DFA_SHORTEST option causes the matching  algorithm  to       Setting  the  PCRE_DFA_SHORTEST option causes the matching algorithm to
        stop as soon as it has found one match. Because of the way the alterna-         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       tive  algorithm  works, this is necessarily the shortest possible match
        at the first possible matching point in the subject string.         at the first possible matching point in the subject string.
   
          PCRE_DFA_RESTART           PCRE_DFA_RESTART
   
        When pcre_dfa_exec() returns a partial match, it is possible to call it         When pcre_dfa_exec() returns a partial match, it is possible to call it
       again, with additional subject characters, and have  it  continue  with       again,  with  additional  subject characters, and have it continue with
       the  same match. The PCRE_DFA_RESTART option requests this action; when       the same match. The PCRE_DFA_RESTART option requests this action;  when
       it is set, the workspace and wscount options must  reference  the  same       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       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         after a partial match. There is more discussion of this facility in the
        pcrepartial documentation.         pcrepartial documentation.
   
    Successful returns from pcre_dfa_exec()     Successful returns from pcre_dfa_exec()
   
       When  pcre_dfa_exec()  succeeds, it may have matched more than one sub-       When pcre_dfa_exec() succeeds, it may have matched more than  one  sub-
        string in the subject. Note, however, that all the matches from one run         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       of the function start at the same point in  the  subject.  The  shorter
       matches are all initial substrings of the longer matches. For  example,       matches  are all initial substrings of the longer matches. For example,
        if the pattern         if the pattern
   
          <.*>           <.*>
Line 2935  MATCHING A PATTERN: THE ALTERNATIVE FUNCTION Line 3417  MATCHING A PATTERN: THE ALTERNATIVE FUNCTION
          <something> <something else>           <something> <something else>
          <something> <something else> <something further>           <something> <something else> <something further>
   
       On  success,  the  yield of the function is a number greater than zero,       On success, the yield of the function is a number  greater  than  zero,
       which is the number of matched substrings.  The  substrings  themselves       which  is  the  number of matched substrings. The substrings themselves
       are  returned  in  ovector. Each string uses two elements; the first is       are returned in ovector. Each string uses two elements;  the  first  is
       the offset to the start, and the second is the offset to  the  end.  In       the  offset  to  the start, and the second is the offset to the end. In
       fact,  all  the  strings  have the same start offset. (Space could have       fact, all the strings have the same start  offset.  (Space  could  have
       been saved by giving this only once, but it was decided to retain  some       been  saved by giving this only once, but it was decided to retain some
       compatibility  with  the  way pcre_exec() returns data, even though the       compatibility with the way pcre_exec() returns data,  even  though  the
        meaning of the strings is different.)         meaning of the strings is different.)
   
        The strings are returned in reverse order of length; that is, the long-         The strings are returned in reverse order of length; that is, the long-
       est  matching  string is given first. If there were too many matches to       est matching string is given first. If there were too many  matches  to
       fit into ovector, the yield of the function is zero, and the vector  is       fit  into ovector, the yield of the function is zero, and the vector is
       filled  with  the  longest matches. Unlike pcre_exec(), pcre_dfa_exec()       filled with the longest matches.  Unlike  pcre_exec(),  pcre_dfa_exec()
        can use the entire ovector for returning matched strings.         can use the entire ovector for returning matched strings.
   
    Error returns from pcre_dfa_exec()     Error returns from pcre_dfa_exec()
   
       The pcre_dfa_exec() function returns a negative number when  it  fails.       The  pcre_dfa_exec()  function returns a negative number when it fails.
       Many  of  the  errors  are  the  same as for pcre_exec(), and these are       Many of the errors are the same  as  for  pcre_exec(),  and  these  are
       described above.  There are in addition the following errors  that  are       described  above.   There are in addition the following errors that are
        specific to pcre_dfa_exec():         specific to pcre_dfa_exec():
   
          PCRE_ERROR_DFA_UITEM      (-16)           PCRE_ERROR_DFA_UITEM      (-16)
   
       This  return is given if pcre_dfa_exec() encounters an item in the pat-       This return is given if pcre_dfa_exec() encounters an item in the  pat-
       tern that it does not support, for instance, the use of \C  or  a  back       tern  that  it  does not support, for instance, the use of \C or a back
        reference.         reference.
   
          PCRE_ERROR_DFA_UCOND      (-17)           PCRE_ERROR_DFA_UCOND      (-17)
   
       This  return  is  given  if pcre_dfa_exec() encounters a condition item       This return is given if pcre_dfa_exec()  encounters  a  condition  item
       that uses a back reference for the condition, or a test  for  recursion       that  uses  a back reference for the condition, or a test for recursion
        in a specific group. These are not supported.         in a specific group. These are not supported.
   
          PCRE_ERROR_DFA_UMLIMIT    (-18)           PCRE_ERROR_DFA_UMLIMIT    (-18)
   
       This  return  is given if pcre_dfa_exec() is called with an extra block       This return is given if pcre_dfa_exec() is called with an  extra  block
       that contains a setting of  the  match_limit  or  match_limit_recursion       that  contains  a  setting  of the match_limit or match_limit_recursion
       fields.  This  is  not  supported (these fields are meaningless for DFA       fields. This is not supported (these fields  are  meaningless  for  DFA
        matching).         matching).
   
          PCRE_ERROR_DFA_WSSIZE     (-19)           PCRE_ERROR_DFA_WSSIZE     (-19)
   
       This return is given if  pcre_dfa_exec()  runs  out  of  space  in  the       This  return  is  given  if  pcre_dfa_exec()  runs  out of space in the
        workspace vector.         workspace vector.
   
          PCRE_ERROR_DFA_RECURSE    (-20)           PCRE_ERROR_DFA_RECURSE    (-20)
   
       When  a  recursive subpattern is processed, the matching function calls       When a recursive subpattern is processed, the matching  function  calls
       itself recursively, using private vectors for  ovector  and  workspace.       itself  recursively,  using  private vectors for ovector and workspace.
       This  error  is  given  if  the output vector is not large enough. This       This error is given if the output vector  is  not  large  enough.  This
        should be extremely rare, as a vector of size 1000 is used.         should be extremely rare, as a vector of size 1000 is used.
   
            PCRE_ERROR_DFA_BADRESTART (-30)
   
          When  pcre_dfa_exec()  is called with the PCRE_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  SEE ALSO
   
       pcrebuild(3), pcrecallout(3), pcrecpp(3)(3), pcrematching(3),  pcrepar-       pcre16(3),  pcrebuild(3),  pcrecallout(3),  pcrecpp(3)(3),   pcrematch-
       tial(3), pcreposix(3), pcreprecompile(3), pcresample(3), pcrestack(3).       ing(3), pcrepartial(3), pcreposix(3), pcreprecompile(3), pcresample(3),
        pcrestack(3).
   
   
 AUTHOR  AUTHOR
Line 3004  AUTHOR Line 3494  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 02 December 2011       Last updated: 17 June 2012
       Copyright (c) 1997-2011 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 3020  PCRE CALLOUTS Line 3510  PCRE CALLOUTS
   
        int (*pcre_callout)(pcre_callout_block *);         int (*pcre_callout)(pcre_callout_block *);
   
          int (*pcre16_callout)(pcre16_callout_block *);
   
        PCRE provides a feature called "callout", which is a means of temporar-         PCRE provides a feature called "callout", which is a means of temporar-
        ily passing control to the caller of PCRE  in  the  middle  of  pattern         ily passing control to the caller of PCRE  in  the  middle  of  pattern
        matching.  The  caller of PCRE provides an external function by putting         matching.  The  caller of PCRE provides an external function by putting
       its entry point in the global variable pcre_callout. By  default,  this       its entry point in the global variable pcre_callout (pcre16_callout for
       variable contains NULL, which disables all calling out.       the  16-bit  library).  By  default, this variable contains NULL, which
        disables all calling out.
   
       Within  a  regular  expression,  (?C) indicates the points at which the       Within a regular expression, (?C) indicates the  points  at  which  the
       external function is to be called.  Different  callout  points  can  be       external  function  is  to  be  called. Different callout points can be
       identified  by  putting  a number less than 256 after the letter C. The       identified by putting a number less than 256 after the  letter  C.  The
       default value is zero.  For  example,  this  pattern  has  two  callout       default  value  is  zero.   For  example,  this pattern has two callout
        points:         points:
   
          (?C1)abc(?C2)def           (?C1)abc(?C2)def
   
       If  the  PCRE_AUTO_CALLOUT  option  bit  is  set when pcre_compile() or       If the PCRE_AUTO_CALLOUT option bit is set when a pattern is  compiled,
       pcre_compile2() is called, PCRE  automatically  inserts  callouts,  all       PCRE  automatically  inserts callouts, all with number 255, before each
       with  number  255,  before  each  item  in the pattern. For example, if       item in the pattern. For example, if PCRE_AUTO_CALLOUT is used with the
       PCRE_AUTO_CALLOUT is used with the pattern       pattern
   
          A(\d{2}|--)           A(\d{2}|--)
   
Line 3045  PCRE CALLOUTS Line 3538  PCRE CALLOUTS
   
        (?C255)A(?C255)((?C255)\d{2}(?C255)|(?C255)-(?C255)-(?C255))(?C255)         (?C255)A(?C255)((?C255)\d{2}(?C255)|(?C255)-(?C255)-(?C255))(?C255)
   
       Notice that there is a callout before and after  each  parenthesis  and       Notice  that  there  is a callout before and after each parenthesis and
       alternation  bar.  Automatic  callouts  can  be  used  for tracking the       alternation bar. Automatic  callouts  can  be  used  for  tracking  the
       progress of pattern matching. The pcretest command has an  option  that       progress  of  pattern matching. The pcretest command has an option that
       sets  automatic callouts; when it is used, the output indicates how the       sets automatic callouts; when it is used, the output indicates how  the
       pattern is matched. This is useful information when you are  trying  to       pattern  is  matched. This is useful information when you are trying to
        optimize the performance of a particular pattern.         optimize the performance of a particular pattern.
   
       The  use  of callouts in a pattern makes it ineligible for optimization       The use of callouts in a pattern makes it ineligible  for  optimization
        by  the  just-in-time  compiler.  Studying  such  a  pattern  with  the         by  the  just-in-time  compiler.  Studying  such  a  pattern  with  the
        PCRE_STUDY_JIT_COMPILE option always fails.         PCRE_STUDY_JIT_COMPILE option always fails.
   
   
 MISSING CALLOUTS  MISSING CALLOUTS
   
       You  should  be  aware  that,  because of optimizations in the way PCRE       You should be aware that, because of  optimizations  in  the  way  PCRE
       matches patterns by default, callouts  sometimes  do  not  happen.  For       matches  patterns  by  default,  callouts  sometimes do not happen. For
        example, if the pattern is         example, if the pattern is
   
          ab(?C4)cd           ab(?C4)cd
   
        PCRE knows that any matching string must contain the letter "d". If the         PCRE knows that any matching string must contain the letter "d". If the
       subject string is "abyz", the lack of "d" means that  matching  doesn't       subject  string  is "abyz", the lack of "d" means that matching doesn't
       ever  start,  and  the  callout is never reached. However, with "abyd",       ever start, and the callout is never  reached.  However,  with  "abyd",
        though the result is still no match, the callout is obeyed.         though the result is still no match, the callout is obeyed.
   
       If the pattern is studied, PCRE knows the minimum length of a  matching       If  the pattern is studied, PCRE knows the minimum length of a matching
       string,  and will immediately give a "no match" return without actually       string, and will immediately give a "no match" return without  actually
       running a match if the subject is not long enough, or,  for  unanchored       running  a  match if the subject is not long enough, or, for unanchored
        patterns, if it has been scanned far enough.         patterns, if it has been scanned far enough.
   
       You  can disable these optimizations by passing the PCRE_NO_START_OPTI-       You can disable these optimizations by passing the  PCRE_NO_START_OPTI-
       MIZE option to pcre_compile(), pcre_exec(), or pcre_dfa_exec(),  or  by       MIZE  option  to the matching function, or by starting the pattern with
       starting the pattern with (*NO_START_OPT). This slows down the matching       (*NO_START_OPT). This slows down the matching process, but does  ensure
       process, but does ensure that callouts such as the  example  above  are       that callouts such as the example above are obeyed.
       obeyed. 
   
   
 THE CALLOUT INTERFACE  THE CALLOUT INTERFACE
   
        During  matching, when PCRE reaches a callout point, the external func-         During  matching, when PCRE reaches a callout point, the external func-
       tion defined by pcre_callout is called (if it is set). This applies  to       tion defined by pcre_callout or pcre16_callout  is  called  (if  it  is
       both  the  pcre_exec()  and the pcre_dfa_exec() matching functions. The       set).   This applies to both normal and DFA matching. The only argument
       only argument to the callout function is a pointer  to  a  pcre_callout       to the callout function is a pointer to a pcre_callout or  pcre16_call-
       block. This structure contains the following fields:       out block.  These structures contains the following fields:
   
         int         version;         int           version;
         int         callout_number;         int           callout_number;
         int        *offset_vector;         int          *offset_vector;
         const char *subject;         const char   *subject;           (8-bit version)
         int         subject_length;         PCRE_SPTR16   subject;           (16-bit version)
         int         start_match;         int           subject_length;
         int         current_position;         int           start_match;
         int         capture_top;         int           current_position;
         int         capture_last;         int           capture_top;
         void       *callout_data;         int           capture_last;
         int         pattern_position;         void         *callout_data;
         int         next_item_length; 
         const unsigned char *mark;         int           next_item_length;
          const unsigned char *mark;       (8-bit version)
          const PCRE_UCHAR16  *mark;       (16-bit version)
   
        The  version  field  is an integer containing the version number of the         The  version  field  is an integer containing the version number of the
        block format. The initial version was 0; the current version is 2.  The         block format. The initial version was 0; the current version is 2.  The
Line 3114  THE CALLOUT INTERFACE Line 3608  THE CALLOUT INTERFACE
        outs, and 255 for automatically generated callouts).         outs, and 255 for automatically generated callouts).
   
        The offset_vector field is a pointer to the vector of offsets that  was         The offset_vector field is a pointer to the vector of offsets that  was
       passed   by   the   caller  to  pcre_exec()  or  pcre_dfa_exec().  When       passed  by  the  caller  to  the matching function. When pcre_exec() or
       pcre_exec() is used, the contents can be inspected in order to  extract       pcre16_exec() is used, the contents  can  be  inspected,  in  order  to
       substrings  that  have  been  matched  so  far,  in the same way as for       extract  substrings  that  have been matched so far, in the same way as
       extracting substrings after a match has completed. For  pcre_dfa_exec()       for extracting substrings after a match  has  completed.  For  the  DFA
       this field is not useful.       matching functions, this field is not useful.
   
        The subject and subject_length fields contain copies of the values that         The subject and subject_length fields contain copies of the values that
       were passed to pcre_exec().       were passed to the matching function.
   
        The start_match field normally contains the offset within  the  subject         The start_match field normally contains the offset within  the  subject
        at  which  the  current  match  attempt started. However, if the escape         at  which  the  current  match  attempt started. However, if the escape
Line 3133  THE CALLOUT INTERFACE Line 3627  THE CALLOUT INTERFACE
        The  current_position  field  contains the offset within the subject of         The  current_position  field  contains the offset within the subject of
        the current match pointer.         the current match pointer.
   
       When the pcre_exec() function is used, the capture_top  field  contains       When the pcre_exec() or pcre16_exec() is used,  the  capture_top  field
       one  more than the number of the highest numbered captured substring so       contains one more than the number of the highest numbered captured sub-
       far. If no substrings have been captured, the value of  capture_top  is       string so far. If no substrings have been captured, the value  of  cap-
       one.  This  is always the case when pcre_dfa_exec() is used, because it       ture_top  is  one.  This  is always the case when the DFA functions are
       does not support captured substrings.       used, because they do not support captured substrings.
   
        The capture_last field contains the number of the  most  recently  cap-         The capture_last field contains the number of the  most  recently  cap-
        tured  substring. If no substrings have been captured, its value is -1.         tured  substring. If no substrings have been captured, its value is -1.
       This is always the case when pcre_dfa_exec() is used.       This is always the case for the DFA matching functions.
   
       The callout_data field contains a value that is passed  to  pcre_exec()       The callout_data field contains a value that is passed  to  a  matching
       or  pcre_dfa_exec() specifically so that it can be passed back in call-       function  specifically so that it can be passed back in callouts. It is
       outs. It is passed in the pcre_callout field  of  the  pcre_extra  data       passed in the callout_data field of a pcre_extra or  pcre16_extra  data
        structure.  If  no such data was passed, the value of callout_data in a         structure.  If  no such data was passed, the value of callout_data in a
       pcre_callout block is NULL. There is a description  of  the  pcre_extra       callout block is NULL. There is a description of the pcre_extra  struc-
       structure in the pcreapi documentation.       ture in the pcreapi documentation.
   
       The  pattern_position field is present from version 1 of the pcre_call-       The  pattern_position  field  is  present from version 1 of the callout
       out structure. It contains the offset to the next item to be matched in       structure. It contains the offset to the next item to be matched in the
       the pattern string.       pattern string.
   
       The  next_item_length field is present from version 1 of the pcre_call-       The  next_item_length  field  is  present from version 1 of the callout
       out structure. It contains the length of the next item to be matched in       structure. It contains the length of the next item to be matched in the
       the  pattern  string. When the callout immediately precedes an alterna-       pattern  string.  When  the callout immediately precedes an alternation
       tion bar, a closing parenthesis, or the end of the pattern, the  length       bar, a closing parenthesis, or the end of the pattern,  the  length  is
       is  zero.  When the callout precedes an opening parenthesis, the length       zero.  When  the callout precedes an opening parenthesis, the length is
       is that of the entire subpattern.       that of the entire subpattern.
   
        The pattern_position and next_item_length fields are intended  to  help         The pattern_position and next_item_length fields are intended  to  help
        in  distinguishing between different automatic callouts, which all have         in  distinguishing between different automatic callouts, which all have
        the same callout number. However, they are set for all callouts.         the same callout number. However, they are set for all callouts.
   
       The mark field is present from version 2 of the pcre_callout structure.       The mark field is present from version 2 of the callout  structure.  In
       In  callouts  from pcre_exec() it contains a pointer to the zero-termi-       callouts from pcre_exec() or pcre16_exec() it contains a pointer to the
       nated name of the most recently passed (*MARK),  (*PRUNE),  or  (*THEN)       zero-terminated name of the most recently passed (*MARK), (*PRUNE),  or
       item in the match, or NULL if no such items have been passed. Instances       (*THEN)  item  in the match, or NULL if no such items have been passed.
       of (*PRUNE) or (*THEN) without a name  do  not  obliterate  a  previous       Instances of (*PRUNE) or (*THEN) without a name  do  not  obliterate  a
       (*MARK).  In  callouts  from pcre_dfa_exec() this field always contains       previous  (*MARK).  In  callouts  from  the DFA matching functions this
       NULL.       field always contains NULL.
   
   
 RETURN VALUES  RETURN VALUES
Line 3180  RETURN VALUES Line 3674  RETURN VALUES
        is  zero,  matching  proceeds  as  normal. If the value is greater than         is  zero,  matching  proceeds  as  normal. If the value is greater than
        zero, matching fails at the current point, but  the  testing  of  other         zero, matching fails at the current point, but  the  testing  of  other
        matching possibilities goes ahead, just as if a lookahead assertion had         matching possibilities goes ahead, just as if a lookahead assertion had
       failed. If the value is less than zero, the  match  is  abandoned,  and       failed. If the value is less than zero, the  match  is  abandoned,  the
       pcre_exec() or pcre_dfa_exec() returns the negative value.       matching function returns the negative value.
   
        Negative   values   should   normally   be   chosen  from  the  set  of         Negative   values   should   normally   be   chosen  from  the  set  of
        PCRE_ERROR_xxx values. In particular, PCRE_ERROR_NOMATCH forces a stan-         PCRE_ERROR_xxx values. In particular, PCRE_ERROR_NOMATCH forces a stan-
Line 3199  AUTHOR Line 3693  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 30 November 2011       Last updated: 08 Janurary 2012
       Copyright (c) 1997-2011 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 3217  DIFFERENCES BETWEEN PCRE AND PERL Line 3711  DIFFERENCES BETWEEN PCRE AND PERL
        handle regular expressions. The differences  described  here  are  with         handle regular expressions. The differences  described  here  are  with
        respect to Perl versions 5.10 and above.         respect to Perl versions 5.10 and above.
   
       1.  PCRE has only a subset of Perl's UTF-8 and Unicode support. Details       1. PCRE has only a subset of Perl's Unicode support. Details of what it
       of what it does have are given in the pcreunicode page.       does have are given in the pcreunicode page.
   
        2. PCRE allows repeat quantifiers only on parenthesized assertions, but         2. PCRE allows repeat quantifiers only on parenthesized assertions, but
        they  do  not mean what you might think. For example, (?!a){3} does not         they  do  not mean what you might think. For example, (?!a){3} does not
Line 3292  DIFFERENCES BETWEEN PCRE AND PERL Line 3786  DIFFERENCES BETWEEN PCRE AND PERL
        There is a discussion that explains these differences in more detail in         There is a discussion that explains these differences in more detail in
        the section on recursion differences from Perl in the pcrepattern page.         the section on recursion differences from Perl in the pcrepattern page.
   
       11.  If  (*THEN)  is present in a group that is called as a subroutine,       11.  If  any of the backtracking control verbs are used in an assertion
       its action is limited to that group, even if the group does not contain       or in a subpattern that is called  as  a  subroutine  (whether  or  not
       any | characters.       recursively),  their effect is confined to that subpattern; it does not
        extend to the surrounding pattern. This is not always the case in Perl.
        In  particular,  if  (*THEN)  is present in a group that is called as a
        subroutine, its action is limited to that group, even if the group does
        not  contain any | characters. There is one exception to this: the name
        from a *(MARK), (*PRUNE), or (*THEN) that is encountered in a  success-
        ful  positive  assertion  is passed back when a match succeeds (compare
        capturing parentheses in assertions). Note that  such  subpatterns  are
        processed as anchored at the point where they are tested.
   
        12.  There are some differences that are concerned with the settings of         12.  There are some differences that are concerned with the settings of
        captured strings when part of  a  pattern  is  repeated.  For  example,         captured strings when part of  a  pattern  is  repeated.  For  example,
Line 3314  DIFFERENCES BETWEEN PCRE AND PERL Line 3816  DIFFERENCES BETWEEN PCRE AND PERL
   
        14.  Perl  recognizes  comments  in some places that PCRE does not, for         14.  Perl  recognizes  comments  in some places that PCRE does not, for
        example, between the ( and ? at the start of a subpattern.  If  the  /x         example, between the ( and ? at the start of a subpattern.  If  the  /x
       modifier  is set, Perl allows whitespace between ( and ? but PCRE never       modifier is set, Perl allows white space between ( and ? but PCRE never
        does, even if the PCRE_EXTENDED option is set.         does, even if the PCRE_EXTENDED option is set.
   
        15. PCRE provides some extensions to the Perl regular expression facil-         15. PCRE provides some extensions to the Perl regular expression facil-
Line 3356  DIFFERENCES BETWEEN PCRE AND PERL Line 3858  DIFFERENCES BETWEEN PCRE AND PERL
        even on different hosts that have the other endianness.  However,  this         even on different hosts that have the other endianness.  However,  this
        does not apply to optimized data created by the just-in-time compiler.         does not apply to optimized data created by the just-in-time compiler.
   
       (k)  The  alternative  matching function (pcre_dfa_exec()) matches in a       (k)   The   alternative   matching   functions   (pcre_dfa_exec()   and
       different way and is not Perl-compatible.       pcre16_dfa_exec()) match in a different way and are  not  Perl-compati-
        ble.
   
       (l) PCRE recognizes some special sequences such as (*CR) at  the  start       (l)  PCRE  recognizes some special sequences such as (*CR) at the start
        of a pattern that set overall options that cannot be changed within the         of a pattern that set overall options that cannot be changed within the
        pattern.         pattern.
   
Line 3373  AUTHOR Line 3876  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 14 November 2011       Last updated: 01 June 2012
       Copyright (c) 1997-2011 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 3403  PCRE REGULAR EXPRESSION DETAILS Line 3906  PCRE REGULAR EXPRESSION DETAILS
        intended as reference material.         intended as reference material.
   
        The original operation of PCRE was on strings of  one-byte  characters.         The original operation of PCRE was on strings of  one-byte  characters.
       However,  there is now also support for UTF-8 character strings. To use       However,  there  is  now also support for UTF-8 strings in the original
       this, PCRE must be built to include UTF-8 support, and  you  must  call       library, and a second library that supports 16-bit and UTF-16 character
       pcre_compile()  or  pcre_compile2() with the PCRE_UTF8 option. There is       strings. To use these features, PCRE must be built to include appropri-
       also a special sequence that can be given at the start of a pattern:       ate support. When using UTF strings you must either call the  compiling
        function  with  the PCRE_UTF8 or PCRE_UTF16 option, or the pattern must
        start with one of these special sequences:
   
          (*UTF8)           (*UTF8)
            (*UTF16)
   
       Starting a pattern with this sequence  is  equivalent  to  setting  the       Starting a pattern with such a sequence is equivalent  to  setting  the
       PCRE_UTF8  option.  This  feature  is  not Perl-compatible. How setting       relevant option. This feature is not Perl-compatible. How setting a UTF
       UTF-8 mode affects pattern matching  is  mentioned  in  several  places       mode affects pattern matching is mentioned  in  several  places  below.
       below.  There  is  also  a summary of UTF-8 features in the pcreunicode       There is also a summary of features in the pcreunicode page.
       page. 
   
       Another special sequence that may appear at the start of a  pattern  or       Another  special  sequence that may appear at the start of a pattern or
       in combination with (*UTF8) is:       in combination with (*UTF8) or (*UTF16) is:
   
          (*UCP)           (*UCP)
   
       This  has  the  same  effect  as setting the PCRE_UCP option: it causes       This has the same effect as setting  the  PCRE_UCP  option:  it  causes
       sequences such as \d and \w to  use  Unicode  properties  to  determine       sequences  such  as  \d  and  \w to use Unicode properties to determine
        character types, instead of recognizing only characters with codes less         character types, instead of recognizing only characters with codes less
        than 128 via a lookup table.         than 128 via a lookup table.
   
       If a pattern starts with (*NO_START_OPT), it has  the  same  effect  as       If  a  pattern  sta       If  a  pattern  sta
        setting the PCRE_NO_START_OPTIMIZE option either at compile or matching         setting the PCRE_NO_START_OPTIMIZE option either at compile or matching
        time. There are also some more of these special sequences that are con-         time. There are also some more of these special sequences that are con-
        cerned with the handling of newlines; they are described below.         cerned with the handling of newlines; they are described below.
   
       The  remainder  of  this  document discusses the patterns that are sup-       The remainder of this document discusses the  patterns  that  are  sup-
       ported by PCRE when its main matching function, pcre_exec(),  is  used.       ported  by  PCRE  when  one  its  main  matching functions, pcre_exec()
       From   release   6.0,   PCRE   offers   a   second  matching  function,       (8-bit) or pcre16_exec() (16-bit), is used. PCRE also  has  alternative
       pcre_dfa_exec(), which matches using a different algorithm that is  not       matching  functions, pcre_dfa_exec() and pcre16_dfa_exec(), which match
       Perl-compatible. Some of the features discussed below are not available       using a different algorithm that is not Perl-compatible.  Some  of  the
       when pcre_dfa_exec() is used. The advantages and disadvantages  of  the       features  discussed  below are not available when DFA matching is used.
       alternative  function, and how it differs from the normal function, are       The advantages and disadvantages of the alternative functions, and  how
       discussed in the pcrematching page.       they  differ from the normal functions, are discussed in the pcrematch-
        ing page.
   
   
 NEWLINE CONVENTIONS  NEWLINE CONVENTIONS
Line 3459  NEWLINE CONVENTIONS Line 3965  NEWLINE CONVENTIONS
          (*ANYCRLF)   any of the three above           (*ANYCRLF)   any of the three above
          (*ANY)       all Unicode newline sequences           (*ANY)       all Unicode newline sequences
   
       These override the default and the options given to  pcre_compile()  or       These override the default and the options given to the compiling func-
       pcre_compile2().  For example, on a Unix system where LF is the default       tion.  For  example,  on  a Unix system where LF is the default newline
       newline sequence, the pattern       sequence, the pattern
   
          (*CR)a.b           (*CR)a.b
   
Line 3491  CHARACTERS AND METACHARACTERS Line 3997  CHARACTERS AND METACHARACTERS
   
        matches a portion of a subject string that is identical to itself. When         matches a portion of a subject string that is identical to itself. When
        caseless matching is specified (the PCRE_CASELESS option), letters  are         caseless matching is specified (the PCRE_CASELESS option), letters  are
       matched  independently  of case. In UTF-8 mode, PCRE always understands       matched  independently  of case. In a UTF mode, PCRE always understands
        the concept of case for characters whose values are less than  128,  so         the concept of case for characters whose values are less than  128,  so
        caseless  matching  is always possible. For characters with higher val-         caseless  matching  is always possible. For characters with higher val-
        ues, the concept of case is supported if PCRE is compiled with  Unicode         ues, the concept of case is supported if PCRE is compiled with  Unicode
        property  support,  but  not  otherwise.   If  you want to use caseless         property  support,  but  not  otherwise.   If  you want to use caseless
        matching for characters 128 and above, you must  ensure  that  PCRE  is         matching for characters 128 and above, you must  ensure  that  PCRE  is
       compiled with Unicode property support as well as with UTF-8 support.       compiled with Unicode property support as well as with UTF support.
   
        The  power  of  regular  expressions  comes from the ability to include         The  power  of  regular  expressions  comes from the ability to include
        alternatives and repetitions in the pattern. These are encoded  in  the         alternatives and repetitions in the pattern. These are encoded  in  the
Line 3552  BACKSLASH Line 4058  BACKSLASH
        that  it stands for itself. In particular, if you want to match a back-         that  it stands for itself. In particular, if you want to match a back-
        slash, you write \\.         slash, you write \\.
   
       In UTF-8 mode, only ASCII numbers and letters have any special  meaning       In a UTF mode, only ASCII numbers and letters have any special  meaning
        after  a  backslash.  All  other characters (in particular, those whose         after  a  backslash.  All  other characters (in particular, those whose
        codepoints are greater than 127) are treated as literals.         codepoints are greater than 127) are treated as literals.
   
       If a pattern is compiled with the PCRE_EXTENDED option,  whitespace  in       If a pattern is compiled with the PCRE_EXTENDED option, white space  in
        the  pattern (other than in a character class) and characters between a         the  pattern (other than in a character class) and characters between a
        # outside a character class and the next newline are ignored. An escap-         # outside a character class and the next newline are ignored. An escap-
       ing  backslash  can  be  used to include a whitespace or # character as       ing  backslash  can  be used to include a white space or # character as
        part of the pattern.         part of the pattern.
   
        If you want to remove the special meaning from a  sequence  of  charac-         If you want to remove the special meaning from a  sequence  of  charac-
Line 3594  BACKSLASH Line 4100  BACKSLASH
          \a        alarm, that is, the BEL character (hex 07)           \a        alarm, that is, the BEL character (hex 07)
          \cx       "control-x", where x is any ASCII character           \cx       "control-x", where x is any ASCII character
          \e        escape (hex 1B)           \e        escape (hex 1B)
         \f        formfeed (hex 0C)         \f        form feed (hex 0C)
          \n        linefeed (hex 0A)           \n        linefeed (hex 0A)
          \r        carriage return (hex 0D)           \r        carriage return (hex 0D)
          \t        tab (hex 09)           \t        tab (hex 09)
Line 3608  BACKSLASH Line 4114  BACKSLASH
        inverted.  Thus \cz becomes hex 1A (z is 7A), but \c{ becomes hex 3B ({         inverted.  Thus \cz becomes hex 1A (z is 7A), but \c{ becomes hex 3B ({
        is  7B),  while  \c; becomes hex 7B (; is 3B). If the byte following \c         is  7B),  while  \c; becomes hex 7B (; is 3B). If the byte following \c
        has a value greater than 127, a compile-time error occurs.  This  locks         has a value greater than 127, a compile-time error occurs.  This  locks
       out  non-ASCII  characters in both byte mode and UTF-8 mode. (When PCRE       out non-ASCII characters in all modes. (When PCRE is compiled in EBCDIC
       is compiled in EBCDIC mode, all byte values are  valid.  A  lower  case       mode, all byte values are valid. A lower case letter  is  converted  to
       letter is converted to upper case, and then the 0xc0 bits are flipped.)       upper case, and then the 0xc0 bits are flipped.)
   
        By  default,  after  \x,  from  zero to two hexadecimal digits are read         By  default,  after  \x,  from  zero to two hexadecimal digits are read
        (letters can be in upper or lower case). Any number of hexadecimal dig-         (letters can be in upper or lower case). Any number of hexadecimal dig-
       its  may  appear between \x{ and }, but the value of the character code       its may appear between \x{ and }, but the character code is constrained
       must be less than 256 in non-UTF-8 mode, and less than 2**31  in  UTF-8       as follows:
       mode.  That is, the maximum value in hexadecimal is 7FFFFFFF. Note that 
       this is bigger than the largest Unicode code point, which is 10FFFF. 
   
       If characters other than hexadecimal digits appear between \x{  and  },        or if there is no terminating }, this form of escape is not recognized.
          8-bit UTF-8 mode      less than 0x10ffff and a valid codepoint
          16-bit non-UTF mode   less than 0x10000
          16-bit UTF-16 mode    less than 0x10ffff and a valid codepoint
 
        Invalid Unicode codepoints are the range  0xd800  to  0xdfff  (the  so-
        called "surrogate" codepoints).
 
        If  characters  other than hexadecimal digits appear between \x{ and },
        or if there is no terminating }, this form of escape is not recognized.         or if there is no terminating }, this form of escape is not recognized.
       Instead, the initial \x will be  interpreted  as  a  basic  hexadecimal       Instead,  the  initial  \x  will  be interpreted as a basic hexadecimal
       escape,  with  no  following  digits, giving a character whose value is       escape, with no following digits, giving a  character  whose  value  is
        zero.         zero.
   
       If the PCRE_JAVASCRIPT_COMPAT option is set, the interpretation  of  \x       If  the  PCRE_JAVASCRIPT_COMPAT option is set, the interpretation of \x
       is  as  just described only when it is followed by two hexadecimal dig-       is as just described only when it is followed by two  hexadecimal  dig-
       its.  Otherwise, it matches a  literal  "x"  character.  In  JavaScript       its.   Otherwise,  it  matches  a  literal "x" character. In JavaScript
        mode, support for code points greater than 256 is provided by \u, which         mode, support for code points greater than 256 is provided by \u, which
       must be followed by four hexadecimal digits;  otherwise  it  matches  a       must  be  followed  by  four hexadecimal digits; otherwise it matches a
       literal "u" character.       literal "u" character.  Character codes specified by \u  in  JavaScript
        mode  are  constrained in the same was as those specified by \x in non-
        JavaScript mode.
   
        Characters whose value is less than 256 can be defined by either of the         Characters whose value is less than 256 can be defined by either of the
       two syntaxes for \x (or by \u in JavaScript mode). There is no  differ-       two  syntaxes for \x (or by \u in JavaScript mode). There is no differ-
        ence in the way they are handled. For example, \xdc is exactly the same         ence in the way they are handled. For example, \xdc is exactly the same
        as \x{dc} (or \u00dc in JavaScript mode).         as \x{dc} (or \u00dc in JavaScript mode).
   
       After \0 up to two further octal digits are read. If  there  are  fewer       After  \0  up  to two further octal digits are read. If there are fewer
       than  two  digits,  just  those  that  are  present  are used. Thus the       than two digits, just  those  that  are  present  are  used.  Thus  the
        sequence \0\x\07 specifies two binary zeros followed by a BEL character         sequence \0\x\07 specifies two binary zeros followed by a BEL character
       (code  value 7). Make sure you supply two digits after the initial zero       (code value 7). Make sure you supply two digits after the initial  zero
        if the pattern character that follows is itself an octal digit.         if the pattern character that follows is itself an octal digit.
   
        The handling of a backslash followed by a digit other than 0 is compli-         The handling of a backslash followed by a digit other than 0 is compli-
        cated.  Outside a character class, PCRE reads it and any following dig-         cated.  Outside a character class, PCRE reads it and any following dig-
       its as a decimal number. If the number is less than  10,  or  if  there       its  as  a  decimal  number. If the number is less        its  as  a  decimal  number. If the number is less than 10, or if there
        have been at least that many previous capturing left parentheses in the         have been at least that many previous capturing left parentheses in the
       expression, the entire  sequence  is  taken  as  a  back  reference.  A       expression,  the  entire  sequence  is  taken  as  a  back reference. A
       description  of how this works is given later, following the discussion       description of how this works is given later, following the  discussion
        of parenthesized subpatterns.         of parenthesized subpatterns.
   
       Inside a character class, or if the decimal number is  greater  than  9       Inside  a  character  class, or if the decimal number is greater than 9
       and  there have not been that many capturing subpatterns, PCRE re-reads       and there have not been that many capturing subpatterns, PCRE  re-reads
        up to three octal digits following the backslash, and uses them to gen-         up to three octal digits following the backslash, and uses them to gen-
       erate  a data character. Any subsequent digits stand for themselves. In       erate a data character. Any subsequent digits stand for themselves. The
       non-UTF-8 mode, the value of a character specified  in  octal  must  be       value  of  the  character  is constrained in the same way as characters
       less  than  \400.  In  UTF-8 mode, values up to \777 are permitted. For       specified in hexadecimal.  For example:
       example: 
   
          \040   is another way of writing a space           \040   is another way of writing a space
          \40    is the same, provided there are fewer than 40           \40    is the same, provided there are fewer than 40
Line 3670  BACKSLASH Line 4183  BACKSLASH
          \113   might be a back reference, otherwise the           \113   might be a back reference, otherwise the
                    character with octal code 113                     character with octal code 113
          \377   might be a back reference, otherwise           \377   might be a back reference, otherwise
                   the byte consisting entirely of 1 bits                   the value 255 (decimal)
          \81    is either a back reference, or a binary zero           \81    is either a back reference, or a binary zero
                    followed by the two characters "8" and "1"                     followed by the two characters "8" and "1"
   
Line 3718  BACKSLASH Line 4231  BACKSLASH
   
          \d     any decimal digit           \d     any decimal digit
          \D     any character that is not a decimal digit           \D     any character that is not a decimal digit
         \h     any horizontal whitespace character         \h     any horizontal white space character
         \H     any character that is not a horizontal whitespace character         \H     any character that is not a horizontal white space character
         \s     any whitespace character         \s     any white space character
         \S     any character that is not a whitespace character         \S     any character that is not a white space character
         \v     any vertical whitespace character         \v     any vertical white space character
         \V     any character that is not a vertical whitespace character         \V     any character that is not a vertical white space character
          \w     any "word" character           \w     any "word" character
          \W     any "non-word" character           \W     any "non-word" character
   
Line 3755  BACKSLASH Line 4268  BACKSLASH
        are  used  for  accented letters, and these are then matched by \w. The         are  used  for  accented letters, and these are then matched by \w. The
        use of locales with Unicode is discouraged.         use of locales with Unicode is discouraged.
   
       By default, in UTF-8 mode, characters  with  values  greater  than  128       By default, in a UTF mode, characters  with  values  greater  than  128
        never  match  \d,  \s,  or  \w,  and always match \D, \S, and \W. These         never  match  \d,  \s,  or  \w,  and always match \D, \S, and \W. These
       sequences retain their original meanings from before UTF-8 support  was       sequences retain their original meanings from before  UTF  support  was
        available,  mainly for efficiency reasons. However, if PCRE is compiled         available,  mainly for efficiency reasons. However, if PCRE is compiled
        with Unicode property support, and the PCRE_UCP option is set, the  be-         with Unicode property support, and the PCRE_UCP option is set, the  be-
        haviour  is  changed  so  that Unicode properties are used to determine         haviour  is  changed  so  that Unicode properties are used to determine
Line 3776  BACKSLASH Line 4289  BACKSLASH
        The sequences \h, \H, \v, and \V are features that were added  to  Perl         The sequences \h, \H, \v, and \V are features that were added  to  Perl
        at  release  5.10. In contrast to the other sequences, which match only         at  release  5.10. In contrast to the other sequences, which match only
        ASCII characters by default, these  always  match  certain  high-valued         ASCII characters by default, these  always  match  certain  high-valued
       codepoints  in UTF-8 mode, whether or not PCRE_UCP is set. The horizon-       codepoints,  whether or not PCRE_UCP is set. The horizontal space char-
       tal space characters are:       acters are:
   
          U+0009     Horizontal tab           U+0009     Horizontal tab
          U+0020     Space           U+0020     Space
Line 3803  BACKSLASH Line 4316  BACKSLASH
   
          U+000A     Linefeed           U+000A     Linefeed
          U+000B     Vertical tab           U+000B     Vertical tab
         U+000C     Formfeed         U+000C     Form feed
          U+000D     Carriage return           U+000D     Carriage return
          U+0085     Next line           U+0085     Next line
          U+2028     Line separator           U+2028     Line separator
          U+2029     Paragraph separator           U+2029     Paragraph separator
   
          In 8-bit, non-UTF-8 mode, only the characters with codepoints less than
          256 are relevant.
   
    Newline sequences     Newline sequences
   
       Outside a character class, by default, the escape sequence  \R  matches       Outside  a  character class, by default, the escape sequence \R matches
       any Unicode newline sequence. In non-UTF-8 mode \R is equivalent to the       any Unicode newline sequence. In 8-bit non-UTF-8 mode \R is  equivalent
       following:       to the following:
   
          (?>\r\n|\n|\x0b|\f|\r|\x85)           (?>\r\n|\n|\x0b|\f|\r|\x85)
   
       This is an example of an "atomic group", details  of  which  are  given       This  is  an  example  of an "atomic group", details of which are given
        below.  This particular group matches either the two-character sequence         below.  This particular group matches either the two-character sequence
       CR followed by LF, or  one  of  the  single  characters  LF  (linefeed,       CR  followed  by  LF,  or  one  of  the single characters LF (linefeed,
       U+000A), VT (vertical tab, U+000B), FF (formfeed, U+000C), CR (carriage       U+000A), VT (vertical tab, U+000B), FF (form feed,  U+000C),  CR  (car-
       return, U+000D), or NEL (next line, U+0085). The two-character sequence       riage  return,  U+000D),  or NEL (next line, U+0085). The two-character
       is treated as a single unit that cannot be split.       sequence is treated as a single unit that cannot be split.
   
       In  UTF-8  mode, two additional characters whose codepoints are greater       In other modes, two additional characters whose codepoints are  greater
        than 255 are added: LS (line separator, U+2028) and PS (paragraph sepa-         than 255 are added: LS (line separator, U+2028) and PS (paragraph sepa-
       rator,  U+2029).   Unicode character property support is not needed for       rator, U+2029).  Unicode character property support is not  needed  for
        these characters to be recognized.         these characters to be recognized.
   
        It is possible to restrict \R to match only CR, LF, or CRLF (instead of         It is possible to restrict \R to match only CR, LF, or CRLF (instead of
       the  complete  set  of  Unicode  line  endings)  by  setting the option       the complete set  of  Unicode  line  endings)  by  setting  the  option
        PCRE_BSR_ANYCRLF either at compile time or when the pattern is matched.         PCRE_BSR_ANYCRLF either at compile time or when the pattern is matched.
        (BSR is an abbrevation for "backslash R".) This can be made the default         (BSR is an abbrevation for "backslash R".) This can be made the default
       when PCRE is built; if this is the case, the  other  behaviour  can  be       when  PCRE  is  built;  if this is the case, the other behaviour can be
       requested  via  the  PCRE_BSR_UNICODE  option.   It is also possible to       requested via the PCRE_BSR_UNICODE option.   It  is  also  possible  to
       specify these settings by starting a pattern string  with  one  of  the       specify  these  settings  by  starting a pattern string with one of the
        following sequences:         following sequences:
   
          (*BSR_ANYCRLF)   CR, LF, or CRLF only           (*BSR_ANYCRLF)   CR, LF, or CRLF only
          (*BSR_UNICODE)   any Unicode newline sequence           (*BSR_UNICODE)   any Unicode newline sequence
   
       These  override  the default and the options given to pcre_compile() or       These override the default and the options given to the compiling func-
       pcre_compile2(), but  they  can  be  overridden  by  options  given  to       tion,  but  they  can  themselves  be  overridden by options given to a
       pcre_exec() or pcre_dfa_exec(). Note that these special settings, which       matching function. Note that these  special  settings,  which  are  not
       are not Perl-compatible, are recognized only at the  very  start  of  a       Perl-compatible,  are  recognized  only at the very start of a pattern,
       pattern,  and that they must be in upper case. If more than one of them       and that they must be in upper case.  If  more  than  one  of  them  is
       is present, the last one is used. They can be combined with a change of       present,  the  last  one is used. They can be combined with a change of
        newline convention; for example, a pattern can start with:         newline convention; for example, a pattern can start with:
   
          (*ANY)(*BSR_ANYCRLF)           (*ANY)(*BSR_ANYCRLF)
   
       They can also be combined with the (*UTF8) or (*UCP) special sequences.       They can also be combined with the (*UTF8), (*UTF16), or (*UCP) special
       Inside a character class, \R  is  treated  as  an  unrecognized  escape       sequences.  Inside  a character class, \R is treated as an unrecognized
       sequence, and so matches the letter "R" by default, but causes an error       escape sequence, and so matches the letter "R" by default,  but  causes
       if PCRE_EXTRA is set.       an error if PCRE_EXTRA is set.
   
    Unicode character properties     Unicode character properties
   
        When PCRE is built with Unicode character property support, three addi-         When PCRE is built with Unicode character property support, three addi-
       tional  escape sequences that match characters with specific properties       tional escape sequences that match characters with specific  properties
       are available.  When not in UTF-8 mode, these sequences are  of  course       are  available.   When  in 8-bit non-UTF-8 mode, these sequences are of
       limited  to  testing characters whose codepoints are less than 256, but       course limited to testing characters whose  codepoints  are  less  than
       they do work in this mode.  The extra escape sequences are:       256, but they do work in this mode.  The extra escape sequences are:
   
          \p{xx}   a character with the xx property           \p{xx}   a character with the xx property
          \P{xx}   a character without the xx property           \P{xx}   a character without the xx property
          \X       an extended Unicode sequence           \X       an extended Unicode sequence
   
       The property names represented by xx above are limited to  the  Unicode       The  property  names represented by xx above are limited to the Unicode
        script names, the general category properties, "Any", which matches any         script names, the general category properties, "Any", which matches any
       character  (including  newline),  and  some  special  PCRE   properties       character   (including  newline),  and  some  special  PCRE  properties
       (described  in the next section).  Other Perl properties such as "InMu-       (described in the next section).  Other Perl properties such as  "InMu-
       sicalSymbols" are not currently supported by PCRE.  Note  that  \P{Any}       sicalSymbols"  are  not  currently supported by PCRE. Note that \P{Any}
        does not match any characters, so always causes a match failure.         does not match any characters, so always causes a match failure.
   
        Sets of Unicode characters are defined as belonging to certain scripts.         Sets of Unicode characters are defined as belonging to certain scripts.
       A character from one of these sets can be matched using a script  name.       A  character from one of these sets can be matched using a script name.
        For example:         For example:
   
          \p{Greek}           \p{Greek}
          \P{Han}           \P{Han}
   
       Those  that are not part of an identified script are lumped together as       Those that are not part of an identified script are lumped together  as
        "Common". The current list of scripts is:         "Common". The current list of scripts is:
   
       Arabic, Armenian, Avestan, Balinese, Bamum, Bengali, Bopomofo, Braille,       Arabic,  Armenian,  Avestan, Balinese, Bamum, Batak, Bengali, Bopomofo,
       Buginese,  Buhid,  Canadian_Aboriginal, Carian, Cham, Cherokee, Common,       Brahmi, Braille, Buginese, Buhid, Canadian_Aboriginal, Carian,  Chakma,
       Coptic,  Cuneiform,  Cypriot,  Cyrillic,  Deseret,  Devanagari,   Egyp-       Cham,  Cherokee, Common, Coptic, Cuneiform, Cypriot, Cyrillic, Deseret,
       tian_Hieroglyphs,   Ethiopic,   Georgian,  Glagolitic,  Gothic,  Greek,       Devanagari,  Egyptian_Hieroglyphs,  Ethiopic,   Georgian,   Glagolitic,
       Gujarati, Gurmukhi,  Han,  Hangul,  Hanunoo,  Hebrew,  Hiragana,  Impe-       Gothic,  Greek, Gujarati, Gurmukhi, Han, Hangul, Hanunoo, Hebrew, Hira-
       rial_Aramaic, Inherited, Inscriptional_Pahlavi, Inscriptional_Parthian,       gana,  Imperial_Aramaic,  Inherited,  Inscriptional_Pahlavi,   Inscrip-
       Javanese, Kaithi, Kannada, Katakana, Kayah_Li, Kharoshthi, Khmer,  Lao,       tional_Parthian,   Javanese,   Kaithi,   Kannada,  Katakana,  Kayah_Li,
       Latin,  Lepcha,  Limbu,  Linear_B,  Lisu,  Lycian,  Lydian,  Malayalam,       Kharoshthi, Khmer, Lao, Latin, Lepcha, Limbu, Linear_B,  Lisu,  Lycian,
       Meetei_Mayek, Mongolian, Myanmar, New_Tai_Lue, Nko, Ogham,  Old_Italic,       Lydian,    Malayalam,    Mandaic,    Meetei_Mayek,    Meroitic_Cursive,
       Old_Persian,  Old_South_Arabian,  Old_Turkic, Ol_Chiki, Oriya, Osmanya,       Meroitic_Hieroglyphs,  Miao,  Mongolian,  Myanmar,  New_Tai_Lue,   Nko,
       Phags_Pa, Phoenician, Rejang, Runic,  Samaritan,  Saurashtra,  Shavian,       Ogham,    Old_Italic,   Old_Persian,   Old_South_Arabian,   Old_Turkic,
       Sinhala,  Sundanese,  Syloti_Nagri,  Syriac, Tagalog, Tagbanwa, Tai_Le,       Ol_Chiki, Oriya, Osmanya, Phags_Pa, Phoenician, Rejang, Runic,  Samari-
       Tai_Tham, Tai_Viet, Tamil, Telugu,  Thaana,  Thai,  Tibetan,  Tifinagh,       tan,  Saurashtra,  Sharada,  Shavian, Sinhala, Sora_Sompeng, Sundanese,
       Ugaritic, Vai, Yi.       Syloti_Nagri, Syriac, Tagalog, Tagbanwa,  Tai_Le,  Tai_Tham,  Tai_Viet,
        Takri,  Tamil,  Telugu, Thaana, Thai, Tibetan, Tifinagh, Ugaritic, Vai,
        Yi.
   
        Each character has exactly one Unicode general category property, spec-         Each character has exactly one Unicode general category property, spec-
       ified by a two-letter abbreviation. For compatibility with Perl,  nega-       ified  by a two-letter abbreviation. For compatibility with Perl, nega-
       tion  can  be  specified  by including a circumflex between the opening       tion can be specified by including a  circumflex  between  the  opening
       brace and the property name.  For  example,  \p{^Lu}  is  the  same  as       brace  and  the  property  name.  For  example,  \p{^Lu} is the same as
        \P{Lu}.         \P{Lu}.
   
        If only one letter is specified with \p or \P, it includes all the gen-         If only one letter is specified with \p or \P, it includes all the gen-
       eral category properties that start with that letter. In this case,  in       eral  category properties that start with that letter. In this case, in
       the  absence of negation, the curly brackets in the escape sequence are       the absence of negation, the curly brackets in the escape sequence  are
        optional; these two examples have the same effect:         optional; these two examples have the same effect:
   
          \p{L}           \p{L}
Line 3960  BACKSLASH Line 4478  BACKSLASH
          Zp    Paragraph separator           Zp    Paragraph separator
          Zs    Space separator           Zs    Space separator
   
       The special property L& is also supported: it matches a character  that       The  special property L& is also supported: it matches a character that
       has  the  Lu,  Ll, or Lt property, in other words, a letter that is not       has the Lu, Ll, or Lt property, in other words, a letter  that  is  not
        classified as a modifier or "other".         classified as a modifier or "other".
   
       The Cs (Surrogate) property applies only to  characters  in  the  range       The  Cs  (Surrogate)  property  applies only to characters in the range
       U+D800  to  U+DFFF. Such characters are not valid in UTF-8 strings (see       U+D800 to U+DFFF. Such characters are not valid in Unicode strings  and
       RFC 3629) and so cannot be tested by PCRE, unless UTF-8 validity check-       so  cannot  be  tested  by  PCRE, unless UTF validity checking has been
       ing  has  been  turned off (see the discussion of PCRE_NO_UTF8_CHECK in       turned   off   (see   the   discussion   of   PCRE_NO_UTF8_CHECK    and
       the pcreapi page). Perl does not support the Cs property.       PCRE_NO_UTF16_CHECK  in the pcreapi page). Perl does not support the Cs
        property.
   
        The long synonyms for  property  names  that  Perl  supports  (such  as         The long synonyms for  property  names  that  Perl  supports  (such  as
        \p{Letter})  are  not  supported by PCRE, nor is it permitted to prefix         \p{Letter})  are  not  supported by PCRE, nor is it permitted to prefix
Line 3990  BACKSLASH Line 4509  BACKSLASH
        by  zero  or  more  characters with the "mark" property, and treats the         by  zero  or  more  characters with the "mark" property, and treats the
        sequence as an atomic group (see below).  Characters  with  the  "mark"         sequence as an atomic group (see below).  Characters  with  the  "mark"
        property  are  typically  accents  that affect the preceding character.         property  are  typically  accents  that affect the preceding character.
       None of them have codepoints less than 256, so  in  non-UTF-8  mode  \X       None of them have codepoints less than 256, so in 8-bit non-UTF-8  mode
       matches any one character.       \X matches any one character.
   
        Note that recent versions of Perl have changed \X to match what Unicode         Note that recent versions of Perl have changed \X to match what Unicode
        calls an "extended grapheme cluster", which has a more complicated def-         calls an "extended grapheme cluster", which has a more complicated def-
Line 4001  BACKSLASH Line 4520  BACKSLASH
        to search a structure that contains  data  for  over  fifteen  thousand         to search a structure that contains  data  for  over  fifteen  thousand
        characters. That is why the traditional escape sequences such as \d and         characters. That is why the traditional escape sequences such as \d and
        \w do not use Unicode properties in PCRE by  default,  though  you  can         \w do not use Unicode properties in PCRE by  default,  though  you  can
       make them do so by setting the PCRE_UCP option for pcre_compile() or by       make  them do so by setting the PCRE_UCP option or by starting the pat-
       starting the pattern with (*UCP).       tern with (*UCP).
   
    PCRE's additional properties     PCRE's additional properties
   
Line 4019  BACKSLASH Line 4538  BACKSLASH
   
        Xan matches characters that have either the L (letter) or the  N  (num-         Xan matches characters that have either the L (letter) or the  N  (num-
        ber)  property. Xps matches the characters tab, linefeed, vertical tab,         ber)  property. Xps matches the characters tab, linefeed, vertical tab,
       formfeed, or carriage return, and any other character that  has  the  Z       form feed, or carriage return, and any other character that has  the  Z
        (separator) property.  Xsp is the same as Xps, except that vertical tab         (separator) property.  Xsp is the same as Xps, except that vertical tab
        is excluded. Xwd matches the same characters as Xan, plus underscore.         is excluded. Xwd matches the same characters as Xan, plus underscore.
   
Line 4071  BACKSLASH Line 4590  BACKSLASH
        A  word  boundary is a position in the subject string where the current         A  word  boundary is a position in the subject string where the current
        character and the previous character do not both match \w or  \W  (i.e.         character and the previous character do not both match \w or  \W  (i.e.
        one  matches  \w  and the other matches \W), or the start or end of the         one  matches  \w  and the other matches \W), or the start or end of the
       string if the first or last  character  matches  \w,  respectively.  In       string if the first or last character matches \w,  respectively.  In  a
       UTF-8  mode,  the  meanings  of \w and \W can be changed by setting the       UTF  mode,  the  meanings  of  \w  and \W can be changed by setting the
        PCRE_UCP option. When this is done, it also affects \b and \B.  Neither         PCRE_UCP option. When this is done, it also affects \b and \B.  Neither
        PCRE  nor  Perl has a separate "start of word" or "end of word" metase-         PCRE  nor  Perl has a separate "start of word" or "end of word" metase-
        quence. However, whatever follows \b normally determines which  it  is.         quence. However, whatever follows \b normally determines which  it  is.
Line 4163  FULL STOP (PERIOD, DOT) AND \N Line 4682  FULL STOP (PERIOD, DOT) AND \N
   
        Outside a character class, a dot in the pattern matches any one charac-         Outside a character class, a dot in the pattern matches any one charac-
        ter  in  the subject string except (by default) a character that signi-         ter  in  the subject string except (by default) a character that signi-
       fies the end of a line. In UTF-8 mode, the  matched  character  may  be       fies the end of a line.
       more than one byte long. 
   
       When  a line ending is defined as a single character, dot never matches       When a line ending is defined as a single character, dot never  matches
       that character; when the two-character sequence CRLF is used, dot  does       that  character; when the two-character sequence CRLF is used, dot does
       not  match  CR  if  it  is immediately followed by LF, but otherwise it       not match CR if it is immediately followed  by  LF,  but  otherwise  it
       matches all characters (including isolated CRs and LFs). When any  Uni-       matches  all characters (including isolated CRs and LFs). When any Uni-
       code  line endings are being recognized, dot does not match CR or LF or       code line endings are being recognized, dot does not match CR or LF  or
        any of the other line ending characters.         any of the other line ending characters.
   
       The behaviour of dot with regard to newlines can  be  changed.  If  the       The  behaviour  of  dot  with regard to newlines can be changed. If the
       PCRE_DOTALL  option  is  set,  a dot matches any one character, without       PCRE_DOTALL option is set, a dot matches  any  one  character,  without
        exception. If the two-character sequence CRLF is present in the subject         exception. If the two-character sequence CRLF is present in the subject
        string, it takes two dots to match it.         string, it takes two dots to match it.
   
       The  handling of dot is entirely independent of the handling of circum-       The handling of dot is entirely independent of the handling of  circum-
       flex and dollar, the only relationship being  that  they  both  involve       flex  and  dollar,  the  only relationship being that they both involve
        newlines. Dot has no special meaning in a character class.         newlines. Dot has no special meaning in a character class.
   
       The  escape  sequence  \N  behaves  like  a  dot, except that it is not       The escape sequence \N behaves like  a  dot,  except  that  it  is  not
       affected by the PCRE_DOTALL option. In  other  words,  it  matches  any       affected  by  the  PCRE_DOTALL  option.  In other words, it matches any
       character  except  one that signifies the end of a line. Perl also uses       character except one that signifies the end of a line. Perl  also  uses
        \N to match characters by name; PCRE does not support this.         \N to match characters by name; PCRE does not support this.
   
   
MATCHING A SINGLE BYTEMATCHING A SINGLE DATA UNIT
   
       Outside a character class, the escape sequence \C matches any one byte,       Outside  a character class, the escape sequence \C matches any one data
       both  in  and  out of UTF-8 mode. Unlike a dot, it always matches line-       unit, whether or not a UTF mode is set. In the 8-bit library, one  data
       ending characters. The feature is provided in Perl in  order  to  match       unit  is  one byte; in the 16-bit library it is a 16-bit unit. Unlike a
       individual  bytes  in UTF-8 mode, but it is unclear how it can usefully       dot, \C always matches line-ending characters. The feature is  provided
       be used. Because \C breaks up characters into individual bytes,  match-       in  Perl  in  order  to match individual bytes in UTF-8 mode, but it is
       ing  one  byte  with \C in UTF-8 mode means that the rest of the string       unclear how it can usefully be used. Because \C  breaks  up  characters
       may start with a malformed UTF-8 character. This has undefined results,       into  individual  data  units,  matching one unit with \C in a UTF mode
       because  PCRE  assumes that it is dealing with valid UTF-8 strings (and       means that the rest of the string may start with a malformed UTF  char-
       by default it checks  this  at  the  start  of  processing  unless  the       acter.  This  has  undefined  results,  because PCRE assumes that it is
       PCRE_NO_UTF8_CHECK option is used).       dealing with valid UTF strings (and by default it checks  this  at  the
        start     of    processing    unless    the    PCRE_NO_UTF8_CHECK    or
        PCRE_NO_UTF16_CHECK option is used).
   
       PCRE  does  not  allow \C to appear in lookbehind assertions (described       PCRE does not allow \C to appear in  lookbehind  assertions  (described
       below) in UTF-8 mode, because this would make it impossible  to  calcu-       below)  in  a UTF mode, because this would make it impossible to calcu-
        late the length of the lookbehind.         late the length of the lookbehind.
   
       In  general, the \C escape sequence is best avoided in UTF-8 mode. How-       In general, the \C escape sequence is best avoided. However, one way of
       ever, one way of using it that avoids the problem  of  malformed  UTF-8       using  it that avoids the problem of malformed UTF characters is to use
       characters  is to use a lookahead to check the length of the next char-       a lookahead to check the length of the next character, as in this  pat-
       acter, as in this pattern (ignore white space and line breaks):       tern,  which  could be used with a UTF-8 string (ignore white space and
        line breaks):
   
          (?| (?=[\x00-\x7f])(\C) |           (?| (?=[\x00-\x7f])(\C) |
              (?=[\x80-\x{7ff}])(\C)(\C) |               (?=[\x80-\x{7ff}])(\C)(\C) |
Line 4233  SQUARE BRACKETS AND CHARACTER CLASSES Line 4754  SQUARE BRACKETS AND CHARACTER CLASSES
        first data character in the class  (after  an  initial  circumflex,  if         first data character in the class  (after  an  initial  circumflex,  if
        present) or escaped with a backslash.         present) or escaped with a backslash.
   
       A  character  class matches a single character in the subject. In UTF-8       A  character  class matches a single character in the subject. In a UTF
       mode, the character may be more than one byte long. A matched character       mode, the character may be more than one  data  unit  long.  A  matched
       must be in the set of characters defined by the class, unless the first       character must be in the set of characters defined by the class, unless
       character in the class definition is a circumflex, in  which  case  the       the first character in the class definition is a circumflex,  in  which
       subject  character  must  not  be in the set defined by the class. If a       case the subject character must not be in the set defined by the class.
       circumflex is actually required as a member of the class, ensure it  is       If a circumflex is actually required as a member of the  class,  ensure
       not the first character, or escape it with a backslash.       it is not the first character, or escape it with a backslash.
   
        For  example, the character class [aeiou] matches any lower case vowel,         For  example, the character class [aeiou] matches any lower case vowel,
        while [^aeiou] matches any character that is not a  lower  case  vowel.         while [^aeiou] matches any character that is not a  lower  case  vowel.
Line 4249  SQUARE BRACKETS AND CHARACTER CLASSES Line 4770  SQUARE BRACKETS AND CHARACTER CLASSES
        sumes a character from the subject string, and therefore  it  fails  if         sumes a character from the subject string, and therefore  it  fails  if
        the current pointer is at the end of the string.         the current pointer is at the end of the string.
   
       In  UTF-8 mode, characters with values greater than 255 can be included       In  UTF-8  (UTF-16)  mode,  characters  with  values  greater  than 255
       in a class as a literal string of bytes, or by using the  \x{  escaping       (0xffff) can be included in a class as a literal string of data  units,
       mechanism.       or by using the \x{ escaping mechanism.
   
        When  caseless  matching  is set, any letters in a class represent both         When  caseless  matching  is set, any letters in a class represent both
        their upper case and lower case versions, so for  example,  a  caseless         their upper case and lower case versions, so for  example,  a  caseless
        [aeiou]  matches  "A"  as well as "a", and a caseless [^aeiou] does not         [aeiou]  matches  "A"  as well as "a", and a caseless [^aeiou] does not
       match "A", whereas a caseful version would. In UTF-8 mode, PCRE  always       match "A", whereas a caseful version would. In a UTF mode, PCRE  always
        understands  the  concept  of case for characters whose values are less         understands  the  concept  of case for characters whose values are less
        than 128, so caseless matching is always possible. For characters  with         than 128, so caseless matching is always possible. For characters  with
        higher  values,  the  concept  of case is supported if PCRE is compiled         higher  values,  the  concept  of case is supported if PCRE is compiled
        with Unicode property support, but not otherwise.  If you want  to  use         with Unicode property support, but not otherwise.  If you want  to  use
       caseless  matching  in UTF8-mode for characters 128 and above, you must       caseless  matching in a UTF mode for characters 128 and above, you must
        ensure that PCRE is compiled with Unicode property support as  well  as         ensure that PCRE is compiled with Unicode property support as  well  as
       with UTF-8 support.       with UTF support.
   
        Characters  that  might  indicate  line breaks are never treated in any         Characters  that  might  indicate  line breaks are never treated in any
        special way  when  matching  character  classes,  whatever  line-ending         special way  when  matching  character  classes,  whatever  line-ending
Line 4289  SQUARE BRACKETS AND CHARACTER CLASSES Line 4810  SQUARE BRACKETS AND CHARACTER CLASSES
   
        Ranges  operate in the collating sequence of character values. They can         Ranges  operate in the collating sequence of character values. They can
        also  be  used  for  characters  specified  numerically,  for   example         also  be  used  for  characters  specified  numerically,  for   example
       [\000-\037].  In UTF-8 mode, ranges can include characters whose values       [\000-\037].  Ranges  can include any characters that are valid for the
       are greater than 255, for example [\x{100}-\x{2ff}].       current mode.
   
        If a range that includes letters is used when caseless matching is set,         If a range that includes letters is used when caseless matching is set,
        it matches the letters in either case. For example, [W-c] is equivalent         it matches the letters in either case. For example, [W-c] is equivalent
       to [][\\^_`wxyzabc], matched caselessly,  and  in  non-UTF-8  mode,  if       to [][\\^_`wxyzabc], matched caselessly, and  in  a  non-UTF  mode,  if
        character  tables  for  a French locale are in use, [\xc8-\xcb] matches         character  tables  for  a French locale are in use, [\xc8-\xcb] matches
       accented E characters in both cases. In UTF-8 mode, PCRE  supports  the       accented E characters in both cases. In UTF modes,  PCRE  supports  the
        concept  of  case for characters with values greater than 128 only when         concept  of  case for characters with values greater than 128 only when
        it is compiled with Unicode property support.         it is compiled with Unicode property support.
   
        The character escape sequences \d, \D, \h, \H, \p, \P, \s, \S, \v,  \V,         The character escape sequences \d, \D, \h, \H, \p, \P, \s, \S, \v,  \V,
        \w, and \W may appear in a character class, and add the characters that         \w, and \W may appear in a character class, and add the characters that
        they match to the class. For example, [\dABCDEF] matches any  hexadeci-         they match to the class. For example, [\dABCDEF] matches any  hexadeci-
       mal  digit.  In UTF-8 mode, the PCRE_UCP option affects the meanings of       mal  digit.  In  UTF modes, the PCRE_UCP option affects the meanings of
        \d, \s, \w and their upper case partners, just as  it  does  when  they         \d, \s, \w and their upper case partners, just as  it  does  when  they
        appear  outside a character class, as described in the section entitled         appear  outside a character class, as described in the section entitled
        "Generic character types" above. The escape sequence \b has a different         "Generic character types" above. The escape sequence \b has a different
Line 4369  POSIX CHARACTER CLASSES Line 4890  POSIX CHARACTER CLASSES
        POSIX syntax [.ch.] and [=ch=] where "ch" is a "collating element", but         POSIX syntax [.ch.] and [=ch=] where "ch" is a "collating element", but
        these are not supported, and an error is given if they are encountered.         these are not supported, and an error is given if they are encountered.
   
       By  default,  in UTF-8 mode, characters with values greater than 128 do       By  default,  in  UTF modes, characters with values greater than 128 do
        not match any of the POSIX character classes. However, if the  PCRE_UCP         not match any of the POSIX character classes. However, if the  PCRE_UCP
        option  is passed to pcre_compile(), some of the classes are changed so         option  is passed to pcre_compile(), some of the classes are changed so
        that Unicode character properties are used. This is achieved by replac-         that Unicode character properties are used. This is achieved by replac-
Line 4453  INTERNAL OPTION SETTING Line 4974  INTERNAL OPTION SETTING
        some very weird behaviour otherwise.         some very weird behaviour otherwise.
   
        Note: There are other PCRE-specific options that  can  be  set  by  the         Note: There are other PCRE-specific options that  can  be  set  by  the
       application  when  the  compile  or match functions are called. In some       application  when  the  compiling  or matching functions are called. In
       cases the pattern can contain special leading sequences such as (*CRLF)       some cases the pattern can contain special leading  sequences  such  as
       to  override  what  the application has set or what has been defaulted.       (*CRLF)  to  override  what  the  application  has set or what has been
       Details are given in the section entitled  "Newline  sequences"  above.       defaulted.  Details  are  given  in  the  section   entitled   "Newline
       There  are  also  the  (*UTF8) and (*UCP) leading sequences that can be       sequences"  above.  There  are  also  the (*UTF8), (*UTF16), and (*UCP)
       used to set UTF-8 and Unicode property modes; they  are  equivalent  to       leading sequences that can be used to  set  UTF  and  Unicode  property
       setting the PCRE_UTF8 and the PCRE_UCP options, respectively.       modes;  they  are  equivalent to setting the PCRE_UTF8, PCRE_UTF16, and
        the PCRE_UCP options, respectively.
   
   
 SUBPATTERNS  SUBPATTERNS
Line 4471  SUBPATTERNS Line 4993  SUBPATTERNS
   
          cat(aract|erpillar|)           cat(aract|erpillar|)
   
       matches "cataract", "caterpillar", or "cat". Without  the  parentheses,       matches  "cataract",  "caterpillar", or "cat". Without the parentheses,
        it would match "cataract", "erpillar" or an empty string.         it would match "cataract", "erpillar" or an empty string.
   
       2.  It  sets  up  the  subpattern as a capturing subpattern. This means       2. It sets up the subpattern as  a  capturing  subpattern.  This  means
       that, when the whole pattern  matches,  that  portion  of  the  subject       that,  when  the  whole  pattern  matches,  that portion of the subject
        string that matched the subpattern is passed back to the caller via the         string that matched the subpattern is passed back to the caller via the
       ovector argument of pcre_exec(). Opening parentheses are  counted  from       ovector  argument  of  the matching function. (This applies only to the
       left  to  right  (starting  from 1) to obtain numbers for the capturing       traditional matching functions; the DFA matching functions do not  sup-
       subpatterns. For example, if the  string  "the  red  king"  is  matched       port capturing.)
       against the pattern 
   
          Opening parentheses are counted from left to right (starting from 1) to
          obtain numbers for the  capturing  subpatterns.  For  example,  if  the
          string "the red king" is matched against the pattern
   
          the ((red|white) (king|queen))           the ((red|white) (king|queen))
   
        the captured substrings are "red king", "red", and "king", and are num-         the captured substrings are "red king", "red", and "king", and are num-
Line 4636  REPETITION Line 5161  REPETITION
          a literal data character           a literal data character
          the dot metacharacter           the dot metacharacter
          the \C escape sequence           the \C escape sequence
         the \X escape sequence (in UTF-8 mode with Unicode properties)         the \X escape sequence
          the \R escape sequence           the \R escape sequence
          an escape such as \d or \pL that matches a single character           an escape such as \d or \pL that matches a single character
          a character class           a character class
Line 4668  REPETITION Line 5193  REPETITION
        the  syntax of a quantifier, is taken as a literal character. For exam-         the  syntax of a quantifier, is taken as a literal character. For exam-
        ple, {,6} is not a quantifier, but a literal string of four characters.         ple, {,6} is not a quantifier, but a literal string of four characters.
   
       In UTF-8 mode, quantifiers apply to UTF-8  characters  rather  than  to       In UTF modes, quantifiers apply to characters rather than to individual
       individual bytes. Thus, for example, \x{100}{2} matches two UTF-8 char-       data  units. Thus, for example, \x{100}{2} matches two characters, each
       acters, each of which is represented by a two-byte sequence. Similarly,       of which is represented by a two-byte sequence in a UTF-8 string. Simi-
       when Unicode property support is available, \X{3} matches three Unicode       larly,  \X{3}  matches  three Unicode extended sequences, each of which
       extended sequences, each of which may be several bytes long  (and  they       may be several data units long (and they may be of different lengths).
       may be of different lengths). 
   
        The quantifier {0} is permitted, causing the expression to behave as if         The quantifier {0} is permitted, causing the expression to behave as if
        the previous item and the quantifier were not present. This may be use-         the previous item and the quantifier were not present. This may be use-
       ful  for  subpatterns that are referenced as subroutines from elsewhere       ful for subpatterns that are referenced as subroutines  from  elsewhere
        in the pattern (but see also the section entitled "Defining subpatterns         in the pattern (but see also the section entitled "Defining subpatterns
       for  use  by  reference only" below). Items other than subpatterns that       for use by reference only" below). Items other  than  subpatterns  that
        have a {0} quantifier are omitted from the compiled pattern.         have a {0} quantifier are omitted from the compiled pattern.
   
       For convenience, the three most common quantifiers have  single-charac-       For  convenience, the three most common quantifiers have single-charac-
        ter abbreviations:         ter abbreviations:
   
          *    is equivalent to {0,}           *    is equivalent to {0,}
          +    is equivalent to {1,}           +    is equivalent to {1,}
          ?    is equivalent to {0,1}           ?    is equivalent to {0,1}
   
       It  is  possible  to construct infinite loops by following a subpattern       It is possible to construct infinite loops by  following  a  subpattern
        that can match no characters with a quantifier that has no upper limit,         that can match no characters with a quantifier that has no upper limit,
        for example:         for example:
   
          (a?)*           (a?)*
   
        Earlier versions of Perl and PCRE used to give an error at compile time         Earlier versions of Perl and PCRE used to give an error at compile time
       for such patterns. However, because there are cases where this  can  be       for  such  patterns. However, because there are cases where this can be
       useful,  such  patterns  are now accepted, but if any repetition of the       useful, such patterns are now accepted, but if any  repetition  of  the
       subpattern does in fact match no characters, the loop is forcibly  bro-       subpattern  does in fact match no characters, the loop is forcibly bro-
        ken.         ken.
   
       By  default,  the quantifiers are "greedy", that is, they match as much       By default, the quantifiers are "greedy", that is, they match  as  much
       as possible (up to the maximum  number  of  permitted  times),  without       as  possible  (up  to  the  maximum number of permitted times), without
       causing  the  rest of the pattern to fail. The classic example of where       causing the rest of the pattern to fail. The classic example  of  where
        this gives problems is in trying to match comments in C programs. These         this gives problems is in trying to match comments in C programs. These
       appear  between  /*  and  */ and within the comment, individual * and /       appear between /* and */ and within the comment,  individual  *  and  /
       characters may appear. An attempt to match C comments by  applying  the       characters  may  appear. An attempt to match C comments by applying the
        pattern         pattern
   
          /\*.*\*/           /\*.*\*/
Line 4715  REPETITION Line 5239  REPETITION
   
          /* first comment */  not comment  /* second comment */           /* first comment */  not comment  /* second comment */
   
       fails,  because it matches the entire string owing to the greediness of       fails, because it matches the entire string owing to the greediness  of
        the .*  item.         the .*  item.
   
       However, if a quantifier is followed by a question mark, it  ceases  to       However,  if  a quantifier is followed by a question mark, it ceases to
        be greedy, and instead matches the minimum number of times possible, so         be greedy, and instead matches the minimum number of times possible, so
        the pattern         the pattern
   
          /\*.*?\*/           /\*.*?\*/
   
       does the right thing with the C comments. The meaning  of  the  various       does  the  right  thing with the C comments. The meaning of the various
       quantifiers  is  not  otherwise  changed,  just the preferred number of       quantifiers is not otherwise changed,  just  the  preferred  number  of
       matches.  Do not confuse this use of question mark with its  use  as  a       matches.   Do  not  confuse this use of question mark with its use as a
       quantifier  in its own right. Because it has two uses, it can sometimes       quantifier in its own right. Because it has two uses, it can  sometimes
        appear doubled, as in         appear doubled, as in
   
          \d??\d           \d??\d
Line 4735  REPETITION Line 5259  REPETITION
        which matches one digit by preference, but can match two if that is the         which matches one digit by preference, but can match two if that is the
        only way the rest of the pattern matches.         only way the rest of the pattern matches.
   
       If  the PCRE_UNGREEDY option is set (an option that is not available in       If the PCRE_UNGREEDY option is set (an option that is not available  in
       Perl), the quantifiers are not greedy by default, but  individual  ones       Perl),  the  quantifiers are not greedy by default, but individual ones
       can  be  made  greedy  by following them with a question mark. In other       can be made greedy by following them with a  question  mark.  In  other
        words, it inverts the default behaviour.         words, it inverts the default behaviour.
   
       When a parenthesized subpattern is quantified  with  a  minimum  repeat       When  a  parenthesized  subpattern  is quantified with a minimum repeat
       count  that is greater than 1 or with a limited maximum, more memory is       count that is greater than 1 or with a limited maximum, more memory  is
       required for the compiled pattern, in proportion to  the  size  of  the       required  for  the  compiled  pattern, in proportion to the size of the
        minimum or maximum.         minimum or maximum.
   
        If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equiv-         If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equiv-
       alent to Perl's /s) is set, thus allowing the dot  to  match  newlines,       alent  to  Perl's  /s) is set, thus allowing the dot to match newlines,
       the  pattern  is  implicitly anchored, because whatever follows will be       the pattern is implicitly anchored, because whatever  follows  will  be
       tried against every character position in the subject string, so  there       tried  against every character position in the subject string, so there
       is  no  point  in  retrying the overall match at any position after the       is no point in retrying the overall match at  any  position  after  the
       first. PCRE normally treats such a pattern as though it  were  preceded       first.  PCRE  normally treats such a pattern as though it were preceded
        by \A.         by \A.
   
       In  cases  where  it  is known that the subject string contains no new-       In cases where it is known that the subject  string  contains  no  new-
       lines, it is worth setting PCRE_DOTALL in order to  obtain  this  opti-       lines,  it  is  worth setting PCRE_DOTALL in order to obtain this opti-
        mization, or alternatively using ^ to indicate anchoring explicitly.         mization, or alternatively using ^ to indicate anchoring explicitly.
   
       However,  there is one situation where the optimization cannot be used.       However, there is one situation where the optimization cannot be  used.
        When .*  is inside capturing parentheses that are the subject of a back         When .*  is inside capturing parentheses that are the subject of a back
        reference elsewhere in the pattern, a match at the start may fail where         reference elsewhere in the pattern, a match at the start may fail where
        a later one succeeds. Consider, for example:         a later one succeeds. Consider, for example:
   
          (.*)abc\1           (.*)abc\1
   
       If the subject is "xyz123abc123" the match point is the fourth  charac-       If  the subject is "xyz123abc123" the match point is the fourth charac-
        ter. For this reason, such a pattern is not implicitly anchored.         ter. For this reason, such a pattern is not implicitly anchored.
   
        When a capturing subpattern is repeated, the value captured is the sub-         When a capturing subpattern is repeated, the value captured is the sub-
Line 4773  REPETITION Line 5297  REPETITION
          (tweedle[dume]{3}\s*)+           (tweedle[dume]{3}\s*)+
   
        has matched "tweedledum tweedledee" the value of the captured substring         has matched "tweedledum tweedledee" the value of the captured substring
       is  "tweedledee".  However,  if there are nested capturing subpatterns,       is "tweedledee". However, if there are  nested  capturing  subpatterns,
       the corresponding captured values may have been set in previous  itera-       the  corresponding captured values may have been set in previous itera-
        tions. For example, after         tions. For example, after
   
          /(a|(b))+/           /(a|(b))+/
Line 4784  REPETITION Line 5308  REPETITION
   
 ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS  ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS
   
       With  both  maximizing ("greedy") and minimizing ("ungreedy" or "lazy")       With both maximizing ("greedy") and minimizing ("ungreedy"  or  "lazy")
       repetition, failure of what follows normally causes the  repeated  item       repetition,  failure  of what follows normally causes the repeated item
       to  be  re-evaluated to see if a different number of repeats allows the       to be re-evaluated to see if a different number of repeats  allows  the
       rest of the pattern to match. Sometimes it is useful to  prevent  this,       rest  of  the pattern to match. Sometimes it is useful to prevent this,
       either  to  change the nature of the match, or to cause it fail earlier       either to change the nature of the match, or to cause it  fail  earlier
       than it otherwise might, when the author of the pattern knows there  is       than  it otherwise might, when the author of the pattern knows there is
        no point in carrying on.         no point in carrying on.
   
       Consider,  for  example, the pattern \d+foo when applied to the subject       Consider, for example, the pattern \d+foo when applied to  the  subject
        line         line
   
          123456bar           123456bar
   
        After matching all 6 digits and then failing to match "foo", the normal         After matching all 6 digits and then failing to match "foo", the normal
       action  of  the matcher is to try again with only 5 digits matching the       action of the matcher is to try again with only 5 digits  matching  the
       \d+ item, and then with  4,  and  so  on,  before  ultimately  failing.       \d+  item,  and  then  with  4,  and  so on, before ultimately failing.
       "Atomic  grouping"  (a  term taken from Jeffrey Friedl's book) provides       "Atomic grouping" (a term taken from Jeffrey  Friedl's  book)  provides
       the means for specifying that once a subpattern has matched, it is  not       the  means for specifying that once a subpattern has matched, it is not
        to be re-evaluated in this way.         to be re-evaluated in this way.
   
       If  we  use atomic grouping for the previous example, the matcher gives       If we use atomic grouping for the previous example, the  matcher  gives
       up immediately on failing to match "foo" the first time.  The  notation       up  immediately  on failing to match "foo" the first time. The notation
        is a kind of special parenthesis, starting with (?> as in this example:         is a kind of special parenthesis, starting with (?> as in this example:
   
          (?>\d+)foo           (?>\d+)foo
   
       This  kind  of  parenthesis "locks up" the  part of the pattern it con-       This kind of parenthesis "locks up" the  part of the  pattern  it  con-
       tains once it has matched, and a failure further into  the  pattern  is       tains  once  it  has matched, and a failure further into the pattern is
       prevented  from  backtracking into it. Backtracking past it to previous       prevented from backtracking into it. Backtracking past it  to  previous
        items, however, works as normal.         items, however, works as normal.
   
       An alternative description is that a subpattern of  this  type  matches       An  alternative  description  is that a subpattern of this type matches
       the  string  of  characters  that an identical standalone pattern would       the string of characters that an  identical  standalone  pattern  would
        match, if anchored at the current point in the subject string.         match, if anchored at the current point in the subject string.
   
        Atomic grouping subpatterns are not capturing subpatterns. Simple cases         Atomic grouping subpatterns are not capturing subpatterns. Simple cases
        such as the above example can be thought of as a maximizing repeat that         such as the above example can be thought of as a maximizing repeat that
       must swallow everything it can. So, while both \d+ and  \d+?  are  pre-       must  swallow  everything  it can. So, while both \d+ and \d+? are pre-
       pared  to  adjust  the number of digits they match in order to make the       pared to adjust the number of digits they match in order  to  make  the
        rest of the pattern match, (?>\d+) can only match an entire sequence of         rest of the pattern match, (?>\d+) can only match an entire sequence of
        digits.         digits.
   
       Atomic  groups in general can of course contain arbitrarily complicated       Atomic groups in general can of course contain arbitrarily  complicated
       subpatterns, and can be nested. However, when  the  subpattern  for  an       subpatterns,  and  can  be  nested. However, when the subpattern for an
        atomic group is just a single repeated item, as in the example above, a         atomic group is just a single repeated item, as in the example above, a
       simpler notation, called a "possessive quantifier" can  be  used.  This       simpler  notation,  called  a "possessive quantifier" can be used. This
       consists  of  an  additional  + character following a quantifier. Using       consists of an additional + character  following  a  quantifier.  Using
        this notation, the previous example can be rewritten as         this notation, the previous example can be rewritten as
   
          \d++foo           \d++foo
Line 4840  ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS Line 5364  ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS
   
          (abc|xyz){2,3}+           (abc|xyz){2,3}+
   
       Possessive   quantifiers   are   always  greedy;  the  setting  of  the       Possessive  quantifiers  are  always  greedy;  the   setting   of   the
        PCRE_UNGREEDY option is ignored. They are a convenient notation for the         PCRE_UNGREEDY option is ignored. They are a convenient notation for the
       simpler  forms  of atomic group. However, there is no difference in the       simpler forms of atomic group. However, there is no difference  in  the
       meaning of a possessive quantifier and  the  equivalent  atomic  group,       meaning  of  a  possessive  quantifier and the equivalent atomic group,
       though  there  may  be a performance difference; possessive quantifiers       though there may be a performance  difference;  possessive  quantifiers
        should be slightly faster.         should be slightly faster.
   
       The possessive quantifier syntax is an extension to the Perl  5.8  syn-       The  possessive  quantifier syntax is an extension to the Perl 5.8 syn-
       tax.   Jeffrey  Friedl  originated the idea (and the name) in the first       tax.  Jeffrey Friedl originated the idea (and the name)  in  the  first
        edition of his book. Mike McCloskey liked it, so implemented it when he         edition of his book. Mike McCloskey liked it, so implemented it when he
       built  Sun's Java package, and PCRE copied it from there. It ultimately       built Sun's Java package, and PCRE copied it from there. It  ultimately
        found its way into Perl at release 5.10.         found its way into Perl at release 5.10.
   
        PCRE has an optimization that automatically "possessifies" certain sim-         PCRE has an optimization that automatically "possessifies" certain sim-
       ple  pattern  constructs.  For  example, the sequence A+B is treated as       ple pattern constructs. For example, the sequence  A+B  is  treated  as
       A++B because there is no point in backtracking into a sequence  of  A's       A++B  because  there is no point in backtracking into a sequence of A's
        when B must follow.         when B must follow.
   
       When  a  pattern  contains an unlimited repeat inside a subpattern that       When a pattern contains an unlimited repeat inside  a  subpattern  that
       can itself be repeated an unlimited number of  times,  the  use  of  an       can  itself  be  repeated  an  unlimited number of times, the use of an
       atomic  group  is  the  only way to avoid some failing matches taking a       atomic group is the only way to avoid some  failing  matches  taking  a
        very long time indeed. The pattern         very long time indeed. The pattern
   
          (\D+|<\d+>)*[!?]           (\D+|<\d+>)*[!?]
   
       matches an unlimited number of substrings that either consist  of  non-       matches  an  unlimited number of substrings that either consist of non-
       digits,  or  digits  enclosed in <>, followed by either ! or ?. When it       digits, or digits enclosed in <>, followed by either ! or  ?.  When  it
        matches, it runs quickly. However, if it is applied to         matches, it runs quickly. However, if it is applied to
   
          aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa           aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
   
       it takes a long time before reporting  failure.  This  is  because  the       it  takes  a  long  time  before reporting failure. This is because the
       string  can be divided between the internal \D+ repeat and the external       string can be divided between the internal \D+ repeat and the  external
       * repeat in a large number of ways, and all  have  to  be  tried.  (The       *  repeat  in  a  large  number of ways, and all have to be tried. (The
       example  uses  [!?]  rather than a single character at the end, because       example uses [!?] rather than a single character at  the  end,  because
       both PCRE and Perl have an optimization that allows  for  fast  failure       both  PCRE  and  Perl have an optimization that allows for fast failure
       when  a single character is used. They remember the last single charac-       when a single character is used. They remember the last single  charac-
       ter that is required for a match, and fail early if it is  not  present       ter  that  is required for a match, and fail early if it is not present
       in  the  string.)  If  the pattern is changed so that it uses an atomic       in the string.) If the pattern is changed so that  it  uses  an  atomic
        group, like this:         group, like this:
   
          ((?>\D+)|<\d+>)*[!?]           ((?>\D+)|<\d+>)*[!?]
Line 4890  BACK REFERENCES Line 5414  BACK REFERENCES
   
        Outside a character class, a backslash followed by a digit greater than         Outside a character class, a backslash followed by a digit greater than
        0 (and possibly further digits) is a back reference to a capturing sub-         0 (and possibly further digits) is a back reference to a capturing sub-
       pattern earlier (that is, to its left) in the pattern,  provided  there       pattern  earlier  (that is, to its left) in the pattern, provided there
        have been that many previous capturing left parentheses.         have been that many previous capturing left parentheses.
   
        However, if the decimal number following the backslash is less than 10,         However, if the decimal number following the backslash is less than 10,
       it is always taken as a back reference, and causes  an  error  only  if       it  is  always  taken  as a back reference, and causes an error only if
       there  are  not that many capturing left parentheses in the entire pat-       there are not that many capturing left parentheses in the  entire  pat-
       tern. In other words, the parentheses that are referenced need  not  be       tern.  In  other words, the parentheses that are referenced need not be
       to  the left of the reference for numbers less than 10. A "forward back       to the left of the reference for numbers less than 10. A "forward  back
       reference" of this type can make sense when a  repetition  is  involved       reference"  of  this  type can make sense when a repetition is involved
       and  the  subpattern to the right has participated in an earlier itera-       and the subpattern to the right has participated in an  earlier  itera-
        tion.         tion.
   
       It is not possible to have a numerical "forward back  reference"  to  a       It  is  not  possible to have a numerical "forward back reference" to a
       subpattern  whose  number  is  10  or  more using this syntax because a       subpattern whose number is 10 or  more  using  this  syntax  because  a
       sequence such as \50 is interpreted as a character  defined  in  octal.       sequence  such  as  \50 is interpreted as a character defined in octal.
        See the subsection entitled "Non-printing characters" above for further         See the subsection entitled "Non-printing characters" above for further
       details of the handling of digits following a backslash.  There  is  no       details  of  the  handling of digits following a backslash. There is no
       such  problem  when named parentheses are used. A back reference to any       such problem when named parentheses are used. A back reference  to  any
        subpattern is possible using named parentheses (see below).         subpattern is possible using named parentheses (see below).
   
       Another way of avoiding the ambiguity inherent in  the  use  of  digits       Another  way  of  avoiding  the ambiguity inherent in the use of digits
       following  a  backslash  is  to use the \g escape sequence. This escape       following a backslash is to use the \g  escape  sequence.  This  escape
        must be followed by an unsigned number or a negative number, optionally         must be followed by an unsigned number or a negative number, optionally
        enclosed in braces. These examples are all identical:         enclosed in braces. These examples are all identical:
   
Line 4919  BACK REFERENCES Line 5443  BACK REFERENCES
          (ring), \g1           (ring), \g1
          (ring), \g{1}           (ring), \g{1}
   
       An  unsigned number specifies an absolute reference without the ambigu-       An unsigned number specifies an absolute reference without the  ambigu-
        ity that is present in the older syntax. It is also useful when literal         ity that is present in the older syntax. It is also useful when literal
        digits follow the reference. A negative number is a relative reference.         digits follow the reference. A negative number is a relative reference.
        Consider this example:         Consider this example:
Line 4928  BACK REFERENCES Line 5452  BACK REFERENCES
   
        The sequence \g{-1} is a reference to the most recently started captur-         The sequence \g{-1} is a reference to the most recently started captur-
        ing subpattern before \g, that is, is it equivalent to \2 in this exam-         ing subpattern before \g, that is, is it equivalent to \2 in this exam-
       ple.  Similarly, \g{-2} would be equivalent to \1. The use of  relative       ple.   Similarly, \g{-2} would be equivalent to \1. The use of relative
       references  can  be helpful in long patterns, and also in patterns that       references can be helpful in long patterns, and also in  patterns  that
       are created by  joining  together  fragments  that  contain  references       are  created  by  joining  together  fragments  that contain references
        within themselves.         within themselves.
   
       A  back  reference matches whatever actually matched the capturing sub-       A back reference matches whatever actually matched the  capturing  sub-
       pattern in the current subject string, rather  than  anything  matching       pattern  in  the  current subject string, rather than anything matching
        the subpattern itself (see "Subpatterns as subroutines" below for a way         the subpattern itself (see "Subpatterns as subroutines" below for a way
        of doing that). So the pattern         of doing that). So the pattern
   
          (sens|respons)e and \1ibility           (sens|respons)e and \1ibility
   
       matches "sense and sensibility" and "response and responsibility",  but       matches  "sense and sensibility" and "response and responsibility", but
       not  "sense and responsibility". If caseful matching is in force at the       not "sense and responsibility". If caseful matching is in force at  the
       time of the back reference, the case of letters is relevant. For  exam-       time  of the back reference, the case of letters is relevant. For exam-
        ple,         ple,
   
          ((?i)rah)\s+\1           ((?i)rah)\s+\1
   
       matches  "rah  rah"  and  "RAH RAH", but not "RAH rah", even though the       matches "rah rah" and "RAH RAH", but not "RAH  rah",  even  though  the
        original capturing subpattern is matched caselessly.         original capturing subpattern is matched caselessly.
   
       There are several different ways of writing back  references  to  named       There  are  several  different ways of writing back references to named
       subpatterns.  The  .NET syntax \k{name} and the Perl syntax \k<name> or       subpatterns. The .NET syntax \k{name} and the Perl syntax  \k<name>  or
       \k'name' are supported, as is the Python syntax (?P=name). Perl  5.10's       \k'name'  are supported, as is the Python syntax (?P=name). Perl 5.10's
        unified back reference syntax, in which \g can be used for both numeric         unified back reference syntax, in which \g can be used for both numeric
       and named references, is also supported. We  could  rewrite  the  above       and  named  references,  is  also supported       and  named  references,  is  also supported. We could rewrite the above
        example in any of the following ways:         example in any of the following ways:
   
          (?<p1>(?i)rah)\s+\k<p1>           (?<p1>(?i)rah)\s+\k<p1>
Line 4962  BACK REFERENCES Line 5486  BACK REFERENCES
          (?P<p1>(?i)rah)\s+(?P=p1)           (?P<p1>(?i)rah)\s+(?P=p1)
          (?<p1>(?i)rah)\s+\g{p1}           (?<p1>(?i)rah)\s+\g{p1}
   
       A  subpattern  that  is  referenced  by  name may appear in the pattern       A subpattern that is referenced by  name  may  appear  in  the  pattern
        before or after the reference.         before or after the reference.
   
       There may be more than one back reference to the same subpattern. If  a       There  may be more than one back reference to the same subpattern. If a
       subpattern  has  not actually been used in a particular match, any back       subpattern has not actually been used in a particular match,  any  back
        references to it always fail by default. For example, the pattern         references to it always fail by default. For example, the pattern
   
          (a|(bc))\2           (a|(bc))\2
   
       always fails if it starts to match "a" rather than  "bc".  However,  if       always  fails  if  it starts to match "a" rather than "bc". However, if
        the PCRE_JAVASCRIPT_COMPAT option is set at compile time, a back refer-         the PCRE_JAVASCRIPT_COMPAT option is set at compile time, a back refer-
        ence to an unset value matches an empty string.         ence to an unset value matches an empty string.
   
       Because there may be many capturing parentheses in a pattern, all  dig-       Because  there may be many capturing parentheses in a pattern, all dig-
       its  following a backslash are taken as part of a potential back refer-       its following a backslash are taken as part of a potential back  refer-
       ence number.  If the pattern continues with  a  digit  character,  some       ence  number.   If  the  pattern continues with a digit character, some
       delimiter  must  be  used  to  terminate  the  back  reference.  If the       delimiter must  be  used  to  terminate  the  back  reference.  If  the
       PCRE_EXTENDED option is set, this can be whitespace. Otherwise, the \g{       PCRE_EXTENDED  option  is  set, this can be white space. Otherwise, the
       syntax or an empty comment (see "Comments" below) can be used.       \g{ syntax or an empty comment (see "Comments" below) can be used.
   
    Recursive back references     Recursive back references
   
       A  back reference that occurs inside the parentheses to which it refers       A back reference that occurs inside the parentheses to which it  refers
       fails when the subpattern is first used, so, for example,  (a\1)  never       fails  when  the subpattern is first used, so, for example, (a\1) never
       matches.   However,  such references can be useful inside repeated sub-       matches.  However, such references can be useful inside  repeated  sub-
        patterns. For example, the pattern         patterns. For example, the pattern
   
          (a|b\1)+           (a|b\1)+
   
        matches any number of "a"s and also "aba", "ababbaa" etc. At each iter-         matches any number of "a"s and also "aba", "ababbaa" etc. At each iter-
       ation  of  the  subpattern,  the  back  reference matches the character       ation of the subpattern,  the  back  reference  matches  the  character
       string corresponding to the previous iteration. In order  for  this  to       string  corresponding  to  the previous iteration. In order for this to
       work,  the  pattern must be such that the first iteration does not need       work, the pattern must be such that the first iteration does  not  need
       to match the back reference. This can be done using alternation, as  in       to  match the back reference. This can be done using alternation, as in
        the example above, or by a quantifier with a minimum of zero.         the example above, or by a quantifier with a minimum of zero.
   
       Back  references of this type cause the group that they reference to be       Back references of this type cause the group that they reference to  be
       treated as an atomic group.  Once the whole group has been  matched,  a       treated  as  an atomic group.  Once the whole group has been matched, a
       subsequent  matching  failure cannot cause backtracking into the middle       subsequent matching failure cannot cause backtracking into  the  middle
        of the group.         of the group.
   
   
 ASSERTIONS  ASSERTIONS
   
       An assertion is a test on the characters  following  or  preceding  the       An  assertion  is  a  test on the characters following or preceding the
       current  matching  point that does not actually consume any characters.       current matching point that does not actually consume  any  characters.
       The simple assertions coded as \b, \B, \A, \G, \Z,  \z,  ^  and  $  are       The  simple  assertions  coded  as  \b, \B, \A, \G, \Z, \z, ^ and $ are
        described above.         described above.
   
       More  complicated  assertions  are  coded as subpatterns. There are two       More complicated assertions are coded as  subpatterns.  There  are  two
       kinds: those that look ahead of the current  position  in  the  subject       kinds:  those  that  look  ahead of the current position in the subject
       string,  and  those  that  look  behind  it. An assertion subpattern is       string, and those that look  behind  it.  An  assertion  subpattern  is
       matched in the normal way, except that it does not  cause  the  current       matched  in  the  normal way, except that it does not cause the current
        matching position to be changed.         matching position to be changed.
   
       Assertion  subpatterns are not capturing subpatterns. If such an asser-       Assertion subpatterns are not capturing subpatterns. If such an  asser-
       tion contains capturing subpatterns within it, these  are  counted  for       tion  contains  capturing  subpatterns within it, these are counted for
       the  purposes  of numbering the capturing subpatterns in the whole pat-       the purposes of numbering the capturing subpatterns in the  whole  pat-
       tern. However, substring capturing is carried  out  only  for  positive       tern.  However,  substring  capturing  is carried out only for positive
        assertions, because it does not make sense for negative assertions.         assertions, because it does not make sense for negative assertions.
   
       For  compatibility  with  Perl,  assertion subpatterns may be repeated;       For compatibility with Perl, assertion  subpatterns  may  be  repeated;
       though it makes no sense to assert the same thing  several  times,  the       though  it  makes  no sense to assert the same thing several times, the
       side  effect  of  capturing  parentheses may occasionally be useful. In       side effect of capturing parentheses may  occasionally  be  useful.  In
        practice, there only three cases:         practice, there only three cases:
   
       (1) If the quantifier is {0}, the  assertion  is  never  obeyed  during       (1)  If  the  quantifier  is  {0}, the assertion is never obeyed during
       matching.   However,  it  may  contain internal capturing parenthesized       matching.  However, it may  contain  internal  capturing  parenthesized
        groups that are called from elsewhere via the subroutine mechanism.         groups that are called from elsewhere via the subroutine mechanism.
   
       (2) If quantifier is {0,n} where n is greater than zero, it is  treated       (2)  If quantifier is {0,n} where n is greater than zero, it is treated
       as  if  it  were  {0,1}.  At run time, the rest of the pattern match is       as if it were {0,1}. At run time, the rest  of  the  pattern  match  is
        tried with and without the assertion, the order depending on the greed-         tried with and without the assertion, the order depending on the greed-
        iness of the quantifier.         iness of the quantifier.
   
       (3)  If  the minimum repetition is greater than zero, the quantifier is       (3) If the minimum repetition is greater than zero, the  quantifier  is
       ignored.  The assertion is obeyed just  once  when  encountered  during       ignored.   The  assertion  is  obeyed just once when encountered during
        matching.         matching.
   
    Lookahead assertions     Lookahead assertions
Line 5048  ASSERTIONS Line 5572  ASSERTIONS
   
          \w+(?=;)           \w+(?=;)
   
       matches a word followed by a semicolon, but does not include the  semi-       matches  a word followed by a semicolon, but does not include the semi-
        colon in the match, and         colon in the match, and
   
          foo(?!bar)           foo(?!bar)
   
       matches  any  occurrence  of  "foo" that is not followed by "bar". Note       matches any occurrence of "foo" that is not  followed  by  "bar".  Note
        that the apparently similar pattern         that the apparently similar pattern
   
          (?!foo)bar           (?!foo)bar
   
       does not find an occurrence of "bar"  that  is  preceded  by  something       does  not  find  an  occurrence  of "bar" that is preceded by something
       other  than "foo"; it finds any occurrence of "bar" whatsoever, because       other than "foo"; it finds any occurrence of "bar" whatsoever,  because
        the assertion (?!foo) is always true when the next three characters are         the assertion (?!foo) is always true when the next three characters are
        "bar". A lookbehind assertion is needed to achieve the other effect.         "bar". A lookbehind assertion is needed to achieve the other effect.
   
        If you want to force a matching failure at some point in a pattern, the         If you want to force a matching failure at some point in a pattern, the
       most convenient way to do it is  with  (?!)  because  an  empty  string       most  convenient  way  to  do  it  is with (?!) because an empty string
       always  matches, so an assertion that requires there not to be an empty       always matches, so an assertion that requires there not to be an  empty
        string must always fail.  The backtracking control verb (*FAIL) or (*F)         string must always fail.  The backtracking control verb (*FAIL) or (*F)
        is a synonym for (?!).         is a synonym for (?!).
   
    Lookbehind assertions     Lookbehind assertions
   
       Lookbehind  assertions start with (?<= for positive assertions and (?<!       Lookbehind assertions start with (?<= for positive assertions and  (?<!
        for negative assertions. For example,         for negative assertions. For example,
   
          (?<!foo)bar           (?<!foo)bar
   
       does find an occurrence of "bar" that is not  preceded  by  "foo".  The       does  find  an  occurrence  of "bar" that is not preceded by "foo". The
       contents  of  a  lookbehind  assertion are restricted such that all the       contents of a lookbehind assertion are restricted  such  that  all  the
        strings it matches must have a fixed length. However, if there are sev-         strings it matches must have a fixed length. However, if there are sev-
       eral  top-level  alternatives,  they  do  not all have to have the same       eral top-level alternatives, they do not all  have  to  have  the  same
        fixed length. Thus         fixed length. Thus
   
          (?<=bullock|donkey)           (?<=bullock|donkey)
Line 5088  ASSERTIONS Line 5612  ASSERTIONS
   
          (?<!dogs?|cats?)           (?<!dogs?|cats?)
   
       causes an error at compile time. Branches that match  different  length       causes  an  error at compile time. Branches that match different length
       strings  are permitted only at the top level of a lookbehind assertion.       strings are permitted only at the top level of a lookbehind  assertion.
        This is an extension compared with Perl, which requires all branches to         This is an extension compared with Perl, which requires all branches to
        match the same length of string. An assertion such as         match the same length of string. An assertion such as
   
          (?<=ab(c|de))           (?<=ab(c|de))
   
       is  not  permitted,  because  its single top-level branch can match two       is not permitted, because its single top-level  branch  can  match  two
        different lengths, but it is acceptable to PCRE if rewritten to use two         different lengths, but it is acceptable to PCRE if rewritten to use two
        top-level branches:         top-level branches:
   
          (?<=abc|abde)           (?<=abc|abde)
   
       In  some  cases, the escape sequence \K (see above) can be used instead       In some cases, the escape sequence \K (see above) can be  used  instead
        of a lookbehind assertion to get round the fixed-length restriction.         of a lookbehind assertion to get round the fixed-length restriction.
   
       The implementation of lookbehind assertions is, for  each  alternative,       The  implementation  of lookbehind assertions is, for each alternative,
       to  temporarily  move the current position back by the fixed length and       to temporarily move the current position back by the fixed  length  and
        then try to match. If there are insufficient characters before the cur-         then try to match. If there are insufficient characters before the cur-
        rent position, the assertion fails.         rent position, the assertion fails.
   
       In  UTF-8 mode, PCRE does not allow the \C escape (which matches a sin-       In a UTF mode, PCRE does not allow the \C escape (which matches a  sin-
       gle byte, even in UTF-8  mode)  to  appear  in  lookbehind  assertions,       gle  data  unit even in a UTF mode) to appear in lookbehind assertions,
       because  it  makes it impossible to calculate the length of the lookbe-       because it makes it impossible to calculate the length of  the  lookbe-
       hind. The \X and \R escapes,  which  can  match  different  numbers  of       hind.  The \X and \R escapes, which can match different numbers of data
       bytes, are also not permitted.       units, are also not permitted.
   
       "Subroutine"  calls  (see below) such as (?2) or (?&X) are permitted in       "Subroutine" calls (see below) such as (?2) or (?&X) are  permitted  in
       lookbehinds, as long as the subpattern matches a  fixed-length  string.       lookbehinds,  as  long as the subpattern matches a fixed-length string.
        Recursion, however, is not supported.         Recursion, however, is not supported.
   
       Possessive  quantifiers  can  be  used  in  conjunction with lookbehind       Possessive quantifiers can  be  used  in  conjunction  with  lookbehind
        assertions to specify efficient matching of fixed-length strings at the         assertions to specify efficient matching of fixed-length strings at the
        end of subject strings. Consider a simple pattern such as         end of subject strings. Consider a simple pattern such as
   
          abcd$           abcd$
   
       when  applied  to  a  long string that does not match. Because matching       when applied to a long string that does  not  match.  Because  matching
        proceeds from left to right, PCRE will look for each "a" in the subject         proceeds from left to right, PCRE will look for each "a" in the subject
       and  then  see  if what follows matches the rest of the pattern. If the       and then see if what follows matches the rest of the  pattern.  If  the
        pattern is specified as         pattern is specified as
   
          ^.*abcd$           ^.*abcd$
   
       the initial .* matches the entire string at first, but when this  fails       the  initial .* matches the entire string at first, but when this fails
        (because there is no following "a"), it backtracks to match all but the         (because there is no following "a"), it backtracks to match all but the
       last character, then all but the last two characters, and so  on.  Once       last  character,  then all but the last two characters, and so on. Once
       again  the search for "a" covers the entire string, from right to left,       again the search for "a" covers the entire string, from right to  left,
        so we are no better off. However, if the pattern is written as         so we are no better off. However, if the pattern is written as
   
          ^.*+(?<=abcd)           ^.*+(?<=abcd)
   
       there can be no backtracking for the .*+ item; it can  match  only  the       there  can  be  no backtracking for the .*+ item; it can match only the
       entire  string.  The subsequent lookbehind assertion does a single test       entire string. The subsequent lookbehind assertion does a  single  test
       on the last four characters. If it fails, the match fails  immediately.       on  the last four characters. If it fails, the match fails immediately.
       For  long  strings, this approach makes a significant difference to the       For long strings, this approach makes a significant difference  to  the
        processing time.         processing time.
   
    Using multiple assertions     Using multiple assertions
Line 5152  ASSERTIONS Line 5676  ASSERTIONS
   
          (?<=\d{3})(?<!999)foo           (?<=\d{3})(?<!999)foo
   
       matches "foo" preceded by three digits that are not "999". Notice  that       matches  "foo" preceded by three digits that are not "999". Notice that
       each  of  the  assertions is applied independently at the same point in       each of the assertions is applied independently at the  same  point  in
       the subject string. First there is a  check  that  the  previous  three       the  subject  string.  First  there  is a check that the previous three
       characters  are  all  digits,  and  then there is a check that the same       characters are all digits, and then there is  a  check  that  the  same
        three characters are not "999".  This pattern does not match "foo" pre-         three characters are not "999".  This pattern does not match "foo" pre-
       ceded  by  six  characters,  the first of which are digits and the last       ceded by six characters, the first of which are  digits  and  the  last
       three of which are not "999". For example, it  doesn't  match  "123abc-       three  of  which  are not "999". For example, it doesn't match "123abc-
        foo". A pattern to do that is         foo". A pattern to do that is
   
          (?<=\d{3}...)(?<!999)foo           (?<=\d{3}...)(?<!999)foo
   
       This  time  the  first assertion looks at the preceding six characters,       This time the first assertion looks at the  preceding  six  characters,
        checking that the first three are digits, and then the second assertion         checking that the first three are digits, and then the second assertion
        checks that the preceding three characters are not "999".         checks that the preceding three characters are not "999".
   
Line 5171  ASSERTIONS Line 5695  ASSERTIONS
   
          (?<=(?<!foo)bar)baz           (?<=(?<!foo)bar)baz
   
       matches  an occurrence of "baz" that is preceded by "bar" which in turn       matches an occurrence of "baz" that is preceded by "bar" which in  turn
        is not preceded by "foo", while         is not preceded by "foo", while
   
          (?<=\d{3}(?!999)...)foo           (?<=\d{3}(?!999)...)foo
   
       is another pattern that matches "foo" preceded by three digits and  any       is  another pattern that matches "foo" preceded by three digits and any
        three characters that are not "999".         three characters that are not "999".
   
   
 CONDITIONAL SUBPATTERNS  CONDITIONAL SUBPATTERNS
   
       It  is possible to cause the matching process to obey a subpattern con-       It is possible to cause the matching process to obey a subpattern  con-
       ditionally or to choose between two alternative subpatterns,  depending       ditionally  or to choose between two alternative subpatterns, depending
       on  the result of an assertion, or whether a specific capturing subpat-       on the result of an assertion, or whether a specific capturing  subpat-
       tern has already been matched. The two possible  forms  of  conditional       tern  has  already  been matched. The two possible forms of conditional
        subpattern are:         subpattern are:
   
          (?(condition)yes-pattern)           (?(condition)yes-pattern)
          (?(condition)yes-pattern|no-pattern)           (?(condition)yes-pattern|no-pattern)
   
       If  the  condition is satisfied, the yes-pattern is used; otherwise the       If the condition is satisfied, the yes-pattern is used;  otherwise  the
       no-pattern (if present) is used. If there are more  than  two  alterna-       no-pattern  (if  present)  is used. If there are more than two alterna-
       tives  in  the subpattern, a compile-time error occurs. Each of the two       tives in the subpattern, a compile-time error occurs. Each of  the  two
        alternatives may itself contain nested subpatterns of any form, includ-         alternatives may itself contain nested subpatterns of any form, includ-
        ing  conditional  subpatterns;  the  restriction  to  two  alternatives         ing  conditional  subpatterns;  the  restriction  to  two  alternatives
        applies only at the level of the condition. This pattern fragment is an         applies only at the level of the condition. This pattern fragment is an
Line 5202  CONDITIONAL SUBPATTERNS Line 5726  CONDITIONAL SUBPATTERNS
          (?(1) (A|B|C) | (D | (?(2)E|F) | E) )           (?(1) (A|B|C) | (D | (?(2)E|F) | E) )
   
   
       There  are  four  kinds of condition: references to subpatterns, refer-       There are four kinds of condition: references  to  subpatterns,  refer-
        ences to recursion, a pseudo-condition called DEFINE, and assertions.         ences to recursion, a pseudo-condition called DEFINE, and assertions.
   
    Checking for a used subpattern by number     Checking for a used subpattern by number
   
       If the text between the parentheses consists of a sequence  of  digits,       If  the  text between the parentheses consists of a sequence of digits,
        the condition is true if a capturing subpattern of that number has pre-         the condition is true if a capturing subpattern of that number has pre-
       viously matched. If there is more than one  capturing  subpattern  with       viously  matched.  If  there is more than one capturing subpattern with
       the  same  number  (see  the earlier section about duplicate subpattern       the same number (see the earlier  section  about  duplicate  subpattern
       numbers), the condition is true if any of them have matched. An  alter-       numbers),  the condition is true if any of them have matched. An alter-
       native  notation is to precede the digits with a plus or minus sign. In       native notation is to precede the digits with a plus or minus sign.  In
       this case, the subpattern number is relative rather than absolute.  The       this  case, the subpattern number is relative rather than absolute. The
       most  recently opened parentheses can be referenced by (?(-1), the next       most recently opened parentheses can be referenced by (?(-1), the  next
       most recent by (?(-2), and so on. Inside loops it can also  make  sense       most  recent  by (?(-2), and so on. Inside loops it can also make sense
        to refer to subsequent groups. The next parentheses to be opened can be         to refer to subsequent groups. The next parentheses to be opened can be
       referenced as (?(+1), and so on. (The value zero in any of these  forms       referenced  as (?(+1), and so on. (The value zero in any of these forms
        is not used; it provokes a compile-time error.)         is not used; it provokes a compile-time error.)
   
       Consider  the  following  pattern, which contains non-significant white       Consider the following pattern, which  contains  non-significant  white
        space to make it more readable (assume the PCRE_EXTENDED option) and to         space to make it more readable (assume the PCRE_EXTENDED option) and to
        divide it into three parts for ease of discussion:         divide it into three parts for ease of discussion:
   
          ( \( )?    [^()]+    (?(1) \) )           ( \( )?    [^()]+    (?(1) \) )
   
       The  first  part  matches  an optional opening parenthesis, and if that       The first part matches an optional opening  parenthesis,  and  if  that
        character is present, sets it as the first captured substring. The sec-         character is present, sets it as the first captured substring. The sec-
       ond  part  matches one or more characters that are not parentheses. The       ond part matches one or more characters that are not  parentheses.  The
       third part is a conditional subpattern that tests whether  or  not  the       third  part  is  a conditional subpattern that tests whether or not the
       first  set  of  parentheses  matched.  If they did, that is, if subject       first set of parentheses matched. If they  did,  that  is,  if  subject
       started with an opening parenthesis, the condition is true, and so  the       started  with an opening parenthesis, the condition is true, and so the
       yes-pattern  is  executed and a closing parenthesis is required. Other-       yes-pattern is executed and a closing parenthesis is  required.  Other-
       wise, since no-pattern is not present, the subpattern matches  nothing.       wise,  since no-pattern is not present, the subpattern matches nothing.
       In  other  words,  this  pattern matches a sequence of non-parentheses,       In other words, this pattern matches  a  sequence  of  non-parentheses,
        optionally enclosed in parentheses.         optionally enclosed in parentheses.
   
       If you were embedding this pattern in a larger one,  you  could  use  a       If  you  were  embedding  this pattern in a larger one, you cou       If  you  were  embedding  this pattern in a larger one, you cou
        relative reference:         relative reference:
   
          ...other stuff... ( \( )?    [^()]+    (?(-1) \) ) ...           ...other stuff... ( \( )?    [^()]+    (?(-1) \) ) ...
   
       This  makes  the  fragment independent of the parentheses in the larger       This makes the fragment independent of the parentheses  in  the  larger
        pattern.         pattern.
   
    Checking for a used subpattern by name     Checking for a used subpattern by name
   
       Perl uses the syntax (?(<name>)...) or (?('name')...)  to  test  for  a       Perl  uses  the  syntax  (?(<name>)...) or (?('name')...) to test for a
       used  subpattern  by  name.  For compatibility with earlier versions of       used subpattern by name. For compatibility  with  earlier  versions  of
       PCRE, which had this facility before Perl, the syntax  (?(name)...)  is       PCRE,  which  had this facility before Perl, the syntax (?(name)...) is
       also  recognized. However, there is a possible ambiguity with this syn-       also recognized. However, there is a possible ambiguity with this  syn-
       tax, because subpattern names may  consist  entirely  of  digits.  PCRE       tax,  because  subpattern  names  may  consist entirely of digits. PCRE
       looks  first for a named subpattern; if it cannot find one and the name       looks first for a named subpattern; if it cannot find one and the  name
       consists entirely of digits, PCRE looks for a subpattern of  that  num-       consists  entirely  of digits, PCRE looks for a subpattern of that num-
       ber,  which must be greater than zero. Using subpattern names that con-       ber, which must be greater than zero. Using subpattern names that  con-
        sist entirely of digits is not recommended.         sist entirely of digits is not recommended.
   
        Rewriting the above example to use a named subpattern gives this:         Rewriting the above example to use a named subpattern gives this:
   
          (?<OPEN> \( )?    [^()]+    (?(<OPEN>) \) )           (?<OPEN> \( )?    [^()]+    (?(<OPEN>) \) )
   
       If the name used in a condition of this kind is a duplicate,  the  test       If  the  name used in a condition of this kind is a duplicate, the test
       is  applied to all subpatterns of the same name, and is true if any one       is applied to all subpatterns of the same name, and is true if any  one
        of them has matched.         of them has matched.
   
    Checking for pattern recursion     Checking for pattern recursion
   
        If the condition is the string (R), and there is no subpattern with the         If the condition is the string (R), and there is no subpattern with the
       name  R, the condition is true if a recursive call to the whole pattern       name R, the condition is true if a recursive call to the whole  pattern
        or any subpattern has been made. If digits or a name preceded by amper-         or any subpattern has been made. If digits or a name preceded by amper-
        sand follow the letter R, for example:         sand follow the letter R, for example:
   
Line 5276  CONDITIONAL SUBPATTERNS Line 5800  CONDITIONAL SUBPATTERNS
   
        the condition is true if the most recent recursion is into a subpattern         the condition is true if the most recent recursion is into a subpattern
        whose number or name is given. This condition does not check the entire         whose number or name is given. This condition does not check the entire
       recursion  stack.  If  the  name  used in a condition of this kind is a       recursion stack. If the name used in a condition  of  this  kind  is  a
        duplicate, the test is applied to all subpatterns of the same name, and         duplicate, the test is applied to all subpatterns of the same name, and
        is true if any one of them is the most recent recursion.         is true if any one of them is the most recent recursion.
   
       At  "top  level",  all  these recursion test conditions are false.  The       At "top level", all these recursion test  conditions  are  false.   The
        syntax for recursive patterns is described below.         syntax for recursive patterns is described below.
   
    Defining subpatterns for use by reference only     Defining subpatterns for use by reference only
   
       If the condition is the string (DEFINE), and  there  is  no  subpattern       If  the  condition  is  the string (DEFINE), and there is no subpattern
       with  the  name  DEFINE,  the  condition is always false. In this case,       with the name DEFINE, the condition is  always  false.  In  this  case,
       there may be only one alternative  in  the  subpattern.  It  is  always       there  may  be  only  one  alternative  in the subpattern. It is always
       skipped  if  control  reaches  this  point  in the pattern; the idea of       skipped if control reaches this point  in  the  pattern;  the  idea  of
       DEFINE is that it can be used to define subroutines that can be  refer-       DEFINE  is that it can be used to define subroutines that can be refer-
       enced  from elsewhere. (The use of subroutines is described below.) For       enced from elsewhere. (The use of subroutines is described below.)  For
       example, a pattern to match an IPv4 address  such  as  "192.168.23.245"       example,  a  pattern  to match an IPv4 address such as "192.168.23.245"
       could be written like this (ignore whitespace and line breaks):       could be written like this (ignore white space and line breaks):
   
          (?(DEFINE) (?<byte> 2[0-4]\d | 25[0-5] | 1\d\d | [1-9]?\d) )           (?(DEFINE) (?<byte> 2[0-4]\d | 25[0-5] | 1\d\d | [1-9]?\d) )
          \b (?&byte) (\.(?&byte)){3} \b           \b (?&byte) (\.(?&byte)){3} \b
   
       The  first part of the pattern is a DEFINE group inside which a another       The first part of the pattern is a DEFINE group inside which a  another
       group named "byte" is defined. This matches an individual component  of       group  named "byte" is defined. This matches an individual component of
       an  IPv4  address  (a number less than 256). When matching takes place,       an IPv4 address (a number less than 256). When  matching  takes  place,
       this part of the pattern is skipped because DEFINE acts  like  a  false       this  part  of  the pattern is skipped because DEFINE acts like a false
       condition.  The  rest of the pattern uses references to the named group       condition. The rest of the pattern uses references to the  named  group
       to match the four dot-separated components of an IPv4 address,  insist-       to  match the four dot-separated components of an IPv4 address, insist-
        ing on a word boundary at each end.         ing on a word boundary at each end.
   
    Assertion conditions     Assertion conditions
   
       If  the  condition  is  not  in any of the above formats, it must be an       If the condition is not in any of the above  formats,  it  must  be  an
       assertion.  This may be a positive or negative lookahead or  lookbehind       assertion.   This may be a positive or negative lookahead or lookbehind
       assertion.  Consider  this  pattern,  again  containing non-significant       assertion. Consider  this  pattern,  again  containing  non-significant
        white space, and with the two alternatives on the second line:         white space, and with the two alternatives on the second line:
   
          (?(?=[^a-z]*[a-z])           (?(?=[^a-z]*[a-z])
          \d{2}-[a-z]{3}-\d{2}  |  \d{2}-\d{2}-\d{2} )           \d{2}-[a-z]{3}-\d{2}  |  \d{2}-\d{2}-\d{2} )
   
       The condition  is  a  positive  lookahead  assertion  that  matches  an       The  condition  is  a  positive  lookahead  assertion  that  matches an
       optional  sequence of non-letters followed by a letter. In other words,       optional sequence of non-letters followed by a letter. In other  words,
       it tests for the presence of at least one letter in the subject.  If  a       it  tests  for the presence of at least one letter in the subject. If a
       letter  is found, the subject is matched against the first alternative;       letter is found, the subject is matched against the first  alternative;
       otherwise it is  matched  against  the  second.  This  pattern  matches       otherwise  it  is  matched  against  the  second.  This pattern matches
       strings  in  one  of the two forms dd-aaa-dd or dd-dd-dd, where aaa are       strings in one of the two forms dd-aaa-dd or dd-dd-dd,  where  aaa  are
        letters and dd are digits.         letters and dd are digits.
   
   
Line 5329  COMMENTS Line 5853  COMMENTS
        There are two ways of including comments in patterns that are processed         There are two ways of including comments in patterns that are processed
        by PCRE. In both cases, the start of the comment must not be in a char-         by PCRE. In both cases, the start of the comment must not be in a char-
        acter class, nor in the middle of any other sequence of related charac-         acter class, nor in the middle of any other sequence of related charac-
       ters  such  as  (?: or a subpattern name or number. The characters that       ters such as (?: or a subpattern name or number.  The  characters  that
        make up a comment play no part in the pattern matching.         make up a comment play no part in the pattern matching.
   
       The sequence (?# marks the start of a comment that continues up to  the       The  sequence (?# marks the start of a comment that continues up to the
       next  closing parenthesis. Nested parentheses are not permitted. If the       next closing parenthesis. Nested parentheses are not permitted. If  the
        PCRE_EXTENDED option is set, an unescaped # character also introduces a         PCRE_EXTENDED option is set, an unescaped # character also introduces a
       comment,  which  in  this  case continues to immediately after the next       comment, which in this case continues to  immediately  after  the  next
       newline character or character sequence in the pattern.  Which  charac-       newline  character  or character sequence in the pattern. Which charac-
        ters are interpreted as newlines is controlled by the options passed to         ters are interpreted as newlines is controlled by the options passed to
       pcre_compile() or by a special sequence at the start of the pattern, as       a  compiling function or by a special sequence at the start of the pat-
       described  in  the  section  entitled "Newline conventions" above. Note       tern, as described in the section entitled "Newline conventions" above.
       that the end of this type of comment is a literal newline  sequence  in       Note that the end of this type of comment is a literal newline sequence
       the pattern; escape sequences that happen to represent a newline do not       in the pattern; escape sequences that happen to represent a newline  do
       count. For example, consider this pattern when  PCRE_EXTENDED  is  set,       not  count.  For  example,  consider this pattern when PCRE_EXTENDED is
       and the default newline convention is in force:       set, and the default newline convention is in force:
   
          abc #comment \n still comment           abc #comment \n still comment
   
       On  encountering  the  # character, pcre_compile() skips along, looking       On encountering the # character, pcre_compile()  skips  along,  looking
       for a newline in the pattern. The sequence \n is still literal at  this       for  a newline in the pattern. The sequence \n is still literal at this
       stage,  so  it does not terminate the comment. Only an actual character       stage, so it does not terminate the comment. Only an  actual  character
        with the code value 0x0a (the default newline) does so.         with the code value 0x0a (the default newline) does so.
   
   
 RECURSIVE PATTERNS  RECURSIVE PATTERNS
   
       Consider the problem of matching a string in parentheses, allowing  for       Consider  the problem of matching a string in parentheses, allowing for
       unlimited  nested  parentheses.  Without the use of recursion, the best       unlimited nested parentheses. Without the use of  recursion,  the  best
       that can be done is to use a pattern that  matches  up  to  some  fixed       that  can  be  done  is  to use a pattern that matches up to some fixed
       depth  of  nesting.  It  is not possible to handle an arbitrary nesting       depth of nesting. It is not possible to  handle  an  arbitrary  nesting
        depth.         depth.
   
        For some time, Perl has provided a facility that allows regular expres-         For some time, Perl has provided a facility that allows regular expres-
       sions  to recurse (amongst other things). It does this by interpolating       sions to recurse (amongst other things). It does this by  interpolating
       Perl code in the expression at run time, and the code can refer to  the       Perl  code in the expression at run time, and the code can refer to the
        expression itself. A Perl pattern using code interpolation to solve the         expression itself. A Perl pattern using code interpolation to solve the
        parentheses problem can be created like this:         parentheses problem can be created like this:
   
Line 5373  RECURSIVE PATTERNS Line 5897  RECURSIVE PATTERNS
        refers recursively to the pattern in which it appears.         refers recursively to the pattern in which it appears.
   
        Obviously, PCRE cannot support the interpolation of Perl code. Instead,         Obviously, PCRE cannot support the interpolation of Perl code. Instead,
       it supports special syntax for recursion of  the  entire  pattern,  and       it  supports  special  syntax  for recursion of the entire pattern, and
       also  for  individual  subpattern  recursion. After its introduction in       also for individual subpattern recursion.  After  its  introduction  in
       PCRE and Python, this kind of  recursion  was  subsequently  introduced       PCRE  and  Python,  this  kind of recursion was subsequently introduced
        into Perl at release 5.10.         into Perl at release 5.10.
   
       A  special  item  that consists of (? followed by a number greater than       A special item that consists of (? followed by a  number  greater  than
       zero and a closing parenthesis is a recursive subroutine  call  of  the       zero  and  a  closing parenthesis is a recursive subroutine call of the
       subpattern  of  the  given  number, provided that it occurs inside that       subpattern of the given number, provided that  it  occurs  inside  that
       subpattern. (If not, it is a non-recursive subroutine  call,  which  is       subpattern.  (If  not,  it is a non-recursive subroutine call, which is
       described  in  the  next  section.)  The special item (?R) or (?0) is a       described in the next section.) The special item  (?R)  or  (?0)  is  a
        recursive call of the entire regular expression.         recursive call of the entire regular expression.
   
       This PCRE pattern solves the nested  parentheses  problem  (assume  the       This  PCRE  pattern  solves  the nested parentheses problem (assume the
        PCRE_EXTENDED option is set so that white space is ignored):         PCRE_EXTENDED option is set so that white space is ignored):
   
          \( ( [^()]++ | (?R) )* \)           \( ( [^()]++ | (?R) )* \)
   
       First  it matches an opening parenthesis. Then it matches any number of       First it matches an opening parenthesis. Then it matches any number  of
       substrings which can either be a  sequence  of  non-parentheses,  or  a       substrings  which  can  either  be  a sequence of non-parentheses, or a
       recursive  match  of the pattern itself (that is, a correctly parenthe-       recursive match of the pattern itself (that is, a  correctly  parenthe-
        sized substring).  Finally there is a closing parenthesis. Note the use         sized substring).  Finally there is a closing parenthesis. Note the use
        of a possessive quantifier to avoid backtracking into sequences of non-         of a possessive quantifier to avoid backtracking into sequences of non-
        parentheses.         parentheses.
   
       If this were part of a larger pattern, you would not  want  to  recurse       If  this  were  part of a larger pattern, you would        If  this  were  part of a larger pattern, you would 
        the entire pattern, so instead you could use this:         the entire pattern, so instead you could use this:
   
          ( \( ( [^()]++ | (?1) )* \) )           ( \( ( [^()]++ | (?1) )* \) )
   
       We  have  put the pattern into parentheses, and caused the recursion to       We have put the pattern into parentheses, and caused the  recursion  to
        refer to them instead of the whole pattern.         refer to them instead of the whole pattern.
   
       In a larger pattern,  keeping  track  of  parenthesis  numbers  can  be       In  a  larger  pattern,  keeping  track  of  parenthesis numbers can be
       tricky.  This is made easier by the use of relative references. Instead       tricky. This is made easier by the use of relative references.  Instead
        of (?1) in the pattern above you can write (?-2) to refer to the second         of (?1) in the pattern above you can write (?-2) to refer to the second
       most  recently  opened  parentheses  preceding  the recursion. In other       most recently opened parentheses  preceding  the  recursion.  In  other
       words, a negative number counts capturing  parentheses  leftwards  from       words,  a  negative  number counts capturing parentheses leftwards from
        the point at which it is encountered.         the point at which it is encountered.
   
       It  is  also  possible  to refer to subsequently opened parentheses, by       It is also possible to refer to  subsequently  opened  parentheses,  by
       writing references such as (?+2). However, these  cannot  be  recursive       writing  references  such  as (?+2). However, these cannot be recursive
       because  the  reference  is  not inside the parentheses that are refer-       because the reference is not inside the  parentheses  that  are  refer-
       enced. They are always non-recursive subroutine calls, as described  in       enced.  They are always non-recursive subroutine calls, as described in
        the next section.         the next section.
   
       An  alternative  approach is to use named parentheses instead. The Perl       An alternative approach is to use named parentheses instead.  The  Perl
       syntax for this is (?&name); PCRE's earlier syntax  (?P>name)  is  also       syntax  for  this  is (?&name); PCRE's earlier syntax (?P>name) is also
        supported. We could rewrite the above example as follows:         supported. We could rewrite the above example as follows:
   
          (?<pn> \( ( [^()]++ | (?&pn) )* \) )           (?<pn> \( ( [^()]++ | (?&pn) )* \) )
   
       If  there  is more than one subpattern with the same name, the earliest       If there is more than one subpattern with the same name,  the  earliest
        one is used.         one is used.
   
       This particular example pattern that we have been looking  at  contains       This  particular  example pattern that we have been looking at contains
        nested unlimited repeats, and so the use of a possessive quantifier for         nested unlimited repeats, and so the use of a possessive quantifier for
        matching strings of non-parentheses is important when applying the pat-         matching strings of non-parentheses is important when applying the pat-
       tern  to  strings  that do not match. For example, when this pattern is       tern to strings that do not match. For example, when  this  pattern  is
        applied to         applied to
   
          (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()           (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()
   
       it yields "no match" quickly. However, if a  possessive  quantifier  is       it  yields  "no  match" quickly. However, if a possessive quantifier is
       not  used, the match runs for a very long time indeed because there are       not used, the match runs for a very long time indeed because there  are
       so many different ways the + and * repeats can carve  up  the  subject,       so  many  different  ways the + and * repeats can carve up the subject,
        and all have to be tested before failure can be reported.         and all have to be tested before failure can be reported.
   
       At  the  end  of a match, the values of capturing parentheses are those       At the end of a match, the values of capturing  parentheses  are  those
       from the outermost level. If you want to obtain intermediate values,  a       from  the outermost level. If you want to obtain intermediate values, a
       callout  function can be used (see below and the pcrecallout documenta-       callout function can be used (see below and the pcrecallout  documenta-
        tion). If the pattern above is matched against         tion). If the pattern above is matched against
   
          (ab(cd)ef)           (ab(cd)ef)
   
       the value for the inner capturing parentheses  (numbered  2)  is  "ef",       the  value  for  the  inner capturing parentheses (numbered 2) is "ef",
       which  is the last value taken on at the top level. If a capturing sub-       which is the last value taken on at the top level. If a capturing  sub-
       pattern is not matched at the top level, its final  captured  value  is       pattern  is  not  matched at the top level, its final captured value is
       unset,  even  if  it was (temporarily) set at a deeper level during the       unset, even if it was (temporarily) set at a deeper  level  during  the
        matching process.         matching process.
   
       If there are more than 15 capturing parentheses in a pattern, PCRE  has       If  there are more than 15 capturing parentheses in a pattern, PCRE has
       to  obtain extra memory to store data during a recursion, which it does       to obtain extra memory to store data during a recursion, which it  does
        by using pcre_malloc, freeing it via pcre_free afterwards. If no memory         by using pcre_malloc, freeing it via pcre_free afterwards. If no memory
        can be obtained, the match fails with the PCRE_ERROR_NOMEMORY error.         can be obtained, the match fails with the PCRE_ERROR_NOMEMORY error.
   
       Do  not  confuse  the (?R) item with the condition (R), which tests for       Do not confuse the (?R) item with the condition (R),  which  tests  for
       recursion.  Consider this pattern, which matches text in  angle  brack-       recursion.   Consider  this pattern, which matches text in angle brack-
       ets,  allowing for arbitrary nesting. Only digits are allowed in nested       ets, allowing for arbitrary nesting. Only digits are allowed in  nested
       brackets (that is, when recursing), whereas any characters are  permit-       brackets  (that is, when recursing), whereas any characters are permit-
        ted at the outer level.         ted at the outer level.
   
          < (?: (?(R) \d++  | [^<>]*+) | (?R)) * >           < (?: (?(R) \d++  | [^<>]*+) | (?R)) * >
   
       In  this  pattern, (?(R) is the start of a conditional subpattern, with       In this pattern, (?(R) is the start of a conditional  subpattern,  with
       two different alternatives for the recursive and  non-recursive  cases.       two  different  alternatives for the recursive and non-recursive cases.
        The (?R) item is the actual recursive call.         The (?R) item is the actual recursive call.
   
    Differences in recursion processing between PCRE and Perl     Differences in recursion processing between PCRE and Perl
   
       Recursion  processing  in PCRE differs from Perl in two important ways.       Recursion processing in PCRE differs from Perl in two  important  ways.
       In PCRE (like Python, but unlike Perl), a recursive subpattern call  is       In  PCRE (like Python, but unlike Perl), a recursive subpattern call is
        always treated as an atomic group. That is, once it has matched some of         always treated as an atomic group. That is, once it has matched some of
        the subject string, it is never re-entered, even if it contains untried         the subject string, it is never re-entered, even if it contains untried
       alternatives  and  there  is a subsequent matching failure. This can be       alternatives and there is a subsequent matching failure.  This  can  be
       illustrated by the following pattern, which purports to match a  palin-       illustrated  by the following pattern, which purports to match a palin-
       dromic  string  that contains an odd number of characters (for example,       dromic string that contains an odd number of characters  (for  example,
        "a", "aba", "abcba", "abcdcba"):         "a", "aba", "abcba", "abcdcba"):
   
          ^(.|(.)(?1)\2)$           ^(.|(.)(?1)\2)$
   
        The idea is that it either matches a single character, or two identical         The idea is that it either matches a single character, or two identical
       characters  surrounding  a sub-palindrome. In Perl, this pattern works;       characters surrounding a sub-palindrome. In Perl, this  pattern  works;
       in PCRE it does not if the pattern is  longer  than  three  characters.       in  PCRE  it  does  not if the pattern is longer than three characters.
        Consider the subject string "abcba":         Consider the subject string "abcba":
   
       At  the  top level, the first character is matched, but as it is not at       At the top level, the first character is matched, but as it is  not  at
        the end of the string, the first alternative fails; the second alterna-         the end of the string, the first alternative fails; the second alterna-
        tive is taken and the recursion kicks in. The recursive call to subpat-         tive is taken and the recursion kicks in. The recursive call to subpat-
       tern 1 successfully matches the next character ("b").  (Note  that  the       tern  1  successfully  matches the next character ("b"). (Note that the
        beginning and end of line tests are not part of the recursion).         beginning and end of line tests are not part of the recursion).
   
       Back  at  the top level, the next character ("c") is compared with what       Back at the top level, the next character ("c") is compared  with  what
       subpattern 2 matched, which was "a". This fails. Because the  recursion       subpattern  2 matched, which was "a". This fails. Because the recursion
       is  treated  as  an atomic group, there are now no backtracking points,       is treated as an atomic group, there are now  no  backtracking  points,
       and so the entire match fails. (Perl is able, at  this  point,  to  re-       and  so  the  entire  match fails. (Perl is able, at this point, to re-
       enter  the  recursion  and try the second alternative.) However, if the       enter the recursion and try the second alternative.)  However,  if  the
        pattern is written with the alternatives in the other order, things are         pattern is written with the alternatives in the other order, things are
        different:         different:
   
          ^((.)(?1)\2|.)$           ^((.)(?1)\2|.)$
   
       This  time,  the recursing alternative is tried first, and continues to       This time, the recursing alternative is tried first, and  continues  to
       recurse until it runs out of characters, at which point  the  recursion       recurse  until  it runs out of characters, at which point the recursion
       fails.  But  this  time  we  do  have another alternative to try at the       fails. But this time we do have  another  alternative  to  try  at  the
       higher level. That is the big difference:  in  the  previous  case  the       higher  level.  That  is  the  big difference: in the previous case the
        remaining alternative is at a deeper recursion level, which PCRE cannot         remaining alternative is at a deeper recursion level, which PCRE cannot
        use.         use.
   
       To change the pattern so that it matches all palindromic  strings,  not       To  change  the pattern so that it matches all palindromic strings, not
       just  those  with an odd number of characters, it is tempting to change       just those with an odd number of characters, it is tempting  to  change
        the pattern to this:         the pattern to this:
   
          ^((.)(?1)\2|.?)$           ^((.)(?1)\2|.?)$
   
       Again, this works in Perl, but not in PCRE, and for  the  same  reason.       Again,  this  works  in Perl, but not in PCRE, and for the same reason.
       When  a  deeper  recursion has matched a single character, it cannot be       When a deeper recursion has matched a single character,  it  cannot  be
       entered again in order to match an empty string.  The  solution  is  to       entered  again  in  order  to match an empty string. The solution is to
       separate  the two cases, and write out the odd and even cases as alter-       separate the two cases, and write out the odd and even cases as  alter-
        natives at the higher level:         natives at the higher level:
   
          ^(?:((.)(?1)\2|)|((.)(?3)\4|.))           ^(?:((.)(?1)\2|)|((.)(?3)\4|.))
   
       If you want to match typical palindromic phrases, the  pattern  has  to       If  you  want  to match typical palindromic phrases, the patte       If  you  want  to match typical palindromic phrases, the patte
        ignore all non-word characters, which can be done like this:         ignore all non-word characters, which can be done like this:
   
          ^\W*+(?:((.)\W*+(?1)\W*+\2|)|((.)\W*+(?3)\W*+\4|\W*+.\W*+))\W*+$           ^\W*+(?:((.)\W*+(?1)\W*+\2|)|((.)\W*+(?3)\W*+\4|\W*+.\W*+))\W*+$
   
        If run with the PCRE_CASELESS option, this pattern matches phrases such         If run with the PCRE_CASELESS option, this pattern matches phrases such
        as "A man, a plan, a canal: Panama!" and it works well in both PCRE and         as "A man, a plan, a canal: Panama!" and it works well in both PCRE and
       Perl.  Note the use of the possessive quantifier *+ to avoid backtrack-       Perl. Note the use of the possessive quantifier *+ to avoid  backtrack-
       ing into sequences of non-word characters. Without this, PCRE  takes  a       ing  into  sequences of non-word characters. Without this, PCRE takes a
       great  deal  longer  (ten  times or more) to match typical phrases, and       great deal longer (ten times or more) to  match  typical  phrases,  and
        Perl takes so long that you think it has gone into a loop.         Perl takes so long that you think it has gone into a loop.
   
       WARNING: The palindrome-matching patterns above work only if  the  sub-       WARNING:  The  palindrome-matching patterns above work only if the sub-
       ject  string  does not start with a palindrome that is shorter than the       ject string does not start with a palindrome that is shorter  than  the
       entire string.  For example, although "abcba" is correctly matched,  if       entire  string.  For example, although "abcba" is correctly matched, if
       the  subject  is "ababa", PCRE finds the palindrome "aba" at the start,       the subject is "ababa", PCRE finds the palindrome "aba" at  the  start,
       then fails at top level because the end of the string does not  follow.       then  fails at top level because the end of the string does not follow.
       Once  again, it cannot jump back into the recursion to try other alter-       Once again, it cannot jump back into the recursion to try other  alter-
        natives, so the entire match fails.         natives, so the entire match fails.
   
       The second way in which PCRE and Perl differ in  their  recursion  pro-       The  second  way  in which PCRE and Perl differ in their recursion pro-
       cessing  is in the handling of captured values. In Perl, when a subpat-       cessing is in the handling of captured values. In Perl, when a  subpat-
       tern is called recursively or as a subpattern (see the  next  section),       tern  is  called recursively or as a subpattern (see the next section),
       it  has  no  access to any values that were captured outside the recur-       it has no access to any values that were captured  outside  the  recur-
       sion, whereas in PCRE these values can  be  referenced.  Consider  this       sion,  whereas  in  PCRE  these values can be referenced. Consider this
        pattern:         pattern:
   
          ^(.)(\1|a(?2))           ^(.)(\1|a(?2))
   
       In  PCRE,  this  pattern matches "bab". The first capturing parentheses       In PCRE, this pattern matches "bab". The  first  capturing  parentheses
       match "b", then in the second group, when the back reference  \1  fails       match  "b",  then in the second group, when the back reference \1 fails
       to  match "b", the second alternative matches "a" and then recurses. In       to match "b", the second alternative matches "a" and then recurses.  In
       the recursion, \1 does now match "b" and so the whole  match  succeeds.       the  recursion,  \1 does now match "b" and so the whole match succeeds.
       In  Perl,  the pattern fails to match because inside the recursive call       In Perl, the pattern fails to match because inside the  recursive  call
        \1 cannot access the externally set value.         \1 cannot access the externally set value.
   
   
 SUBPATTERNS AS SUBROUTINES  SUBPATTERNS AS SUBROUTINES
   
       If the syntax for a recursive subpattern call (either by number  or  by       If  the  syntax for a recursive subpattern call (either by number or by
       name)  is  used outside the parentheses to which it refers, it operates       name) is used outside the parentheses to which it refers,  it  operates
       like a subroutine in a programming language. The called subpattern  may       like  a subroutine in a programming language. The called subpattern may
       be  defined  before or after the reference. A numbered reference can be       be defined before or after the reference. A numbered reference  can  be
        absolute or relative, as in these examples:         absolute or relative, as in these examples:
   
          (...(absolute)...)...(?2)...           (...(absolute)...)...(?2)...
Line 5578  SUBPATTERNS AS SUBROUTINES Line 6102  SUBPATTERNS AS SUBROUTINES
   
          (sens|respons)e and \1ibility           (sens|respons)e and \1ibility
   
       matches "sense and sensibility" and "response and responsibility",  but       matches  "sense and sensibility" and "response and responsibility", but
        not "sense and responsibility". If instead the pattern         not "sense and responsibility". If instead the pattern
   
          (sens|respons)e and (?1)ibility           (sens|respons)e and (?1)ibility
   
       is  used, it does match "sense and responsibility" as well as the other       is used, it does match "sense and responsibility" as well as the  other
       two strings. Another example is  given  in  the  discussion  of  DEFINE       two  strings.  Another  example  is  given  in the discussion of DEFINE
        above.         above.
   
       All  subroutine  calls, whether recursive or not, are always treated as       All subroutine calls, whether recursive or not, are always  treated  as
       atomic groups. That is, once a subroutine has matched some of the  sub-       atomic  groups. That is, once a subroutine has matched some of the sub-
        ject string, it is never re-entered, even if it contains untried alter-         ject string, it is never re-entered, even if it contains untried alter-
       natives and there is  a  subsequent  matching  failure.  Any  capturing       natives  and  there  is  a  subsequent  matching failure. Any capturing
       parentheses  that  are  set  during the subroutine call revert to their       parentheses that are set during the subroutine  call  revert  to  their
        previous values afterwards.         previous values afterwards.
   
       Processing options such as case-independence are fixed when  a  subpat-       Processing  options  such as case-independence are fixed when a subpat-
       tern  is defined, so if it is used as a subroutine, such options cannot       tern is defined, so if it is used as a subroutine, such options  cannot
        be changed for different calls. For example, consider this pattern:         be changed for different calls. For example, consider this pattern:
   
          (abc)(?i:(?-1))           (abc)(?i:(?-1))
   
       It matches "abcabc". It does not match "abcABC" because the  change  of       It  matches  "abcabc". It does not match "abcABC" because t       It  matches  "abcabc". It does not match "abcABC" because the change of
        processing option does not affect the called subpattern.         processing option does not affect the called subpattern.
   
   
 ONIGURUMA SUBROUTINE SYNTAX  ONIGURUMA SUBROUTINE SYNTAX
   
       For  compatibility with Oniguruma, the non-Perl syntax \g followed by a       For compatibility with Oniguruma, the non-Perl syntax \g followed by  a
        name or a number enclosed either in angle brackets or single quotes, is         name or a number enclosed either in angle brackets or single quotes, is
       an  alternative  syntax  for  referencing a subpattern as a subroutine,       an alternative syntax for referencing a  subpattern  as  a  subroutine,
       possibly recursively. Here are two of the examples used above,  rewrit-       possibly  recursively. Here are two of the examples used above, rewrit-
        ten using this syntax:         ten using this syntax:
   
          (?<pn> \( ( (?>[^()]+) | \g<pn> )* \) )           (?<pn> \( ( (?>[^()]+) | \g<pn> )* \) )
          (sens|respons)e and \g'1'ibility           (sens|respons)e and \g'1'ibility
   
       PCRE  supports  an extension to Oniguruma: if a number is preceded by a       PCRE supports an extension to Oniguruma: if a number is preceded  by  a
        plus or a minus sign it is taken as a relative reference. For example:         plus or a minus sign it is taken as a relative reference. For example:
   
          (abc)(?i:\g<-1>)           (abc)(?i:\g<-1>)
   
       Note that \g{...} (Perl syntax) and \g<...> (Oniguruma syntax) are  not       Note  that \g{...} (Perl syntax) and \g<...> (Oniguruma syntax) are not
       synonymous.  The former is a back reference; the latter is a subroutine       synonymous. The former is a back reference; the latter is a  subroutine
        call.         call.
   
   
 CALLOUTS  CALLOUTS
   
        Perl has a feature whereby using the sequence (?{...}) causes arbitrary         Perl has a feature whereby using the sequence (?{...}) causes arbitrary
       Perl  code to be obeyed in the middle of matching a regular expression.       Perl code to be obeyed in the middle of matching a regular  expression.
        This makes it possible, amongst other things, to extract different sub-         This makes it possible, amongst other things, to extract different sub-
        strings that match the same pair of parentheses when there is a repeti-         strings that match the same pair of parentheses when there is a repeti-
        tion.         tion.
   
        PCRE provides a similar feature, but of course it cannot obey arbitrary         PCRE provides a similar feature, but of course it cannot obey arbitrary
        Perl code. The feature is called "callout". The caller of PCRE provides         Perl code. The feature is called "callout". The caller of PCRE provides
       an external function by putting its entry point in the global  variable       an  external function by putting its entry point in the global variable
       pcre_callout.   By default, this variable contains NULL, which disables       pcre_callout (8-bit library) or  pcre16_callout  (16-bit  library).  By
       all calling out.       default, this variable contains NULL, which disables all calling out.
   
       Within a regular expression, (?C) indicates the  points  at  which  the       Within  a  regular  expression,  (?C) indicates the points at which the
       external  function  is  to be called. If you want to identify different       external function is to be called. If you want  to  identify  different
       callout points, you can put a number less than 256 after the letter  C.       callout  points, you can put a number less than 256 after the letter C.
       The  default  value is zero.  For example, this pattern has two callout       The default value is zero.  For example, this pattern has  two  callout
        points:         points:
   
          (?C1)abc(?C2)def           (?C1)abc(?C2)def
   
       If the PCRE_AUTO_CALLOUT flag is passed to pcre_compile(), callouts are       If  the PCRE_AUTO_CALLOUT flag is passed to a compiling function, call-
       automatically  installed  before each item in the pattern. They are all       outs are automatically installed before each item in the pattern.  They
       numbered 255.       are all numbered 255.
   
       During matching, when PCRE reaches a callout point (and pcre_callout is       During  matching, when PCRE reaches a callout point, the external func-
       set),  the  external function is called. It is provided with the number       tion is called. It is provided with the  number  of  the  callout,  the
       of the callout, the position in the pattern, and, optionally, one  item       position  in  the pattern, and, optionally, one item of data originally
       of  data  originally supplied by the caller of pcre_exec(). The callout       supplied by the caller of the matching function. The  callout  function
       function may cause matching to proceed, to backtrack, or to fail  alto-       may  cause  matching to proceed, to backtrack, or to fail altogether. A
       gether. A complete description of the interface to the callout function       complete description of the interface to the callout function is  given
       is given in the pcrecallout documentation.       in the pcrecallout documentation.
   
   
 BACKTRACKING CONTROL  BACKTRACKING CONTROL
   
       Perl 5.10 introduced a number of "Special Backtracking Control  Verbs",       Perl  5.10 introduced a number of "Special Backtracking Control Verbs",
        which are described in the Perl documentation as "experimental and sub-         which are described in the Perl documentation as "experimental and sub-
       ject to change or removal in a future version of Perl". It goes  on  to       ject  to  change or removal in a future version of Perl". It goes on to
       say:  "Their usage in production code should be noted to avoid problems       say: "Their usage in production code should be noted to avoid  problems
        during upgrades." The same remarks apply to the PCRE features described         during upgrades." The same remarks apply to the PCRE features described
        in this section.         in this section.
   
       Since  these  verbs  are  specifically related to backtracking, most of       Since these verbs are specifically related  to  backtracking,  most  of
       them can be  used  only  when  the  pattern  is  to  be  matched  using       them  can  be  used only when the pattern is to be matched using one of
       pcre_exec(), which uses a backtracking algorithm. With the exception of       the traditional matching functions, which use a backtracking algorithm.
       (*FAIL), which behaves like a failing negative assertion, they cause an       With  the  exception  of (*FAIL), which behaves like a failing negative
       error if encountered by pcre_dfa_exec().       assertion, they cause an error if encountered by a DFA  matching  func-
        tion.
   
        If  any of these verbs are used in an assertion or in a subpattern that         If  any of these verbs are used in an assertion or in a subpattern that
        is called as a subroutine (whether or not recursively), their effect is         is called as a subroutine (whether or not recursively), their effect is
Line 5682  BACKTRACKING CONTROL Line 6207  BACKTRACKING CONTROL
        that  is  encountered in a successful positive assertion is passed back         that  is  encountered in a successful positive assertion is passed back
        when a match succeeds (compare capturing  parentheses  in  assertions).         when a match succeeds (compare capturing  parentheses  in  assertions).
        Note that such subpatterns are processed as anchored at the point where         Note that such subpatterns are processed as anchored at the point where
       they are tested. Note also that Perl's treatment of subroutines is dif-       they are tested. Note also that Perl's  treatment  of  subroutines  and
       ferent in some cases.       assertions is different in some cases.
   
        The  new verbs make use of what was previously invalid syntax: an open-         The  new verbs make use of what was previously invalid syntax: an open-
        ing parenthesis followed by an asterisk. They are generally of the form         ing parenthesis followed by an asterisk. They are generally of the form
        (*VERB)  or (*VERB:NAME). Some may take either form, with differing be-         (*VERB)  or (*VERB:NAME). Some may take either form, with differing be-
        haviour, depending on whether or not an argument is present. A name  is         haviour, depending on whether or not an argument is present. A name  is
        any sequence of characters that does not include a closing parenthesis.         any sequence of characters that does not include a closing parenthesis.
       If the name is empty, that is, if the closing  parenthesis  immediately       The maximum length of name is 255 in the 8-bit library and 65535 in the
       follows  the  colon,  the effect is as if the colon were not there. Any       16-bit library. If the name is empty, that is, if the closing parenthe-
       number of these verbs may occur in a pattern.       sis immediately follows the colon, the effect is as if the  colon  were
        not there. Any number of these verbs may occur in a pattern.
   
       PCRE contains some optimizations that are used to speed up matching  by   Optimizations that affect backtracking verbs
 
        PCRE  contains some optimizations that are used to speed up matching by
        running some checks at the start of each match attempt. For example, it         running some checks at the start of each match attempt. For example, it
       may know the minimum length of matching subject, or that  a  particular       may  know  the minimum length of matching subject, or that a particular
       character  must  be present. When one of these optimizations suppresses       character must be present. When one of these  optimizations  suppresses
       the running of a match, any included backtracking verbs  will  not,  of       the  running  of  a match, any included backtracking verbs will not, of
        course, be processed. You can suppress the start-of-match optimizations         course, be processed. You can suppress the start-of-match optimizations
       by setting the PCRE_NO_START_OPTIMIZE  option  when  calling  pcre_com-       by  setting  the  PCRE_NO_START_OPTIMIZE  opt       by  setting  the  PCRE_NO_START_OPTIMIZE  option when calling pcre_com-
        pile() or pcre_exec(), or by starting the pattern with (*NO_START_OPT).         pile() or pcre_exec(), or by starting the pattern with (*NO_START_OPT).
          There is more discussion of this option in the section entitled "Option
          bits for pcre_exec()" in the pcreapi documentation.
   
       Experiments  with  Perl  suggest that it too has similar optimizations,       Experiments with Perl suggest that it too  has  similar  optimizations,
        sometimes leading to anomalous results.         sometimes leading to anomalous results.
   
    Verbs that act immediately     Verbs that act immediately
   
       The following verbs act as soon as they are encountered. They  may  not       The  following  verbs act as soon as they are encountered. Th       The  following  verbs act as soon as they are encountered. They may not
        be followed by a name.         be followed by a name.
   
           (*ACCEPT)            (*ACCEPT)
   
       This  verb causes the match to end successfully, skipping the remainder       This verb causes the match to end successfully, skipping the  remainder
       of the pattern. However, when it is inside a subpattern that is  called       of  the pattern. However, when it is inside a subpattern that is called
       as  a  subroutine, only that subpattern is ended successfully. Matching       as a subroutine, only that subpattern is ended  successfully.  Matching
       then continues at the outer level. If  (*ACCEPT)  is  inside  capturing       then  continues  at  the  outer level. If (*ACCEPT) is inside capturing
        parentheses, the data so far is captured. For example:         parentheses, the data so far is captured. For example:
   
          A((?:A|B(*ACCEPT)|C)D)           A((?:A|B(*ACCEPT)|C)D)
   
       This  matches  "AB", "AAD", or "ACD"; when it matches "AB", "B" is cap-       This matches "AB", "AAD", or "ACD"; when it matches "AB", "B"  is  cap-
        tured by the outer parentheses.         tured by the outer parentheses.
   
          (*FAIL) or (*F)           (*FAIL) or (*F)
   
       This verb causes a matching failure, forcing backtracking to occur.  It       This  verb causes a matching failure, forcing backtracking to occur. It
       is  equivalent to (?!) but easier to read. The Perl documentation notes       is equivalent to (?!) but easier to read. The Perl documentation  notes
       that it is probably useful only when combined  with  (?{})  or  (??{}).       that  it  is  probably  useful only when combined with (?{}) or (??{}).
       Those  are,  of course, Perl features that are not present in PCRE. The       Those are, of course, Perl features that are not present in  PCRE.  The
       nearest equivalent is the callout feature, as for example in this  pat-       nearest  equivalent is the callout feature, as for example in this pat-
        tern:         tern:
   
          a+(?C)(*FAIL)           a+(?C)(*FAIL)
   
       A  match  with the string "aaaa" always fails, but the callout is taken       A match with the string "aaaa" always fails, but the callout  is  taken
        before each backtrack happens (in this example, 10 times).         before each backtrack happens (in this example, 10 times).
   
    Recording which path was taken     Recording which path was taken
   
       There is one verb whose main purpose  is  to  track  how  a  match  was       There  is  one  verb  whose  main  purpose  is to track how a match was
       arrived  at,  though  it  also  has a secondary use in conjunction with       arrived at, though it also has a  secondary  use  in  conjunction  with
        advancing the match starting point (see (*SKIP) below).         advancing the match starting point (see (*SKIP) below).
   
          (*MARK:NAME) or (*:NAME)           (*MARK:NAME) or (*:NAME)
   
       A name is always  required  with  this  verb.  There  may  be  as  many       A  name  is  always  required  with  this  verb.  There  may be as many
       instances  of  (*MARK) as you like in a pattern, and their names do not       instances of (*MARK) as you like in a pattern, and their names  do  not
        have to be unique.         have to be unique.
   
       When a match succeeds, the name of the last-encountered (*MARK) on  the       When  a match succeeds, the name of the last-encountered (*MARK) on the
       matching  path  is  passed  back  to the caller via the pcre_extra data       matching path is passed back to the caller as described in the  section
       structure, as described in the section on  pcre_extra  in  the  pcreapi       entitled  "Extra  data  for  pcre_exec()" in the pcreapi documentation.
       documentation. Here is an example of pcretest output, where the /K mod-       Here is an example of pcretest output, where the /K  modifier  requests
       ifier requests the retrieval and outputting of (*MARK) data:       the retrieval and outputting of (*MARK) data:
   
            re> /X(*MARK:A)Y|X(*MARK:B)Z/K             re> /X(*MARK:A)Y|X(*MARK:B)Z/K
          data> XY           data> XY
Line 5765  BACKTRACKING CONTROL Line 6295  BACKTRACKING CONTROL
          MK: B           MK: B
   
        The (*MARK) name is tagged with "MK:" in this output, and in this exam-         The (*MARK) name is tagged with "MK:" in this output, and in this exam-
       ple  it indicates which of the two alternatives matched. This is a more       ple it indicates which of the two alternatives matched. This is a  more
       efficient way of obtaining this information than putting each  alterna-       efficient  way of obtaining this information than putting each alterna-
        tive in its own capturing parentheses.         tive in its own capturing parentheses.
   
        If (*MARK) is encountered in a positive assertion, its name is recorded         If (*MARK) is encountered in a positive assertion, its name is recorded
        and passed back if it is the last-encountered. This does not happen for         and passed back if it is the last-encountered. This does not happen for
        negative assertions.         negative assertions.
   
       After  a  partial match or a failed match, the name of the last encoun-       After a partial match or a failed match, the name of the  last  encoun-
        tered (*MARK) in the entire match process is returned. For example:         tered (*MARK) in the entire match process is returned. For example:
   
            re> /X(*MARK:A)Y|X(*MARK:B)Z/K             re> /X(*MARK:A)Y|X(*MARK:B)Z/K
          data> XP           data> XP
          No match, mark = B           No match, mark = B
   
       Note that in this unanchored example the  mark  is  retained  from  the       Note  that  in  this  unanchored  example the mark is retained from the
       match attempt that started at the letter "X". Subsequent match attempts       match attempt that started at the letter "X" in the subject. Subsequent
       starting at "P" and then with an empty string do not get as far as  the       match attempts starting at "P" and then with an empty string do not get
       (*MARK) item, but nevertheless do not reset it.       as far as the (*MARK) item, but nevertheless do not reset it.
   
          If you are interested in  (*MARK)  values  after  failed  matches,  you
          should  probably  set  the PCRE_NO_START_OPTIMIZE option (see above) to
          ensure that the match is always attempted.
   
    Verbs that act after backtracking     Verbs that act after backtracking
   
        The following verbs do nothing when they are encountered. Matching con-         The following verbs do nothing when they are encountered. Matching con-
       tinues with what follows, but if there is no subsequent match,  causing       tinues  with what follows, but if there is no subsequent match, causing
       a  backtrack  to  the  verb, a failure is forced. That is, backtracking       a backtrack to the verb, a failure is  forced.  That  is,  backtracking
       cannot pass to the left of the verb. However, when one of  these  verbs       cannot  pass  to the left of the verb. However, when one of these verbs
       appears  inside  an atomic group, its effect is confined to that group,       appears inside an atomic group, its effect is confined to  that  group,
       because once the group has been matched, there is never any  backtrack-       because  once the group has been matched, there is never any backtrack-
       ing  into  it.  In  this situation, backtracking can "jump back" to the       ing into it. In this situation, backtracking can  "jump  back"  to  the
       left of the entire atomic group. (Remember also, as stated above,  that       left  of the entire atomic group. (Remember also, as stated above, that
        this localization also applies in subroutine calls and assertions.)         this localization also applies in subroutine calls and assertions.)
   
       These  verbs  differ  in exactly what kind of failure occurs when back-       These verbs differ in exactly what kind of failure  occurs  when  back-
        tracking reaches them.         tracking reaches them.
   
          (*COMMIT)           (*COMMIT)
   
       This verb, which may not be followed by a name, causes the whole  match       This  verb, which may not be followed by a name, causes the whole match
        to fail outright if the rest of the pattern does not match. Even if the         to fail outright if the rest of the pattern does not match. Even if the
        pattern is unanchored, no further attempts to find a match by advancing         pattern is unanchored, no further attempts to find a match by advancing
        the  starting  point  take  place.  Once  (*COMMIT)  has  been  passed,         the  starting  point  take  place.  Once  (*COMMIT)  has  been  passed,
       pcre_exec() is committed to finding a match  at  the  current  starting       pcre_exec()  is  committed  to  finding a match at the current starting
        point, or not at all. For example:         point, or not at all. For example:
   
          a+(*COMMIT)b           a+(*COMMIT)b
   
       This  matches  "xxaab" but not "aacaab". It can be thought of as a kind       This matches "xxaab" but not "aacaab". It can be thought of as  a  kind
        of dynamic anchor, or "I've started, so I must finish." The name of the         of dynamic anchor, or "I've started, so I must finish." The name of the
       most  recently passed (*MARK) in the path is passed back when (*COMMIT)       most recently passed (*MARK) in the path is passed back when  (*COMMIT)
        forces a match failure.         forces a match failure.
   
       Note that (*COMMIT) at the start of a pattern is not  the  same  as  an       Note  that  (*COMMIT)  at  the start of a pattern is not the same as an
       anchor,  unless  PCRE's start-of-match optimizations are turned off, as       anchor, unless PCRE's start-of-match optimizations are turned  off,  as
        shown in this pcretest example:         shown in this pcretest example:
   
            re> /(*COMMIT)abc/             re> /(*COMMIT)abc/
Line 5826  BACKTRACKING CONTROL Line 6360  BACKTRACKING CONTROL
          xyzabc\Y           xyzabc\Y
          No match           No match
   
       PCRE knows that any match must start  with  "a",  so  the  optimization       PCRE  knows  that  any  match  must start with "a", so the optimization
       skips  along the subject to "a" before running the first match attempt,       skips along the subject to "a" before running the first match  attempt,
       which succeeds. When the optimization is disabled by the \Y  escape  in       which  succeeds.  When the optimization is disabled by the \Y escape in
        the second subject, the match starts at "x" and so the (*COMMIT) causes         the second subject, the match starts at "x" and so the (*COMMIT) causes
        it to fail without trying any other starting points.         it to fail without trying any other starting points.
   
          (*PRUNE) or (*PRUNE:NAME)           (*PRUNE) or (*PRUNE:NAME)
   
       This verb causes the match to fail at the current starting position  in       This  verb causes the match to fail at the current starting position in
       the  subject  if the rest of the pattern does not match. If the pattern       the subject if the rest of the pattern does not match. If  the  pattern
       is unanchored, the normal "bumpalong"  advance  to  the  next  starting       is  unanchored,  the  normal  "bumpalong"  advance to the next starting
       character  then happens. Backtracking can occur as usual to the left of       character then happens. Backtracking can occur as usual to the left  of
       (*PRUNE), before it is reached,  or  when  matching  to  the  right  of       (*PRUNE),  before  it  is  reached,  or  when  matching to the right of
       (*PRUNE),  but  if  there is no match to the right, backtracking cannot       (*PRUNE), but if there is no match to the  right,  backtracking  cannot
       cross (*PRUNE). In simple cases, the use of (*PRUNE) is just an  alter-       cross  (*PRUNE). In simple cases, the use of (*PRUNE) is just an alter-
       native  to an atomic group or possessive quantifier, but there are some       native to an atomic group or possessive quantifier, but there are  some
        uses of (*PRUNE) that cannot be expressed in any other way.  The behav-         uses of (*PRUNE) that cannot be expressed in any other way.  The behav-
       iour  of  (*PRUNE:NAME)  is  the  same  as  (*MARK:NAME)(*PRUNE). In an       iour of (*PRUNE:NAME)  is  the  same  as  (*MARK:NAME)(*PRUNE).  In  an
        anchored pattern (*PRUNE) has the same effect as (*COMMIT).         anchored pattern (*PRUNE) has the same effect as (*COMMIT).
   
          (*SKIP)           (*SKIP)
   
       This verb, when given without a name, is like (*PRUNE), except that  if       This  verb, when given without a name, is like (*PRUNE), except that if
       the  pattern  is unanchored, the "bumpalong" advance is not to the next       the pattern is unanchored, the "bumpalong" advance is not to  the  next
        character, but to the position in the subject where (*SKIP) was encoun-         character, but to the position in the subject where (*SKIP) was encoun-
       tered.  (*SKIP)  signifies that whatever text was matched leading up to       tered. (*SKIP) signifies that whatever text was matched leading  up  to
        it cannot be part of a successful match. Consider:         it cannot be part of a successful match. Consider:
   
          a+(*SKIP)b           a+(*SKIP)b
   
       If the subject is "aaaac...",  after  the  first  match  attempt  fails       If  the  subject  is  "aaaac...",  after  the first match attempt fails
       (starting  at  the  first  character in the string), the starting point       (starting at the first character in the  string),  the  starting  point
        skips on to start the next attempt at "c". Note that a possessive quan-         skips on to start the next attempt at "c". Note that a possessive quan-
       tifer  does not have the same effect as this example; although it would       tifer does not have the same effect as this example; although it  would
       suppress backtracking  during  the  first  match  attempt,  the  second       suppress  backtracking  during  the  first  match  attempt,  the second
       attempt  would  start at the second character instead of skipping on to       attempt would start at the second character instead of skipping  on  to
        "c".         "c".
   
          (*SKIP:NAME)           (*SKIP:NAME)
   
       When (*SKIP) has an associated name, its behaviour is modified. If  the       When  (*SKIP) has an associated name, its behaviour is modified. If the
        following pattern fails to match, the previous path through the pattern         following pattern fails to match, the previous path through the pattern
       is searched for the most recent (*MARK) that has the same name. If  one       is  searched for the most recent (*MARK) that has the same name. If one
       is  found, the "bumpalong" advance is to the subject position that cor-       is found, the "bumpalong" advance is to the subject position that  cor-
       responds to that (*MARK) instead of to where (*SKIP)  was  encountered.       responds  to  that (*MARK) instead of to where (*SKIP) was encountered.
        If no (*MARK) with a matching name is found, the (*SKIP) is ignored.         If no (*MARK) with a matching name is found, the (*SKIP) is ignored.
   
          (*THEN) or (*THEN:NAME)           (*THEN) or (*THEN:NAME)
   
       This  verb  causes a skip to the next innermost alternative if the rest       This verb causes a skip to the next innermost alternative if  the  rest
       of the pattern does not match. That is, it cancels  pending  backtrack-       of  the  pattern does not match. That is, it cancels pending backtrack-
       ing,  but  only within the current alternative. Its name comes from the       ing, but only within the current alternative. Its name comes  from  the
        observation that it can be used for a pattern-based if-then-else block:         observation that it can be used for a pattern-based if-then-else block:
   
          ( COND1 (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ ) ...           ( COND1 (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ ) ...
   
       If the COND1 pattern matches, FOO is tried (and possibly further  items       If  the COND1 pattern matches, FOO is tried (and possibly further items
       after  the  end  of the group if FOO succeeds); on failure, the matcher       after the end of the group if FOO succeeds); on  failure,  the  matcher
       skips to the second alternative and tries COND2,  without  backtracking       skips  to  the second alternative and tries COND2, without backtracking
       into  COND1.  The  behaviour  of  (*THEN:NAME)  is  exactly the same as       into COND1. The behaviour  of  (*THEN:NAME)  is  exactly  the  same  as
       (*MARK:NAME)(*THEN).  If (*THEN) is not inside an alternation, it  acts       (*MARK:NAME)(*THEN).   If (*THEN) is not inside an alternation, it acts
        like (*PRUNE).         like (*PRUNE).
   
       Note  that  a  subpattern that does not contain a | character is just a       Note that a subpattern that does not contain a | character  is  just  a
       part of the enclosing alternative; it is not a nested alternation  with       part  of the enclosing alternative; it is not a nested alternation with
       only  one alternative. The effect of (*THEN) extends beyond such a sub-       only one alternative. The effect of (*THEN) extends beyond such a  sub-
       pattern to the enclosing alternative. Consider this pattern,  where  A,       pattern  to  the enclosing alternative. Consider this pattern, where A,
        B, etc. are complex pattern fragments that do not contain any | charac-         B, etc. are complex pattern fragments that do not contain any | charac-
        ters at this level:         ters at this level:
   
          A (B(*THEN)C) | D           A (B(*THEN)C) | D
   
       If A and B are matched, but there is a failure in C, matching does  not       If  A and B are matched, but there is a failure in C, matching does not
        backtrack into A; instead it moves to the next alternative, that is, D.         backtrack into A; instead it moves to the next alternative, that is, D.
       However, if the subpattern containing (*THEN) is given an  alternative,       However,  if the subpattern containing (*THEN) is given an alternative,
        it behaves differently:         it behaves differently:
   
          A (B(*THEN)C | (*FAIL)) | D           A (B(*THEN)C | (*FAIL)) | D
   
       The  effect of (*THEN) is now confined to the inner subpattern. After a       The effect of (*THEN) is now confined to the inner subpattern. After  a
        failure in C, matching moves to (*FAIL), which causes the whole subpat-         failure in C, matching moves to (*FAIL), which causes the whole subpat-
       tern  to  fail  because  there are no more alternatives to try. In this       tern to fail because there are no more alternatives  to  try.  In  this
        case, matching does now backtrack into A.         case, matching does now backtrack into A.
   
        Note also that a conditional subpattern is not considered as having two         Note also that a conditional subpattern is not considered as having two
       alternatives,  because  only  one  is  ever used. In other words, the |       alternatives, because only one is ever used.  In  other  words,  the  |
        character in a conditional subpattern has a different meaning. Ignoring         character in a conditional subpattern has a different meaning. Ignoring
        white space, consider:         white space, consider:
   
          ^.*? (?(?=a) a | b(*THEN)c )           ^.*? (?(?=a) a | b(*THEN)c )
   
       If  the  subject  is  "ba", this pattern does not match. Because .*? is       If the subject is "ba", this pattern does not  match.  Because  .*?  is
       ungreedy, it initially matches zero  characters.  The  condition  (?=a)       ungreedy,  it  initially  matches  zero characters. The condition (?=a)
       then  fails,  the  character  "b"  is  matched, but "c" is not. At this       then fails, the character "b" is matched,  but  "c"  is  not.  At  this
       point, matching does not backtrack to .*? as might perhaps be  expected       point,  matching does not backtrack to .*? as might perhaps be expected
       from  the  presence  of  the | character. The conditional subpattern is       from the presence of the | character.  The  conditional  subpattern  is
        part of the single alternative that comprises the whole pattern, and so         part of the single alternative that comprises the whole pattern, and so
       the  match  fails.  (If  there was a backtrack into .*?, allowing it to       the match fails. (If there was a backtrack into  .*?,  allowing  it  to
        match "b", the match would succeed.)         match "b", the match would succeed.)
   
       The verbs just described provide four different "strengths" of  control       The  verbs just described provide four different "strengths" of control
        when subsequent matching fails. (*THEN) is the weakest, carrying on the         when subsequent matching fails. (*THEN) is the weakest, carrying on the
       match at the next alternative. (*PRUNE) comes next, failing  the  match       match  at  the next alternative. (*PRUNE) comes next, failing the match
       at  the  current starting position, but allowing an advance to the next       at the current starting position, but allowing an advance to  the  next
       character (for an unanchored pattern). (*SKIP) is similar, except  that       character  (for an unanchored pattern). (*SKIP) is similar, except that
        the advance may be more than one character. (*COMMIT) is the strongest,         the advance may be more than one character. (*COMMIT) is the strongest,
        causing the entire match to fail.         causing the entire match to fail.
   
Line 5940  BACKTRACKING CONTROL Line 6474  BACKTRACKING CONTROL
   
          (A(*COMMIT)B(*THEN)C|D)           (A(*COMMIT)B(*THEN)C|D)
   
       Once A has matched, PCRE is committed to this  match,  at  the  current       Once  A  has  matched,  PCRE is committed to this match, at the current
       starting  position. If subsequently B matches, but C does not, the nor-       starting position. If subsequently B matches, but C does not, the  nor-
        mal (*THEN) action of trying the next alternative (that is, D) does not         mal (*THEN) action of trying the next alternative (that is, D) does not
        happen because (*COMMIT) overrides.         happen because (*COMMIT) overrides.
   
   
 SEE ALSO  SEE ALSO
   
       pcreapi(3), pcrecallout(3), pcrematching(3), pcresyntax(3), pcre(3).       pcreapi(3), pcrecallout(3),  pcrematching(3),  pcresyntax(3),  pcre(3),
        pcre16(3).
   
   
 AUTHOR  AUTHOR
Line 5960  AUTHOR Line 6495  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 29 November 2011       Last updated: 17 June 2012
       Copyright (c) 1997-2011 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 5976  PCRE REGULAR EXPRESSION SYNTAX SUMMARY Line 6511  PCRE REGULAR EXPRESSION SYNTAX SUMMARY
   
        The  full syntax and semantics of the regular expressions that are sup-         The  full syntax and semantics of the regular expressions that are sup-
        ported by PCRE are described in  the  pcrepattern  documentation.  This         ported by PCRE are described in  the  pcrepattern  documentation.  This
       document contains just a quick-reference summary of the syntax.       document contains a quick-reference summary of the syntax.
   
   
 QUOTING  QUOTING
Line 5990  CHARACTERS Line 6525  CHARACTERS
          \a         alarm, that is, the BEL character (hex 07)           \a         alarm, that is, the BEL character (hex 07)
          \cx        "control-x", where x is any ASCII character           \cx        "control-x", where x is any ASCII character
          \e         escape (hex 1B)           \e         escape (hex 1B)
         \f         formfeed (hex 0C)         \f         form feed (hex 0C)
          \n         newline (hex 0A)           \n         newline (hex 0A)
          \r         carriage return (hex 0D)           \r         carriage return (hex 0D)
          \t         tab (hex 09)           \t         tab (hex 09)
Line 6003  CHARACTER TYPES Line 6538  CHARACTER TYPES
   
          .          any character except newline;           .          any character except newline;
                       in dotall mode, any character whatsoever                        in dotall mode, any character whatsoever
         \C         one byte, even in UTF-8 mode (best avoided)         \C         one data unit, even in UTF mode (best avoided)
          \d         a decimal digit           \d         a decimal digit
          \D         a character that is not a decimal digit           \D         a character that is not a decimal digit
         \h         a horizontal whitespace character         \h         a horizontal white space character
         \H         a character that is not a horizontal whitespace character         \H         a character that is not a horizontal white space character
          \N         a character that is not a newline           \N         a character that is not a newline
          \p{xx}     a character with the xx property           \p{xx}     a character with the xx property
          \P{xx}     a character without the xx property           \P{xx}     a character without the xx property
          \R         a newline sequence           \R         a newline sequence
         \s         a whitespace character         \s         a white space character
         \S         a character that is not a whitespace character         \S         a character that is not a white space character
         \v         a vertical whitespace character         \v         a vertical white space character
         \V         a character that is not a vertical whitespace character         \V         a character that is not a vertical white space character
          \w         a "word" character           \w         a "word" character
          \W         a "non-word" character           \W         a "non-word" character
          \X         an extended Unicode sequence           \X         an extended Unicode sequence
   
        In  PCRE,  by  default, \d, \D, \s, \S, \w, and \W recognize only ASCII         In  PCRE,  by  default, \d, \D, \s, \S, \w, and \W recognize only ASCII
       characters, even in UTF-8 mode. However, this can be changed by setting       characters, even in a UTF mode. However, this can be changed by setting
        the PCRE_UCP option.         the PCRE_UCP option.
   
   
Line 6083  PCRE SPECIAL CATEGORY PROPERTIES FOR \p and \P Line 6618  PCRE SPECIAL CATEGORY PROPERTIES FOR \p and \P
   
 SCRIPT NAMES FOR \p AND \P  SCRIPT NAMES FOR \p AND \P
   
       Arabic, Armenian, Avestan, Balinese, Bamum, Bengali, Bopomofo, Braille,       Arabic,  Armenian,  Avestan, Balinese, Bamum, Batak, Bengali, Bopomofo,
       Buginese, Buhid, Canadian_Aboriginal, Carian, Cham,  Cherokee,  Common,       Brahmi, Braille, Buginese, Buhid, Canadian_Aboriginal, Carian,  Chakma,
       Coptic,   Cuneiform,  Cypriot,  Cyrillic,  Deseret,  Devanagari,  Egyp-       Cham,  Cherokee, Common, Coptic, Cuneiform, Cypriot, Cyrillic, Deseret,
       tian_Hieroglyphs,  Ethiopic,  Georgian,  Glagolitic,   Gothic,   Greek,       Devanagari,  Egyptian_Hieroglyphs,  Ethiopic,   Georgian,   Glagolitic,
       Gujarati,  Gurmukhi,  Han,  Hangul,  Hanunoo,  Hebrew,  Hiragana, Impe-       Gothic,  Greek, Gujarati, Gurmukhi, Han, Hangul, Hanunoo, Hebrew, Hira-
       rial_Aramaic, Inherited, Inscriptional_Pahlavi, Inscriptional_Parthian,       gana,  Imperial_Aramaic,  Inherited,  Inscriptional_Pahlavi,   Inscrip-
       Javanese,  Kaithi, Kannada, Katakana, Kayah_Li, Kharoshthi, Khmer, Lao,       tional_Parthian,   Javanese,   Kaithi,   Kannada,  Katakana,  Kayah_Li,
       Latin,  Lepcha,  Limbu,  Linear_B,  Lisu,  Lycian,  Lydian,  Malayalam,       Kharoshthi, Khmer, Lao, Latin, Lepcha, Limbu, Linear_B,  Lisu,  Lycian,
       Meetei_Mayek,  Mongolian, Myanmar, New_Tai_Lue, Nko, Ogham, Old_Italic,       Lydian,    Malayalam,    Mandaic,    Meetei_Mayek,    Meroitic_Cursive,
       Old_Persian, Old_South_Arabian, Old_Turkic, Ol_Chiki,  Oriya,  Osmanya,       Meroitic_Hieroglyphs,  Miao,  Mongolian,  Myanmar,  New_Tai_Lue,   Nko,
       Phags_Pa,  Phoenician,  Rejang,  Runic, Samaritan, Saurashtra, Shavian,       Ogham,    Old_Italic,   Old_Persian,   Old_South_Arabian,   Old_Turkic,
       Sinhala, Sundanese, Syloti_Nagri, Syriac,  Tagalog,  Tagbanwa,  Tai_Le,       Ol_Chiki, Oriya, Osmanya, Phags_Pa, Phoenician, Rejang, Runic,  Samari-
       Tai_Tham,  Tai_Viet,  Tamil,  Telugu,  Thaana, Thai, Tibetan, Tifinagh,       tan,  Saurashtra,  Sharada,  Shavian, Sinhala, Sora_Sompeng, Sundanese,
       Ugaritic, Vai, Yi.       Syloti_Nagri, Syriac, Tagalog, Tagbanwa,  Tai_Le,  Tai_Tham,  Tai_Viet,
        Takri,  Tamil,  Telugu, Thaana, Thai, Tibetan, Tifinagh, Ugaritic, Vai,
        Yi.
   
   
 CHARACTER CLASSES  CHARACTER CLASSES
Line 6117  CHARACTER CLASSES Line 6654  CHARACTER CLASSES
          lower       lower case letter           lower       lower case letter
          print       printing, including space           print       printing, including space
          punct       printing, excluding alphanumeric           punct       printing, excluding alphanumeric
         space       whitespace         space       white space
          upper       upper case letter           upper       upper case letter
          word        same as \w           word        same as \w
          xdigit      hexadecimal digit           xdigit      hexadecimal digit
Line 6208  OPTION SETTING Line 6745  OPTION SETTING
        one of the newline-setting options with similar syntax:         one of the newline-setting options with similar syntax:
   
          (*NO_START_OPT) no start-match optimization (PCRE_NO_START_OPTIMIZE)           (*NO_START_OPT) no start-match optimization (PCRE_NO_START_OPTIMIZE)
         (*UTF8)         set UTF-8 mode (PCRE_UTF8)         (*UTF8)         set UTF-8 mode: 8-bit library (PCRE_UTF8)
          (*UTF16)        set UTF-16 mode: 16-bit library (PCRE_UTF16)
          (*UCP)          set PCRE_UCP (use Unicode properties for \d etc)           (*UCP)          set PCRE_UCP (use Unicode properties for \d etc)
   
   
Line 6277  BACKTRACKING CONTROL Line 6815  BACKTRACKING CONTROL
   
          (*ACCEPT)       force successful match           (*ACCEPT)       force successful match
          (*FAIL)         force backtrack; synonym (*F)           (*FAIL)         force backtrack; synonym (*F)
            (*MARK:NAME)    set name to be passed back; synonym (*:NAME)
   
        The  following  act only when a subsequent match failure causes a back-         The  following  act only when a subsequent match failure causes a back-
        track to reach them. They all force a match failure, but they differ in         track to reach them. They all force a match failure, but they differ in
Line 6285  BACKTRACKING CONTROL Line 6824  BACKTRACKING CONTROL
   
          (*COMMIT)       overall failure, no advance of starting point           (*COMMIT)       overall failure, no advance of starting point
          (*PRUNE)        advance to next starting character           (*PRUNE)        advance to next starting character
         (*SKIP)         advance start to current matching position         (*PRUNE:NAME)   equivalent to (*MARK:NAME)(*PRUNE)
          (*SKIP)         advance to current matching position
          (*SKIP:NAME)    advance to position corresponding to an earlier
                          (*MARK:NAME); if not found, the (*SKIP) is ignored
          (*THEN)         local failure, backtrack to next alternation           (*THEN)         local failure, backtrack to next alternation
            (*THEN:NAME)    equivalent to (*MARK:NAME)(*THEN)
   
   
 NEWLINE CONVENTIONS  NEWLINE CONVENTIONS
   
        These are recognized only at the very start of the pattern or  after  a         These are recognized only at the very start of the pattern or  after  a
       (*BSR_...) or (*UTF8) or (*UCP) option.       (*BSR_...), (*UTF8), (*UTF16) or (*UCP) option.
   
          (*CR)           carriage return only           (*CR)           carriage return only
          (*LF)           linefeed only           (*LF)           linefeed only
Line 6304  NEWLINE CONVENTIONS Line 6847  NEWLINE CONVENTIONS
 WHAT \R MATCHES  WHAT \R MATCHES
   
        These  are  recognized only at the very start of the pattern or after a         These  are  recognized only at the very start of the pattern or after a
       (*...) option that sets the newline convention or UTF-8 or UCP mode.       (*...) option that sets the newline convention or a UTF or UCP mode.
   
          (*BSR_ANYCRLF)  CR, LF, or CRLF           (*BSR_ANYCRLF)  CR, LF, or CRLF
          (*BSR_UNICODE)  any Unicode newline sequence           (*BSR_UNICODE)  any Unicode newline sequence
Line 6330  AUTHOR Line 6873  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 21 November 2010       Last updated: 10 January 2012
       Copyright (c) 1997-2010 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 6342  NAME Line 6885  NAME
        PCRE - Perl-compatible regular expressions         PCRE - Perl-compatible regular expressions
   
   
UTF-8 AND UNICODE PROPERTY SUPPORTUTF-8, UTF-16, AND UNICODE PROPERTY SUPPORT
   
       In  order  process  UTF-8 strings, you must build PCRE to include UTF-8       From Release 8.30, in addition to its previous UTF-8 support, PCRE also
       support in the code, and, in addition,  you  must  call  pcre_compile()       supports UTF-16 by means of a separate  16-bit  library.  This  can  be
       with  the  PCRE_UTF8  option  flag,  or the pattern must start with the       built as well as, or instead of, the 8-bit library.
       sequence (*UTF8). When either of these is the case,  both  the  pattern 
       and  any  subject  strings  that  are matched against it are treated as 
       UTF-8 strings instead of strings of 1-byte characters.  PCRE  does  not 
       support any other formats (in particular, it does not support UTF-16). 
   
       If  you compile PCRE with UTF-8 support, but do not use it at run time,
 UTF-8 SUPPORT
 
        In  order  process  UTF-8  strings, you must build PCRE's 8-bit library
        with UTF support, and, in addition, you must call  pcre_compile()  with
        the  PCRE_UTF8 option flag, or the pattern must start with the sequence
        (*UTF8). When either of these is the case, both  the  pattern  and  any
        subject  strings  that  are  matched  against  it  are treated as UTF-8
        strings instead of strings of 1-byte characters.
 
 
 UTF-16 SUPPORT
 
        In order process UTF-16 strings, you must build PCRE's  16-bit  library
        with UTF support, and, in addition, you must call pcre16_compile() with
        the PCRE_UTF16 option flag, or the pattern must start with the sequence
        (*UTF16).  When  either  of these is the case, both the pattern and any
        subject strings that are matched  against  it  are  treated  as  UTF-16
        strings instead of strings of 16-bit characters.
 
 
 UTF SUPPORT OVERHEAD
 
        If  you  compile  PCRE with UTF support, but do not use it at run time,
        the library will be a bit bigger, but the additional run time  overhead         the library will be a bit bigger, but the additional run time  overhead
       is limited to testing the PCRE_UTF8 flag occasionally, so should not be       is limited to testing the PCRE_UTF8/16 flag occasionally, so should not
       very big.       be very big.
   
   
   UNICODE PROPERTY SUPPORT
   
        If PCRE is built with Unicode character property support (which implies         If PCRE is built with Unicode character property support (which implies
       UTF-8  support),  the  escape sequences \p{..}, \P{..}, and \X are sup-       UTF  support), the escape sequences \p{..}, \P{..}, and \X can be used.
       ported.  The available properties that can be tested are limited to the       The available properties that can be tested are limited to the  general
       general  category  properties such as Lu for an upper case letter or Nd       category  properties  such  as  Lu for an upper case letter or Nd for a
       for a decimal number, the Unicode script names such as Arabic  or  Han,       decimal number, the Unicode script names such as Arabic or Han, and the
       and  the  derived  properties  Any  and L&. A full list is given in the       derived  properties Any and L&. A full list is given in the pcrepattern
       pcrepattern documentation. Only the short names for properties are sup-       documentation. Only the short names for properties are  supported.  For
       ported.  For example, \p{L} matches a letter. Its Perl synonym, \p{Let-       example,  \p{L}  matches a letter. Its Perl synonym, \p{Letter}, is not
       ter}, is not supported.  Furthermore,  in  Perl,  many  properties  may       supported.  Furthermore, in Perl, many  properties  may  optionally  be
       optionally  be  prefixed by "Is", for compatibility with Perl 5.6. PCRE       prefixed  by  "Is", for compatibility with Perl 5.6. PCRE does not sup-
       does not support this.       port this.
   
    Validity of UTF-8 strings     Validity of UTF-8 strings
   
       When you set the PCRE_UTF8 flag, the strings  passed  as  patterns  and       When you set the PCRE_UTF8 flag, the byte strings  passed  as  patterns
       subjects are (by default) checked for validity on entry to the relevant       and subjects are (by default) checked for validity on entry to the rel-
       functions. From release 7.3 of PCRE, the check is according  the  rules       evant functions. The entire string is checked before any other process-
       of  RFC  3629, which are themselves derived from the Unicode specifica-       ing  takes  place. From release 7.3 of PCRE, the check is according the
       tion. Earlier releases of PCRE followed the rules of  RFC  2279,  which       rules of RFC 3629, which are themselves derived from the Unicode speci-
       allows  the  full range of 31-bit values (0 to 0x7FFFFFFF). The current       fication.  Earlier  releases  of  PCRE  followed the rules of RFC 2279,
       check allows only values in the range U+0 to U+10FFFF, excluding U+D800       which allows the full range of 31-bit values  (0  to  0x7FFFFFFF).  The
       to U+DFFF.       current  check allows only values in the range U+0 to U+10FFFF, exclud-
        ing U+D800 to U+DFFF.
   
       The  excluded  code  points are the "Low Surrogate Area" of Unicode, of       The excluded code points are the "Surrogate Area" of Unicode. They  are
       which the Unicode Standard says this: "The Low Surrogate Area does  not       reserved  for  use  by  UTF-16,  where they are used in pairs to encode
       contain  any  character  assignments,  consequently  no  character code       codepoints with values greater than 0xFFFF. The code  points  that  are
       charts or namelists are provided for this area. Surrogates are reserved       encoded by UTF-16 pairs are available independently in the UTF-8 encod-
       for  use  with  UTF-16 and then must be used in pairs." The code points       ing. (In other words, the whole surrogate thing is a fudge  for  UTF-16
       that are encoded by UTF-16 pairs  are  available  as  independent  code       which unfortunately messes up UTF-8.)
       points  in  the  UTF-8  encoding.  (In other words, the whole surrogate 
       thing is a fudge for UTF-16 which unfortunately messes up UTF-8.) 
   
        If an invalid UTF-8 string is passed to PCRE, an error return is given.         If an invalid UTF-8 string is passed to PCRE, an error return is given.
       At  compile  time, the only additional information is the offset to the       At compile time, the only additional information is the offset  to  the
       first byte of the failing character. The runtime functions  pcre_exec()       first byte of the failing character. The run-time functions pcre_exec()
       and  pcre_dfa_exec() also pass back this information, as well as a more       and pcre_dfa_exec() also pass back this information, as well as a  more
       detailed reason code if the caller has provided memory in which  to  do       detailed  reason  code if the caller has provided memory in which to do
        this.         this.
   
       In  some  situations, you may already know that your strings are valid,       In some situations, you may already know that your strings  are  valid,
       and therefore want to skip these checks in  order  to  improve  perfor-       and  therefore  want  to  skip these checks in order to improve perfor-
       mance. If you set the PCRE_NO_UTF8_CHECK flag at compile time or at run       mance, for example in the case of a long subject string that  is  being
       time, PCRE assumes that the pattern or subject  it  is  given  (respec-       scanned   repeatedly   with   different   patterns.   If  you  set  the
       tively)  contains  only  valid  UTF-8  codes. In this case, it does not       PCRE_NO_UTF8_CHECK flag at compile time or at run  time,  PCRE  assumes
       diagnose an invalid UTF-8 string.       that  the  pattern  or subject it is given (respectively) contains only
        valid UTF-8 codes. In this case, it does not diagnose an invalid  UTF-8
        string.
   
       If you pass an invalid UTF-8 string  when  PCRE_NO_UTF8_CHECK  is  set,       If  you  pass  an  invalid UTF-8 string when PCRE_NO_UTF8_CHECK is set,
       what  happens  depends on why the string is invalid. If the string con-       what happens depends on why the string is invalid. If the  string  con-
        forms to the "old" definition of UTF-8 (RFC 2279), it is processed as a         forms to the "old" definition of UTF-8 (RFC 2279), it is processed as a
       string  of  characters  in the range 0 to 0x7FFFFFFF by pcre_dfa_exec()       string of characters in the range 0 to  0x7FFFFFFF  by  pcre_dfa_exec()
       and the interpreted version of pcre_exec(). In other words, apart  from       and  the interpreted version of pcre_exec(). In other words, apart from
       the  initial validity test, these functions (when in UTF-8 mode) handle       the initial validity test, these functions (when in UTF-8 mode)  handle
       strings according to the more liberal rules of RFC 2279.  However,  the       strings  according  to the more liberal rules of RFC 2279. However, the
        just-in-time (JIT) optimization for pcre_exec() supports only RFC 3629.         just-in-time (JIT) optimization for pcre_exec() supports only RFC 3629.
       If you are using JIT optimization, or if the string does not even  con-       If  you are using JIT optimization, or if the string does not even con-
        form to RFC 2279, the result is undefined. Your program may crash.         form to RFC 2279, the result is undefined. Your program may crash.
   
       If  you  want  to  process  strings  of  values  in the full range 0 to       If you want to process strings  of  values  in  the  full  range  0  to
       0x7FFFFFFF, encoded in a UTF-8-like manner as per the old RFC, you  can       0x7FFFFFFF,  encoded in a UTF-8-like manner as per the old RFC, you can
        set PCRE_NO_UTF8_CHECK to bypass the more restrictive test. However, in         set PCRE_NO_UTF8_CHECK to bypass the more restrictive test. However, in
       this situation, you will have to apply your  own  validity  check,  and       this  situation,  you  will  have to apply your own validity check, and
        avoid the use of JIT optimization.         avoid the use of JIT optimization.
   
   General comments about UTF-8 mode   Validity of UTF-16 strings
   
       1.  An  unbraced  hexadecimal  escape sequence (such as \xb3) matches a       When you set the PCRE_UTF16 flag, the strings of 16-bit data units that
       two-byte UTF-8 character if the value is greater than 127.       are passed as patterns and subjects are (by default) checked for valid-
        ity on entry to the relevant functions. Values other than those in  the
        surrogate range U+D800 to U+DFFF are independent code points. Values in
        the surrogate range must be used in pairs in the correct manner.
   
       2. Octal numbers up to \777 are recognized, and  match  two-byte  UTF-8       If an invalid UTF-16 string is passed  to  PCRE,  an  error  return  is
       characters for values greater than \177.       given.  At  compile time, the only additional information is the offset
        to the first data unit of the failing character. The run-time functions
        pcre16_exec() and pcre16_dfa_exec() also pass back this information, as
        well as a more detailed reason code if the caller has  provided  memory
        in which to do this.
   
       3.  Repeat quantifiers apply to complete UTF-8 characters, not to indi-       In  some  situations, you may already know that your strings are valid,
       vidual bytes, for example: \x{100}{3}.       and therefore want to skip these checks in  order  to  improve  perfor-
        mance.  If  you  set the PCRE_NO_UTF16_CHECK flag at compile time or at
        run time, PCRE assumes that the pattern or subject it is given (respec-
        tively) contains only valid UTF-16 sequences. In this case, it does not
        diagnose an invalid UTF-16 string.
   
       4. The dot metacharacter matches one UTF-8 character instead of a  sin-   General comments about UTF modes
       gle byte. 
   
          1. Codepoints less than 256  can  be  specified  by  either  braced  or
          unbraced  hexadecimal  escape  sequences (for example, \x{b3} or \xb3).
          Larger values have to use braced sequences.
   
          2. Octal numbers up to \777 are recognized, and  in  UTF-8  mode,  they
          match two-byte characters for values greater than \177.
   
          3. Repeat quantifiers apply to complete UTF characters, not to individ-
          ual data units, for example: \x{100}{3}.
   
          4. The dot metacharacter matches one UTF character instead of a  single
          data unit.
   
        5.  The  escape sequence \C can be used to match a single byte in UTF-8         5.  The  escape sequence \C can be used to match a single byte in UTF-8
       mode, but its use can lead to some strange effects because it breaks up       mode, or a single 16-bit data unit in UTF-16 mode, but its use can lead
       multibyte characters (see the description of \C in the pcrepattern doc-       to some strange effects because it breaks up multi-unit characters (see
       umentation). The use of \C is not supported in the alternative matching       the description of \C in the pcrepattern documentation). The use of  \C
       function  pcre_dfa_exec(), nor is it supported in UTF-8 mode by the JIT       is    not    supported    in    the   alternative   matching   function
       optimization of pcre_exec(). If JIT optimization  is  requested  for  a       pcre[16]_dfa_exec(), nor is it supported in UTF mode by the  JIT  opti-
       UTF-8  pattern that contains \C, it will not succeed, and so the match-       mization of pcre[16]_exec(). If JIT optimization is requested for a UTF
       ing will be carried out by the normal interpretive function.       pattern that contains \C, it will not succeed, and so the matching will
        be carried out by the normal interpretive function.
   
       6. The character escapes \b, \B, \d, \D, \s, \S, \w, and  \W  correctly       6.  The  character escapes \b, \B, \d, \D, \s, \S, \w, and \W correctly
        test characters of any code value, but, by default, the characters that         test characters of any code value, but, by default, the characters that
       PCRE recognizes as digits, spaces, or word characters remain  the  same       PCRE  recognizes  as digits, spaces, or word characters remain the same
       set  as  before,  all with values less than 256. This remains true even       set as in non-UTF mode, all with values less  than  256.  This  remains
       when PCRE is built to include Unicode property support, because  to  do       true  even  when  PCRE  is  built  to include Unicode property support,
       otherwise would slow down PCRE in many common cases. Note in particular       because to do otherwise would slow down PCRE in many common cases. Note
       that this applies to \b and \B, because they are defined in terms of \w       in  particular that this applies to \b and \B, because they are defined
       and  \W. If you really want to test for a wider sense of, say, "digit",       in terms of \w and \W. If you really want to test for a wider sense of,
       you can use explicit Unicode property tests such  as  \p{Nd}.  Alterna-       say,  "digit",  you  can  use  explicit  Unicode property tests such as
       tively,  if  you  set  the  PCRE_UCP option, the way that the character       \p{Nd}. Alternatively, if you set the PCRE_UCP option, the way that the
       escapes work is changed so that Unicode properties are used  to  deter-       character  escapes  work is changed so that Unicode properties are used
       mine  which  characters match. There are more details in the section on       to determine which characters match. There are more details in the sec-
       generic character types in the pcrepattern documentation.       tion on generic character types in the pcrepattern documentation.
   
       7. Similarly, characters that match the POSIX named  character  classes       7.  Similarly,  characters that match the POSIX named characte       7.  Similarly,  characters that match the POSIX named characte
        are all low-valued characters, unless the PCRE_UCP option is set.         are all low-valued characters, unless the PCRE_UCP option is set.
   
       8.  However,  the  horizontal  and vertical whitespace matching escapes       8. However, the horizontal and vertical white  space  matching  escapes
       (\h, \H, \v, and \V) do match all the appropriate  Unicode  characters,       (\h,  \H,  \v, and \V) do match all the appropriate Unicode characters,
        whether or not PCRE_UCP is set.         whether or not PCRE_UCP is set.
   
       9.  Case-insensitive  matching  applies only to characters whose values       9. Case-insensitive matching applies only to  characters  whose  values
       are less than 128, unless PCRE is built with Unicode property  support.       are  less than 128, unless PCRE is built with Unicode property support.
       Even  when  Unicode  property support is available, PCRE still uses its       Even when Unicode property support is available, PCRE  still  uses  its
       own character tables when checking the case of  low-valued  characters,       own  character  tables when checking the case of low-valued characters,
       so  as not to degrade performance.  The Unicode property information is       so as not to degrade performance.  The Unicode property information  is
        used only for characters with higher values. Furthermore, PCRE supports         used only for characters with higher values. Furthermore, PCRE supports
       case-insensitive  matching  only  when  there  is  a one-to-one mapping       case-insensitive matching only  when  there  is  a  one-to-one  mapping
       between a letter's cases. There are a small number of many-to-one  map-       between  a letter's cases. There are a small number of many-to-one map-
        pings in Unicode; these are not supported by PCRE.         pings in Unicode; these are not supported by PCRE.
   
   
Line 6484  AUTHOR Line 7074  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 19 October 2011       Last updated: 14 April 2012
       Copyright (c) 1997-2011 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 6502  PCRE JUST-IN-TIME COMPILER SUPPORT Line 7092  PCRE JUST-IN-TIME COMPILER SUPPORT
        speed up pattern matching. However, it comes at the cost of extra  pro-         speed up pattern matching. However, it comes at the cost of extra  pro-
        cessing before the match is performed. Therefore, it is of most benefit         cessing before the match is performed. Therefore, it is of most benefit
        when the same pattern is going to be matched many times. This does  not         when the same pattern is going to be matched many times. This does  not
       necessarily  mean  many  calls  of  pcre_exec();  if the pattern is not       necessarily  mean  many calls of a matching function; if the pattern is
       anchored, matching attempts may take place many times at various  posi-       not anchored, matching attempts may take place many  times  at  various
       tions  in  the  subject,  even for a single call to pcre_exec(). If the       positions  in  the  subject, even for a single call.  Therefore, if the
        subject string is very long, it may still pay to use  JIT  for  one-off         subject string is very long, it may still pay to use  JIT  for  one-off
        matches.         matches.
   
       JIT   support  applies  only  to  the  traditional  matching  function,       JIT  support  applies  only to the traditional Perl-compatible matching
       pcre_exec(). It does not apply when pcre_dfa_exec() is being used.  The       function.  It does not apply when the DFA matching  function  is  being
       code for this support was written by Zoltan Herczeg.       used. The code for this support was written by Zoltan Herczeg.
   
   
   8-BIT and 16-BIT SUPPORT
   
          JIT  support is available for both the 8-bit and 16-bit PCRE libraries.
          To  keep  this  documentation  simple,  only  the  8-bit  interface  is
          described in what follows. If you are using the 16-bit library, substi-
          tute  the  16-bit  functions  and  16-bit  structures   (for   example,
          pcre16_jit_stack instead of pcre_jit_stack).
   
   
 AVAILABILITY OF JIT SUPPORT  AVAILABILITY OF JIT SUPPORT
   
        JIT  support  is  an  optional  feature of PCRE. The "configure" option         JIT  support  is  an  optional  feature of PCRE. The "configure" option
Line 6523  AVAILABILITY OF JIT SUPPORT Line 7122  AVAILABILITY OF JIT SUPPORT
          ARM v5, v7, and Thumb2           ARM v5, v7, and Thumb2
          Intel x86 32-bit and 64-bit           Intel x86 32-bit and 64-bit
          MIPS 32-bit           MIPS 32-bit
         Power PC 32-bit and 64-bit (experimental)         Power PC 32-bit and 64-bit
   
       The Power PC support is designated as experimental because it  has  not       If --enable-jit is set on an unsupported platform, compilation fails.
       been  fully  tested. If --enable-jit is set on an unsupported platform, 
       compilation fails. 
   
        A program that is linked with PCRE 8.20 or later can tell if  JIT  sup-         A program that is linked with PCRE 8.20 or later can tell if  JIT  sup-
        port  is  available  by  calling pcre_config() with the PCRE_CONFIG_JIT         port  is  available  by  calling pcre_config() with the PCRE_CONFIG_JIT
        option. The result is 1 when JIT is available, and  0  otherwise.  How-         option. The result is 1 when JIT is available, and  0  otherwise.  How-
        ever, a simple program does not need to check this in order to use JIT.         ever, a simple program does not need to check this in order to use JIT.
       The API is implemented in a way that falls back to  the  ordinary  PCRE       The API is implemented in a way that falls  back  to  the  interpretive
        code if JIT is not available.         code if JIT is not available.
   
        If  your program may sometimes be linked with versions of PCRE that are         If  your program may sometimes be linked with versions of PCRE that are
Line 6552  SIMPLE USE OF JIT Line 7149  SIMPLE USE OF JIT
              pcre_exec().               pcre_exec().
   
          (2) Use pcre_free_study() to free the pcre_extra block when it is           (2) Use pcre_free_study() to free the pcre_extra block when it is
             no longer needed instead of just freeing it yourself. This             no longer needed, instead of just freeing it yourself. This
              ensures that any JIT data is also freed.               ensures that any JIT data is also freed.
   
        For  a  program  that may be linked with pre-8.20 versions of PCRE, you         For  a  program  that may be linked with pre-8.20 versions of PCRE, you
Line 6571  SIMPLE USE OF JIT Line 7168  SIMPLE USE OF JIT
              pcre_free(study_ptr);               pcre_free(study_ptr);
          #endif           #endif
   
       In  some circumstances you may need to call additional functions. These       PCRE_STUDY_JIT_COMPILE  requests  the JIT compiler to generate code for
       are described in the  section  entitled  "Controlling  the  JIT  stack"       complete matches.  If  you  want  to  run  partial  matches  using  the
        PCRE_PARTIAL_HARD  or  PCRE_PARTIAL_SOFT  options  of  pcre_exec(), you
        should set one or both of the following  options  in  addition  to,  or
        instead of, PCRE_STUDY_JIT_COMPILE when you call pcre_study():
 
          PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE
          PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE
 
        The  JIT  compiler  generates  different optimized code for each of the
        three modes (normal, soft partial, hard partial). When  pcre_exec()  is
        called,  the appropriate code is run if it is available. Otherwise, the
        pattern is matched using interpretive code.
 
        In some circumstances you may need to call additional functions.  These
        are  described  in  the  section  entitled  "Controlling the JIT stack"
        below.         below.
   
       If JIT support is not available, PCRE_STUDY_JIT_COMPILE is ignored, and       If JIT  support  is  not  available,  PCRE_STUDY_JIT_COMPILE  etc.  are
       no JIT data is set up. Otherwise, the compiled pattern is passed to the       ignored, and no JIT data is created. Otherwise, the compiled pattern is
       JIT  compiler,  which  turns  it  into  machine code that executes much       passed to the JIT compiler, which turns it into machine code that  exe-
       faster than the normal interpretive code. When pcre_exec() is passed  a       cutes  much  faster than the normal interpretive code. When pcre_exec()
       pcre_extra  block  containing  a  pointer  to  JIT  code, it obeys that       is passed a pcre_extra block containing a pointer to JIT  code  of  the
       instead of the normal code. The result is identical, but the code  runs       appropriate  mode  (normal  or  hard/soft  partial), it obeys that code
       much faster.       instead of running the interpreter. The result is  identical,  but  the
        compiled JIT code runs much faster.
   
        There  are some pcre_exec() options that are not supported for JIT exe-         There  are some pcre_exec() options that are not supported for JIT exe-
        cution. There are also some  pattern  items  that  JIT  cannot  handle.         cution. There are also some  pattern  items  that  JIT  cannot  handle.
        Details  are  given below. In both cases, execution automatically falls         Details  are  given below. In both cases, execution automatically falls
       back to the interpretive code.       back to the interpretive code. If you want  to  know  whether  JIT  was
        actually  used  for  a  particular  match, you should arrange for a JIT
        callback function to be set up as described  in  the  section  entitled
        "Controlling  the JIT stack" below, even if you do not need to supply a
        non-default JIT stack. Such a callback function is called whenever  JIT
        code  is about to be obeyed. If the execution options are not right for
        JIT execution, the callback function is not obeyed.
   
        If the JIT compiler finds an unsupported item, no JIT  data  is  gener-         If the JIT compiler finds an unsupported item, no JIT  data  is  gener-
        ated.  You  can find out if JIT execution is available after studying a         ated.  You  can find out if JIT execution is available after studying a
        pattern by calling pcre_fullinfo() with  the  PCRE_INFO_JIT  option.  A         pattern by calling pcre_fullinfo() with  the  PCRE_INFO_JIT  option.  A
        result  of  1  means that JIT compilation was successful. A result of 0         result  of  1  means that JIT compilation was successful. A result of 0
        means that JIT support is not available, or the pattern was not studied         means that JIT support is not available, or the pattern was not studied
       with PCRE_STUDY_JIT_COMPILE, or the JIT compiler was not able to handle       with  PCRE_STUDY_JIT_COMPILE  etc., or the JIT compiler was not able to
       the pattern.       handle the pattern.
   
        Once a pattern has been studied, with or without JIT, it can be used as         Once a pattern has been studied, with or without JIT, it can be used as
        many times as you like for matching different subject strings.         many times as you like for matching different subject strings.
Line 6603  SIMPLE USE OF JIT Line 7221  SIMPLE USE OF JIT
 UNSUPPORTED OPTIONS AND PATTERN ITEMS  UNSUPPORTED OPTIONS AND PATTERN ITEMS
   
        The  only  pcre_exec() options that are supported for JIT execution are         The  only  pcre_exec() options that are supported for JIT execution are
       PCRE_NO_UTF8_CHECK,  PCRE_NOTBOL,   PCRE_NOTEOL,   PCRE_NOTEMPTY,   and       PCRE_NO_UTF8_CHECK,  PCRE_NO_UTF16_CHECK,   PCRE_NOTBOL,   PCRE_NOTEOL,
       PCRE_NOTEMPTY_ATSTART.  Note in particular that partial matching is not       PCRE_NOTEMPTY,  PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and PCRE_PAR-
       supported.       TIAL_SOFT.
   
        The unsupported pattern items are:         The unsupported pattern items are:
   
          \C             match a single byte; not supported in UTF-8 mode           \C             match a single byte; not supported in UTF-8 mode
          (?Cn)          callouts           (?Cn)          callouts
         (*COMMIT)      )         (*PRUNE)       )
         (*MARK)        )         (*SKIP)        ) backtracking control verbs
         (*PRUNE)       ) the backtracking control verbs 
         (*SKIP)        ) 
          (*THEN)        )           (*THEN)        )
   
        Support for some of these may be added in future.         Support for some of these may be added in future.
Line 6681  CONTROLLING THE JIT STACK Line 7297  CONTROLLING THE JIT STACK
          void               *data           void               *data
   
        The extra argument must be  the  result  of  studying  a  pattern  with         The extra argument must be  the  result  of  studying  a  pattern  with
       PCRE_STUDY_JIT_COMPILE.  There  are  three  cases for the values of the       PCRE_STUDY_JIT_COMPILE etc. There are three cases for the values of the
        other two options:         other two options:
   
          (1) If callback is NULL and data is NULL, an internal 32K block           (1) If callback is NULL and data is NULL, an internal 32K block
Line 6690  CONTROLLING THE JIT STACK Line 7306  CONTROLLING THE JIT STACK
          (2) If callback is NULL and data is not NULL, data must be           (2) If callback is NULL and data is not NULL, data must be
              a valid JIT stack, the result of calling pcre_jit_stack_alloc().               a valid JIT stack, the result of calling pcre_jit_stack_alloc().
   
         (3) If callback not NULL, it must point to a function that is called         (3) If callback is not NULL, it must point to a function that is
             with data as an argument at the start of matching, in order to             called with data as an argument at the start of matching, in
             set up a JIT stack. If the result is NULL, the internal 32K stack             order to set up a JIT stack. If the return from the callback
             is used; otherwise the return value must be a valid JIT stack,             function is NULL, the internal 32K stack is used; otherwise the
             the result of calling pcre_jit_stack_alloc().             return value must be a valid JIT stack, the result of calling
              pcre_jit_stack_alloc().
   
       You may safely assign the same JIT stack to more than one  pattern,  as       A callback function is obeyed whenever JIT code is about to be run;  it
       long as they are all matched sequentially in the same thread. In a mul-       is  not  obeyed when pcre_exec() is called with options that are incom-
       tithread application, each thread must use its own JIT stack.       patible for JIT execution. A callback function can therefore be used to
        determine  whether  a  match  operation  was  executed by JIT or by the
        interpreter.
   
       Strictly speaking, even more is allowed. You can assign the same  stack       You may safely use the same JIT stack for more than one pattern (either
       to  any number of patterns as long as they are not used for matching by       by  assigning directly or by callback), as long as the patterns are all
       multiple threads at the same time. For example, you can assign the same       matched sequentially in the same thread. In a multithread  application,
       stack  to all compiled patterns, and use a global mutex in the callback       if  you  do not specify a JIT stack, or if you assign or pass back NULL
       to wait until the stack is available for use. However, this is an inef-       from a callback, that is thread-safe, because each thread has  its  own
       ficient solution, and not recommended.       machine  stack.  However,  if  you  assign  or pass back a non-NULL JIT
        stack, this must be a different stack  for  each  thread  so  that  the
        application is thread-safe.
   
       This  is  a  suggestion  for  how a typical multithreaded program might       Strictly  speaking,  even more is allowed. You can assign the same non-
       operate:       NULL stack to any number of patterns as long as they are not  used  for
        matching  by  multiple  threads  at the same time. For example, you can
        assign the same stack to all compiled patterns, and use a global  mutex
        in  the callback to wait until the stack is available for use. However,
        this is an inefficient solution, and not recommended.
   
          This is a suggestion for how a multithreaded program that needs to  set
          up non-default JIT stacks might operate:
   
          During thread initalization           During thread initalization
            thread_local_var = pcre_jit_stack_alloc(...)             thread_local_var = pcre_jit_stack_alloc(...)
   
Line 6719  CONTROLLING THE JIT STACK Line 7347  CONTROLLING THE JIT STACK
          Use a one-line callback function           Use a one-line callback function
            return thread_local_var             return thread_local_var
   
       All the functions described in this section do nothing if  JIT  is  not       All  the  functions  described in this section do nothing if JIT is not
       available,  and  pcre_assign_jit_stack()  does nothing unless the extra       available, and pcre_assign_jit_stack() does nothing  unless  the  extra
       argument is non-NULL and points to  a  pcre_extra  block  that  is  the       argument  is  non-NULL  and  points  to  a pcre_extra block that is the
       result of a successful study with PCRE_STUDY_JIT_COMPILE.       result of a successful study with PCRE_STUDY_JIT_COMPILE etc.
   
   
 JIT STACK FAQ  JIT STACK FAQ
   
        (1) Why do we need JIT stacks?         (1) Why do we need JIT stacks?
   
       PCRE  (and JIT) is a recursive, depth-first engine, so it needs a stack       PCRE (and JIT) is a recursive, depth-first engine, so it needs a  stack
       where the local data of the current node is pushed before checking  its       where  the local data of the current node is pushed before checking its
        child nodes.  Allocating real machine stack on some platforms is diffi-         child nodes.  Allocating real machine stack on some platforms is diffi-
        cult. For example, the stack chain needs to be updated every time if we         cult. For example, the stack chain needs to be updated every time if we
       extend  the  stack  on  PowerPC.  Although it is possible, its updating       extend the stack on PowerPC.  Although it  is  possible,  its  updating
        time overhead decreases performance. So we do the recursion in memory.         time overhead decreases performance. So we do the recursion in memory.
   
        (2) Why don't we simply allocate blocks of memory with malloc()?         (2) Why don't we simply allocate blocks of memory with malloc()?
   
       Modern operating systems have a  nice  feature:  they  can  reserve  an       Modern  operating  systems  have  a  nice  feature: they can reserve an
        address space instead of allocating memory. We can safely allocate mem-         address space instead of allocating memory. We can safely allocate mem-
       ory pages inside this address space, so the stack  could  grow  without       ory  pages  inside  this address space, so the stack cou       ory  pages  inside  this address space, so the stack cou
        moving memory data (this is important because of pointers). Thus we can         moving memory data (this is important because of pointers). Thus we can
       allocate 1M address space, and use only a single memory  page  (usually       allocate  1M  address space, and use only a single memory page (usually
       4K)  if  that is enough. However, we can still grow up to 1M anytime if       4K) if that is enough. However, we can still grow up to 1M  anytime  if
        needed.         needed.
   
        (3) Who "owns" a JIT stack?         (3) Who "owns" a JIT stack?
   
        The owner of the stack is the user program, not the JIT studied pattern         The owner of the stack is the user program, not the JIT studied pattern
       or  anything else. The user program must ensure that if a stack is used       or anything else. The user program must ensure that if a stack is  used
       by pcre_exec(), (that is, it is assigned to the pattern currently  run-       by  pcre_exec(), (that is, it is assigned to the pattern currently run-
        ning), that stack must not be used by any other threads (to avoid over-         ning), that stack must not be used by any other threads (to avoid over-
        writing the same memory area). The best practice for multithreaded pro-         writing the same memory area). The best practice for multithreaded pro-
       grams  is  to  allocate  a stack for each thread, and return this stack       grams is to allocate a stack for each thread,  and  return  this  stack
        through the JIT callback function.         through the JIT callback function.
   
        (4) When should a JIT stack be freed?         (4) When should a JIT stack be freed?
   
        You can free a JIT stack at any time, as long as it will not be used by         You can free a JIT stack at any time, as long as it will not be used by
       pcre_exec()  again.  When  you  assign  the  stack to a pattern, only a       pcre_exec() again. When you assign the  stack  to  a  pattern,  only  a
       pointer is set. There is no reference counting or any other magic.  You       pointer  is set. There is no reference counting or any other magic. You
       can  free  the  patterns  and stacks in any order, anytime. Just do not       can free the patterns and stacks in any order,  anytime.  Just  do  not
       call pcre_exec() with a pattern pointing to an already freed stack,  as       call  pcre_exec() with a pattern pointing to an already freed stack, as
       that  will cause SEGFAULT. (Also, do not free a stack currently used by       that will cause SEGFAULT. (Also, do not free a stack currently used  by
       pcre_exec() in another thread). You can also replace the  stack  for  a       pcre_exec()  in  another  thread). You can also replace the stack for a
       pattern  at  any  time.  You  can  even  free the previous stack before       pattern at any time. You  can  even  free  the  previous  stack  before
        assigning a replacement.         assigning a replacement.
   
       (5) Should I allocate/free a  stack  every  time  before/after  calling       (5)  Should  I  allocate/free  a  stack every time before/afte       (5)  Should  I  allocate/free  a  stack every time before/afte
        pcre_exec()?         pcre_exec()?
   
       No,  because  this  is  too  costly in terms of resources. However, you       No, because this is too costly in  terms  of  resources.  However,  you
       could implement some clever idea which release the stack if it  is  not       could  implement  some clever idea which release the stack if it is not
        used in let's say two minutes. The JIT callback can help to achive this         used in let's say two minutes. The JIT callback can help to achive this
        without keeping a list of the currently JIT studied patterns.         without keeping a list of the currently JIT studied patterns.
   
       (6) OK, the stack is for long term memory allocation. But what  happens       (6)  OK, the stack is for long term memory allocation. But what happens
       if  a pattern causes stack overflow with a stack of 1M? Is that 1M kept       if a pattern causes stack overflow with a stack of 1M? Is that 1M  kept
        until the stack is freed?         until the stack is freed?
   
       Especially on embedded sytems, it might be a good idea to release  mem-       Especially  on embedded sytems, it might be a good idea to release mem-
       ory  sometimes  without  freeing the stack. There is no API for this at       ory sometimes without freeing the stack. There is no API  for  this  at
       the moment. Probably a function call which returns with  the  currently       the  moment.  Probably a function call which returns with the currently
       allocated  memory for any stack and another which allows releasing mem-       allocated memory for any stack and another which allows releasing  mem-
        ory (shrinking the stack) would be a good idea if someone needs this.         ory (shrinking the stack) would be a good idea if someone needs this.
   
        (7) This is too much of a headache. Isn't there any better solution for         (7) This is too much of a headache. Isn't there any better solution for
        JIT stack handling?         JIT stack handling?
   
       No,  thanks to Windows. If POSIX threads were used everywhere, we could       No, thanks to Windows. If POSIX threads were used everywhere, we  could
        throw out this complicated API.         throw out this complicated API.
   
   
 EXAMPLE CODE  EXAMPLE CODE
   
       This is a single-threaded example that specifies a  JIT  stack  without       This  is  a  single-threaded example that specifies a JIT stack without
        using a callback.         using a callback.
   
          int rc;           int rc;
Line 6831  AUTHOR Line 7459  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 26 November 2011       Last updated: 04 May 2012
       Copyright (c) 1997-2011 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 6845  NAME Line 7473  NAME
   
 PARTIAL MATCHING IN PCRE  PARTIAL MATCHING IN PCRE
   
       In  normal  use  of  PCRE,  if  the  subject  string  that is passed to       In normal use of PCRE, if the subject string that is passed to a match-
       pcre_exec() or pcre_dfa_exec() matches as far as it goes,  but  is  too       ing function matches as far as it goes, but is too short to  match  the
       short  to  match  the  entire  pattern, PCRE_ERROR_NOMATCH is returned.       entire pattern, PCRE_ERROR_NOMATCH is returned. There are circumstances
       There are circumstances where it might be helpful to  distinguish  this       where it might be helpful to distinguish this case from other cases  in
       case from other cases in which there is no match.       which there is no match.
   
        Consider, for example, an application where a human is required to type         Consider, for example, an application where a human is required to type
        in data for a field with specific formatting requirements.  An  example         in data for a field with specific formatting requirements.  An  example
Line 6867  PARTIAL MATCHING IN PCRE Line 7495  PARTIAL MATCHING IN PCRE
        available at once.         available at once.
   
        PCRE supports partial matching by means of  the  PCRE_PARTIAL_SOFT  and         PCRE supports partial matching by means of  the  PCRE_PARTIAL_SOFT  and
       PCRE_PARTIAL_HARD options, which can be set when calling pcre_exec() or       PCRE_PARTIAL_HARD  options,  which  can  be set when calling any of the
       pcre_dfa_exec(). For backwards compatibility, PCRE_PARTIAL is a synonym       matching functions. For backwards compatibility, PCRE_PARTIAL is a syn-
       for PCRE_PARTIAL_SOFT. The essential difference between the two options       onym  for  PCRE_PARTIAL_SOFT.  The essential difference between the two
       is whether or not a partial match is preferred to an  alternative  com-       options is whether or not a partial match is preferred to  an  alterna-
       plete  match,  though the details differ between the two matching func-       tive complete match, though the details differ between the two types of
       tions. If both options are set, PCRE_PARTIAL_HARD takes precedence.       matching function. If both options  are  set,  PCRE_PARTIAL_HARD  takes
        precedence.
   
       Setting a partial matching option for pcre_exec() disables the  use  of       If  you  want to use partial matching with just-in-time optimized code,
       any  just-in-time code that was set up by calling pcre_study() with the       you must call pcre_study() or pcre16_study() with one or both of  these
       PCRE_STUDY_JIT_COMPILE option. It also disables two of PCRE's  standard       options:
       optimizations.  PCRE  remembers the last literal byte in a pattern, and
       abandons matching immediately if such a byte is not present in the sub-         PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE
       ject string. This optimization cannot be used for a subject string that         PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE
       might match only partially. If the pattern was studied, PCRE knows  the
       minimum  length  of  a  matching string, and does not bother to run the       PCRE_STUDY_JIT_COMPILE  should also be set if you are going to run non-
       matching function on shorter strings. This optimization  is  also  dis-       partial matches on the same pattern. If the appropriate JIT study  mode
        has not been set for a match, the interpretive matching code is used.
 
        Setting a partial matching option disables two of PCRE's standard opti-
        mizations. PCRE remembers the last literal data unit in a pattern,  and
        abandons  matching  immediately  if  it  is  not present in the subject
        string. This optimization cannot be used  for  a  subject  string  that
        might  match only partially. If the pattern was studied, PCRE knows the
        minimum length of a matching string, and does not  bother  to  run  the
        matching  function  on  shorter strings. This optimization is also dis-
        abled for partial matching.         abled for partial matching.
   
   
PARTIAL MATCHING USING pcre_exec()PARTIAL MATCHING USING pcre_exec() OR pcre16_exec()
   
       A partial match occurs during a call to pcre_exec() when the end of the       A partial match occurs during a call to  pcre_exec()  or  pcre16_exec()
       subject string is reached successfully, but  matching  cannot  continue       when  the end of the subject string is reached successfully, but match-
       because  more characters are needed. However, at least one character in       ing cannot continue because more characters  are  needed.  However,  at
       the subject must have been inspected. This character need not form part       least one character in the subject must have been inspected. This char-
       of  the  final  matched string; lookbehind assertions and the \K escape       acter need not form part of the final matched string; lookbehind asser-
       sequence provide ways of inspecting characters before the  start  of  a       tions  and the \K escape sequence provide ways of inspecting characters
       matched  substring. The requirement for inspecting at least one charac-       before the start of a matched substring. The requirement for inspecting
       ter exists because an empty string can always be matched; without  such       at  least  one  character  exists because an empty string can always be
       a  restriction there would always be a partial match of an empty string       matched; without such a restriction there would  always  be  a  partial
       at the end of the subject.       match of an empty string at the end of the subject.
   
       If there are at least two slots in the offsets vector when  pcre_exec()       If  there  are  at least two slots in the offsets vector when a partial
       returns  with  a  partial match, the first slot is set to the offset of       match is returned, the first slot is set to the offset of the  earliest
       the earliest character that was inspected when the  partial  match  was       character that was inspected. For convenience, the second offset points
       found. For convenience, the second offset points to the end of the sub-       to the end of the subject so that a substring can easily be identified.
       ject so that a substring can easily be identified. 
   
        For the majority of patterns, the first offset identifies the start  of         For the majority of patterns, the first offset identifies the start  of
        the  partially matched string. However, for patterns that contain look-         the  partially matched string. However, for patterns that contain look-
Line 6920  PARTIAL MATCHING USING pcre_exec() Line 7557  PARTIAL MATCHING USING pcre_exec()
        What happens when a partial match is identified depends on which of the         What happens when a partial match is identified depends on which of the
        two partial matching options are set.         two partial matching options are set.
   
   PCRE_PARTIAL_SOFT with pcre_exec()   PCRE_PARTIAL_SOFT WITH pcre_exec() OR pcre16_exec()
   
       If  PCRE_PARTIAL_SOFT  is  set  when  pcre_exec()  identifies a partial       If  PCRE_PARTIAL_SOFT  is set when pcre_exec() or pcre16_exec() identi-
       match, the partial match is remembered, but matching continues as  nor-       fies a partial match, the partial match  is  remembered,  but  matching
       mal,  and  other  alternatives in the pattern are tried. If no complete       continues  as  normal, and other alternatives in the pattern are tried.
       match can be found, pcre_exec() returns PCRE_ERROR_PARTIAL  instead  of       If no complete match  can  be  found,  PCRE_ERROR_PARTIAL  is  returned
       PCRE_ERROR_NOMATCH.       instead of PCRE_ERROR_NOMATCH.
   
        This  option  is "soft" because it prefers a complete match over a par-         This  option  is "soft" because it prefers a complete match over a par-
        tial match.  All the various matching items in a pattern behave  as  if         tial match.  All the various matching items in a pattern behave  as  if
Line 6946  PARTIAL MATCHING USING pcre_exec() Line 7583  PARTIAL MATCHING USING pcre_exec()
        (In this example, there are two partial matches, because "dog"  on  its         (In this example, there are two partial matches, because "dog"  on  its
        own partially matches the second alternative.)         own partially matches the second alternative.)
   
   PCRE_PARTIAL_HARD with pcre_exec()   PCRE_PARTIAL_HARD WITH pcre_exec() OR pcre16_exec()
   
       If PCRE_PARTIAL_HARD is set for pcre_exec(), it returns PCRE_ERROR_PAR-       If   PCRE_PARTIAL_HARD   is   set  for  pcre_exec()  or  pcre16_exec(),
       TIAL as soon as a partial match is found, without continuing to  search       PCRE_ERROR_PARTIAL is returned as soon as a  partial  match  is  found,
       for possible complete matches. This option is "hard" because it prefers       without continuing to search for possible complete matches. This option
       an earlier partial match over a later complete match. For this  reason,       is "hard" because it prefers an earlier partial match over a later com-
       the  assumption is made that the end of the supplied subject string may       plete  match.  For  this reason, the assumption is made that the end of
       not be the true end of the available data, and so, if \z, \Z,  \b,  \B,       the supplied subject string may not be the true end  of  the  available
       or  $  are  encountered  at  the  end  of  the  subject,  the result is       data, and so, if \z, \Z, \b, \B, or $ are encountered at the end of the
       PCRE_ERROR_PARTIAL.       subject, the result is PCRE_ERROR_PARTIAL, provided that at  least  one
        character in the subject has been inspected.
   
       Setting PCRE_PARTIAL_HARD also affects the way pcre_exec() checks UTF-8       Setting PCRE_PARTIAL_HARD also affects the way UTF-8 and UTF-16 subject
       subject  strings  for  validity.  Normally,  an  invalid UTF-8 sequence       strings are checked for validity. Normally, an invalid sequence  causes
       causes the error PCRE_ERROR_BADUTF8. However, in the special case of  a       the  error  PCRE_ERROR_BADUTF8  or PCRE_ERROR_BADUTF16. However, in the
       truncated  UTF-8 character at the end of the subject, PCRE_ERROR_SHORT-       special case of a truncated  character  at  the  end  of  the  subject,
       UTF8 is returned when PCRE_PARTIAL_HARD is set.       PCRE_ERROR_SHORTUTF8   or   PCRE_ERROR_SHORTUTF16   is   returned  when
        PCRE_PARTIAL_HARD is set.
   
    Comparing hard and soft partial matching     Comparing hard and soft partial matching
   
Line 6979  PARTIAL MATCHING USING pcre_exec() Line 7618  PARTIAL MATCHING USING pcre_exec()
   
          /dog(sbody)??/           /dog(sbody)??/
   
       In this case the result is always a complete match because  pcre_exec()       In this case the result is always a  complete  match  because  that  is
       finds  that  first,  and  it  never continues after finding a match. It       found  first,  and  matching  never  continues after finding a complete
       might be easier to follow this explanation by thinking of the two  pat-       match. It might be easier to follow this explanation by thinking of the
       terns like this:       two patterns like this:
   
          /dog(sbody)?/    is the same as  /dogsbody|dog/           /dog(sbody)?/    is the same as  /dogsbody|dog/
          /dog(sbody)??/   is the same as  /dog|dogsbody/           /dog(sbody)??/   is the same as  /dog|dogsbody/
   
       The  second  pattern  will  never  match "dogsbody" when pcre_exec() is       The  second pattern will never match "dogsbody", because it will always
       used, because it will always find the shorter match first.       find the shorter match first.
   
   
PARTIAL MATCHING USING pcre_dfa_exec()PARTIAL MATCHING USING pcre_dfa_exec() OR pcre16_dfa_exec()
   
       The pcre_dfa_exec() function moves along the subject  string  character       The DFA functions move along the subject string character by character,
       by  character, without backtracking, searching for all possible matches       without  backtracking,  searching  for  all possible matches simultane-
       simultaneously. If the end of the subject is reached before the end  of       ously. If the end of the subject is reached before the end of the  pat-
       the  pattern,  there  is the possibility of a partial match, again pro-       tern,  there is the possibility of a partial match, again provided that
       vided that at least one character has been inspected.       at least one character has been inspected.
   
        When PCRE_PARTIAL_SOFT is set, PCRE_ERROR_PARTIAL is returned  only  if         When PCRE_PARTIAL_SOFT is set, PCRE_ERROR_PARTIAL is returned  only  if
        there  have  been  no complete matches. Otherwise, the complete matches         there  have  been  no complete matches. Otherwise, the complete matches
Line 7007  PARTIAL MATCHING USING pcre_dfa_exec() Line 7646  PARTIAL MATCHING USING pcre_dfa_exec()
        the first matching string, provided there are at least two slots in the         the first matching string, provided there are at least two slots in the
        offsets vector.         offsets vector.
   
       Because pcre_dfa_exec() always searches for all possible  matches,  and       Because the DFA functions always search for all possible  matches,  and
       there  is no difference between greedy and ungreedy repetition, its be-       there  is  no  difference between greedy and ungreedy repetition, their
       haviour is different from pcre_exec when PCRE_PARTIAL_HARD is set. Con-       behaviour is different  from  the  standard  functions  when  PCRE_PAR-
       sider  the  string  "dog"  matched  against  the ungreedy pattern shown       TIAL_HARD  is  set.  Consider  the  string  "dog"  matched  against the
       above:       ungreedy pattern shown above:
   
          /dog(sbody)??/           /dog(sbody)??/
   
       Whereas pcre_exec() stops as soon as it finds the  complete  match  for       Whereas the standard functions stop as soon as they find  the  complete
       "dog", pcre_dfa_exec() also finds the partial match for "dogsbody", and       match  for  "dog",  the  DFA  functions also find the partial match for
       so returns that when PCRE_PARTIAL_HARD is set.       "dogsbody", and so return that when PCRE_PARTIAL_HARD is set.
   
   
 PARTIAL MATCHING AND WORD BOUNDARIES  PARTIAL MATCHING AND WORD BOUNDARIES
Line 7031  PARTIAL MATCHING AND WORD BOUNDARIES Line 7670  PARTIAL MATCHING AND WORD BOUNDARIES
        This matches "cat", provided there is a word boundary at either end. If         This matches "cat", provided there is a word boundary at either end. If
        the subject string is "the cat", the comparison of the final "t" with a         the subject string is "the cat", the comparison of the final "t" with a
        following character cannot take place, so a  partial  match  is  found.         following character cannot take place, so a  partial  match  is  found.
       However,  pcre_exec() carries on with normal matching, which matches \b       However,  normal  matching carries on, and \b matches at the end of the
       at the end of the subject when the last character  is  a  letter,  thus       subject when the last character is a letter, so  a  complete  match  is
       finding a complete match. The result, therefore, is not PCRE_ERROR_PAR-       found.   The   result,  therefore,  is  not  PCRE_ERROR_PARTIAL.  Using
       TIAL. The same thing happens  with  pcre_dfa_exec(),  because  it  also       PCRE_PARTIAL_HARD in this case does yield  PCRE_ERROR_PARTIAL,  because
       finds the complete match.       then the partial match takes precedence.
   
        Using  PCRE_PARTIAL_HARD  in  this  case does yield PCRE_ERROR_PARTIAL,  
        because then the partial match takes precedence.  
   
   
 FORMERLY RESTRICTED PATTERNS  FORMERLY RESTRICTED PATTERNS
   
        For releases of PCRE prior to 8.00, because of the way certain internal         For releases of PCRE prior to 8.00, because of the way certain internal
       optimizations   were  implemented  in  the  pcre_exec()  function,  the       optimizations  were  implemented  in  the  pcre_exec()  function,   the
       PCRE_PARTIAL option (predecessor of  PCRE_PARTIAL_SOFT)  could  not  be       PCRE_PARTIAL  option  (predecessor  of  PCRE_PARTIAL_SOFT) could not be
       used  with all patterns. From release 8.00 onwards, the restrictions no       used with all patterns. From release 8.00 onwards, the restrictions  no
       longer apply, and partial matching with pcre_exec()  can  be  requested       longer  apply,  and partial matching with can be requested for any pat-
       for any pattern.       tern.
   
        Items that were formerly restricted were repeated single characters and         Items that were formerly restricted were repeated single characters and
       repeated metasequences. If PCRE_PARTIAL was set for a pattern that  did       repeated  metasequences. If PCRE_PARTIAL was set for a pattern that did
       not  conform  to  the restrictions, pcre_exec() returned the error code       not conform to the restrictions, pcre_exec() returned  the  error  code
       PCRE_ERROR_BADPARTIAL (-13). This error code is no longer in  use.  The       PCRE_ERROR_BADPARTIAL  (-13).  This error code is no longer in use. The
       PCRE_INFO_OKPARTIAL  call  to pcre_fullinfo() to find out if a compiled       PCRE_INFO_OKPARTIAL call to pcre_fullinfo() to find out if  a  compiled
        pattern can be used for partial matching now always returns 1.         pattern can be used for partial matching now always returns 1.
   
   
 EXAMPLE OF PARTIAL MATCHING USING PCRETEST  EXAMPLE OF PARTIAL MATCHING USING PCRETEST
   
       If the escape sequence \P is present  in  a  pcretest  data  line,  the       If  the  escape  sequence  \P  is  present in a pcretest data line, the
       PCRE_PARTIAL_SOFT  option  is  used  for  the  match.  Here is a run of       PCRE_PARTIAL_SOFT option is used for  the  match.  Here  is  a  run  of
        pcretest that uses the date example quoted above:         pcretest that uses the date example quoted above:
   
            re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/             re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
Line 7077  EXAMPLE OF PARTIAL MATCHING USING PCRETEST Line 7713  EXAMPLE OF PARTIAL MATCHING USING PCRETEST
          data> j\P           data> j\P
          No match           No match
   
       The first data string is matched  completely,  so  pcretest  shows  the       The  first  data  string  is  matched completely, so pcretest shows the
       matched  substrings.  The  remaining four strings do not match the com-       matched substrings. The remaining four strings do not  match  the  com-
        plete pattern, but the first two are partial matches. Similar output is         plete pattern, but the first two are partial matches. Similar output is
       obtained when pcre_dfa_exec() is used.       obtained if DFA matching is used.
   
       If  the escape sequence \P is present more than once in a pcretest data       If the escape sequence \P is present more than once in a pcretest  data
        line, the PCRE_PARTIAL_HARD option is set for the match.         line, the PCRE_PARTIAL_HARD option is set for the match.
   
   
MULTI-SEGMENT MATCHING WITH pcre_dfa_exec()MULTI-SEGMENT MATCHING WITH pcre_dfa_exec() OR pcre16_dfa_exec()
   
       When a partial match has been found using pcre_dfa_exec(), it is possi-       When  a  partial match has been found using a DFA matching function, it
       ble  to  continue  the  match  by providing additional subject data and       is possible to continue the match by providing additional subject  data
       calling pcre_dfa_exec() again with the same  compiled  regular  expres-       and  calling  the function again with the same compiled regular expres-
       sion,  this time setting the PCRE_DFA_RESTART option. You must pass the       sion, this time setting the PCRE_DFA_RESTART option. You must pass  the
        same working space as before, because this is where details of the pre-         same working space as before, because this is where details of the pre-
       vious  partial  match  are  stored.  Here is an example using pcretest,       vious partial match are stored. Here  is  an  example  using  pcretest,
       using the \R escape sequence to set  the  PCRE_DFA_RESTART  option  (\D       using  the  \R  escape  sequence to set the PCRE_DFA_RESTART option (\D
       specifies the use of pcre_dfa_exec()):       specifies the use of the DFA matching function):
   
            re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/             re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
          data> 23ja\P\D           data> 23ja\P\D
Line 7103  MULTI-SEGMENT MATCHING WITH pcre_dfa_exec() Line 7739  MULTI-SEGMENT MATCHING WITH pcre_dfa_exec()
          data> n05\R\D           data> n05\R\D
           0: n05            0: n05
   
       The  first  call has "23ja" as the subject, and requests partial match-       The first call has "23ja" as the subject, and requests  partial  match-
       ing; the second call  has  "n05"  as  the  subject  for  the  continued       ing;  the  second  call  has  "n05"  as  the  subject for the continued
       (restarted)  match.   Notice  that when the match is complete, only the       (restarted) match.  Notice that when the match is  complete,  only  the
       last part is shown; PCRE does  not  retain  the  previously  partially-       last  part  is  shown;  PCRE  does not retain the previously partially-
       matched  string. It is up to the calling program to do that if it needs       matched string. It is up to the calling program to do that if it  needs
        to.         to.
   
       You can set the PCRE_PARTIAL_SOFT  or  PCRE_PARTIAL_HARD  options  with       You  can  set  the  PCRE_PARTIAL_SOFT or PCRE_PARTIAL_HARD options with
       PCRE_DFA_RESTART  to  continue partial matching over multiple segments.       PCRE_DFA_RESTART to continue partial matching over  multiple  segments.
       This facility can  be  used  to  pass  very  long  subject  strings  to       This  facility can be used to pass very long subject strings to the DFA
       pcre_dfa_exec().       matching functions.
   
   
MULTI-SEGMENT MATCHING WITH pcre_exec()MULTI-SEGMENT MATCHING WITH pcre_exec() OR pcre16_exec()
   
       From  release  8.00,  pcre_exec()  can also be used to do multi-segment       From release 8.00, the standard matching functions can also be used  to
       matching. Unlike pcre_dfa_exec(), it is not  possible  to  restart  the       do multi-segment matching. Unlike the DFA functions, it is not possible
       previous  match  with  a new segment of data. Instead, new data must be       to restart the previous match with a new segment of data. Instead,  new
       added to the previous subject string,  and  the  entire  match  re-run,       data must be added to the previous subject string, and the entire match
       starting  from the point where the partial match occurred. Earlier data       re-run, starting from the point where the partial match occurred.  Ear-
       can be discarded. It is best to use PCRE_PARTIAL_HARD  in  this  situa-       lier data can be discarded.
       tion,  because it does not treat the end of a segment as the end of the 
       subject when matching \z, \Z, \b, \B, and  $.  Consider  an  unanchored 
       pattern that matches dates: 
   
          It  is best to use PCRE_PARTIAL_HARD in this situation, because it does
          not treat the end of a segment as the end of the subject when  matching
          \z,  \Z,  \b,  \B,  and  $. Consider an unanchored pattern that matches
          dates:
   
            re> /\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d/             re> /\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d/
          data> The date is 23ja\P\P           data> The date is 23ja\P\P
          Partial match: 23ja           Partial match: 23ja
   
       At  this stage, an application could discard the text preceding "23ja",       At this stage, an application could discard the text preceding  "23ja",
       add on text from the next segment, and call pcre_exec()  again.  Unlike       add  on  text  from  the  next  segment, and call the matching function
       pcre_dfa_exec(),  the  entire matching string must always be available,       again. Unlike the DFA matching functions, the  entire  matching  string
       and the complete matching process occurs for each call, so more  memory       must  always be available, and the complete matching process occurs for
       and more processing time is needed.       each call, so more memory and more processing time is needed.
   
       Note:  If  the pattern contains lookbehind assertions, or \K, or starts       Note: If the pattern contains lookbehind assertions, or \K,  or  starts
       with \b or \B, the string that is returned for  a  partial  match  will       with \b or \B, the string that is returned for a partial match includes
       include  characters  that  precede the partially matched string itself,       characters that precede the partially matched  string  itself,  because
       because these must be retained when adding on  more  characters  for  a       these  must be retained when adding on more characters for a subsequent
       subsequent matching attempt.       matching attempt.  However, in some cases you may need to  retain  even
        earlier characters, as discussed in the next section.
   
   
 ISSUES WITH MULTI-SEGMENT MATCHING  ISSUES WITH MULTI-SEGMENT MATCHING
Line 7156  ISSUES WITH MULTI-SEGMENT MATCHING Line 7795  ISSUES WITH MULTI-SEGMENT MATCHING
        option, but in practice when doing multi-segment matching you should be         option, but in practice when doing multi-segment matching you should be
        using PCRE_PARTIAL_HARD, which includes the effect of PCRE_NOTEOL.         using PCRE_PARTIAL_HARD, which includes the effect of PCRE_NOTEOL.
   
       2. Lookbehind assertions at the start of a pattern are catered  for  in       2. Lookbehind assertions that have already been obeyed are catered  for
       the  offsets that are returned for a partial match. However, in theory,       in the offsets that are returned for a partial match. However a lookbe-
       a lookbehind assertion later in the pattern could require even  earlier       hind assertion later in the pattern could require even earlier  charac-
       characters  to  be inspected, and it might not have been reached when a       ters   to  be  inspected.  You  can  handle  this  case  by  using  the
       partial match occurs. This is probably an extremely unlikely case;  you       PCRE_INFO_MAXLOOKBEHIND    option    of    the    pcre_fullinfo()    or
       could  guard  against  it to a certain extent by always including extra       pcre16_fullinfo() functions to obtain the length of the largest lookbe-
       characters at the start.       hind in the pattern. This length is given in characters, not bytes.  If
        you  always  retain  at least that many characters before the partially
        matched string, all should be well. (Of course, near the start  of  the
        subject,  fewer  characters may be present; in that case all characters
        should be retained.)
   
       3. Matching a subject string that is split into multiple  segments  may       3. Because a partial match must always contain at least one  character,
       not  always produce exactly the same result as matching over one single       what  might  be  considered a partial match of an empty string actually
       long string, especially when PCRE_PARTIAL_SOFT  is  used.  The  section       gives a "no match" result. For example:
       "Partial  Matching  and  Word Boundaries" above describes an issue that
       arises if the pattern ends with \b or \B. Another  kind  of  difference           re> /c(?<=abc)x/
       may  occur when there are multiple matching possibilities, because (for         data> ab\P
       PCRE_PARTIAL_SOFT) a partial match result is given only when there  are        no completed matches. This means that as soon as the shortest match has
 
        If the next segment begins "cx", a match should be found, but this will
        only  happen  if characters from the previous segment are retained. For
        this reason, a "no match" result  should  be  interpreted  as  "partial
        match of an empty string" when the pattern contains lookbehinds.
 
        4.  Matching  a subject string that is split into multiple segments may
        not always produce exactly the same result as matching over one  single
        long  string,  especially  when  PCRE_PARTIAL_SOFT is used. The section
        "Partial Matching and Word Boundaries" above describes  an  issue  that
        arises  if  the  pattern ends with \b or \B. Another kind of difference
        may occur when there are multiple matching possibilities, because  (for
        PCRE_PARTIAL_SOFT)  a partial match result is given only when there are
        no completed matches. This means that as soon as the shortest match has         no completed matches. This means that as soon as the shortest match has
       been found, continuation to a new subject segment is no  longer  possi-       been  found,  continuation to a new subject segment is no longer possi-
        ble. Consider again this pcretest example:         ble. Consider again this pcretest example:
   
            re> /dog(sbody)?/             re> /dog(sbody)?/
Line 7186  ISSUES WITH MULTI-SEGMENT MATCHING Line 7842  ISSUES WITH MULTI-SEGMENT MATCHING
           0: dogsbody            0: dogsbody
           1: dog            1: dog
   
       The  first  data line passes the string "dogsb" to pcre_exec(), setting       The first data line passes the string "dogsb" to  a  standard  matching
       the PCRE_PARTIAL_SOFT option. Although the string is  a  partial  match       function,  setting the PCRE_PARTIAL_SOFT option. Although the string is
       for  "dogsbody",  the  result  is  not  PCRE_ERROR_PARTIAL, because the       a partial match for "dogsbody", the result is  not  PCRE_ERROR_PARTIAL,
       shorter string "dog" is a complete match. Similarly, when  the  subject       because  the  shorter string "dog" is a complete match. Similarly, when
       is  presented to pcre_dfa_exec() in several parts ("do" and "gsb" being       the subject is presented to a DFA matching function  in  several  parts
       the first two) the match stops when "dog" has been found, and it is not       ("do"  and  "gsb"  being  the first two) the match stops when "dog" has
       possible  to continue. On the other hand, if "dogsbody" is presented as       been found, and it is not possible to continue.  On the other hand,  if
       a single string, pcre_dfa_exec() finds both matches.       "dogsbody"  is  presented  as  a single string, a DFA matching function
        finds both matches.
   
        Because of these problems, it is best  to  use  PCRE_PARTIAL_HARD  when         Because of these problems, it is best  to  use  PCRE_PARTIAL_HARD  when
        matching  multi-segment  data.  The  example above then behaves differ-         matching  multi-segment  data.  The  example above then behaves differ-
Line 7207  ISSUES WITH MULTI-SEGMENT MATCHING Line 7864  ISSUES WITH MULTI-SEGMENT MATCHING
          data> gsb\R\P\P\D           data> gsb\R\P\P\D
          Partial match: gsb           Partial match: gsb
   
       4. Patterns that contain alternatives at the top level which do not all       5. Patterns that contain alternatives at the top level which do not all
        start  with  the  same  pattern  item  may  not  work  as expected when         start  with  the  same  pattern  item  may  not  work  as expected when
       PCRE_DFA_RESTART is used with pcre_dfa_exec().  For  example,  consider       PCRE_DFA_RESTART is used. For example, consider this pattern:
       this pattern: 
   
          1234|3789           1234|3789
   
       If  the  first  part of the subject is "ABC123", a partial match of the       If the first part of the subject is "ABC123", a partial  match  of  the
       first alternative is found at offset 3. There is no partial  match  for       first  alternative  is found at offset 3. There is no partial match for
        the second alternative, because such a match does not start at the same         the second alternative, because such a match does not start at the same
       point in the subject string. Attempting to  continue  with  the  string       point  in  the  subject  string. Attempting to continue with the string
       "7890"  does  not  yield  a  match because only those alternatives that       "7890" does not yield a match  because  only  those  alternatives  that
       match at one point in the subject are remembered.  The  problem  arises       match  at  one  point in the subject are remembered. The problem arises
       because  the  start  of the second alternative matches within the first       because the start of the second alternative matches  within  the  first
       alternative. There is no problem with  anchored  patterns  or  patterns       alternative.  There  is  no  problem with anchored patterns or patterns
        such as:         such as:
   
          1234|ABCD           1234|ABCD
   
       where  no  string can be a partial match for both alternatives. This is       where no string can be a partial match for both alternatives.  This  is
       not a problem if pcre_exec() is used, because the entire match  has  to       not  a  problem  if  a  standard matching function is used, because the
       be rerun each time:       entire match has to be rerun each time:
   
            re> /1234|3789/             re> /1234|3789/
          data> ABC123\P\P           data> ABC123\P\P
Line 7237  ISSUES WITH MULTI-SEGMENT MATCHING Line 7893  ISSUES WITH MULTI-SEGMENT MATCHING
           0: 3789            0: 3789
   
        Of course, instead of using PCRE_DFA_RESTART, the same technique of re-         Of course, instead of using PCRE_DFA_RESTART, the same technique of re-
       running the entire match can also be used with pcre_dfa_exec(). Another       running  the  entire match can also be used with the DFA matching func-
       possibility is to work with two buffers. If a partial match at offset n       tions. Another possibility is to work with two buffers.  If  a  partial
       in the first buffer is followed by "no match" when PCRE_DFA_RESTART  is       match  at  offset  n in the first buffer is followed by "no match" when
       used  on  the  second  buffer, you can then try a new match starting at       PCRE_DFA_RESTART is used on the second buffer, you can then try  a  new
       offset n+1 in the first buffer.       match starting at offset n+1 in the first buffer.
   
   
 AUTHOR  AUTHOR
Line 7253  AUTHOR Line 7909  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 26 August 2011       Last updated: 24 February 2012
       Copyright (c) 1997-2011 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 7273  SAVING AND RE-USING PRECOMPILED PCRE PATTERNS Line 7929  SAVING AND RE-USING PRECOMPILED PCRE PATTERNS
        run.  If you are not  using  any  private  character  tables  (see  the         run.  If you are not  using  any  private  character  tables  (see  the
        pcre_maketables()  documentation),  this is relatively straightforward.         pcre_maketables()  documentation),  this is relatively straightforward.
        If you are using private tables, it is a little bit  more  complicated.         If you are using private tables, it is a little bit  more  complicated.
       However,  if  you  are  using  the just-in-time optimization feature of       However,  if you are using the just-in-time optimization feature, it is
       pcre_study(), it is not possible to save and reload the JIT data.       not possible to save and reload the JIT data.
   
        If you save compiled patterns to a file, you can copy them to a differ-         If you save compiled patterns to a file, you can copy them to a differ-
       ent  host  and  run them there. This works even if the new host has the       ent host and run them there. If the two hosts have different endianness
       opposite endianness to the one on which  the  patterns  were  compiled.       (byte order), you should run the  pcre[16]_pattern_to_host_byte_order()
       There  may  be a small performance penalty, but it should be insignifi-       function on the new host before trying to match the pattern. The match-
       cant. However, compiling regular expressions with one version  of  PCRE       ing functions return PCRE_ERROR_BADENDIANNESS if they detect a  pattern
       for  use  with  a  different  version is not guaranteed to work and may       with the wrong endianness.
       cause crashes, and saving and restoring a compiled  pattern  loses  any 
       JIT optimization data. 
   
          Compiling  regular  expressions with one version of PCRE for use with a
          different version is not guaranteed to work and may cause crashes,  and
          saving  and  restoring  a  compiled  pattern loses any JIT optimization
          data.
   
   
 SAVING A COMPILED PATTERN  SAVING A COMPILED PATTERN
   
       The value returned by pcre_compile() points to a single block of memory       The value returned by pcre[16]_compile() points to a  single  block  of
       that holds the compiled pattern and associated data. You can  find  the       memory  that  holds  the  compiled pattern and associated data. You can
       length  of this block in bytes by calling pcre_fullinfo() with an argu-       find the length of this block in bytes by  calling  pcre[16]_fullinfo()
       ment of PCRE_INFO_SIZE. You can then save the data in  any  appropriate       with  an  argument of PCRE_INFO_SIZE. You can then save the data in any
       manner.  Here is sample code that compiles a pattern and writes it to a       appropriate manner. Here is sample code for the 8-bit library that com-
       file. It assumes that the variable fd refers to a file that is open for       piles  a  pattern and writes it to a file. It assumes that the variable
       output:       fd refers to a file that is open for output:
   
          int erroroffset, rc, size;           int erroroffset, rc, size;
          char *error;           char *error;
Line 7307  SAVING A COMPILED PATTERN Line 7966  SAVING A COMPILED PATTERN
          rc = fwrite(re, 1, size, fd);           rc = fwrite(re, 1, size, fd);
          if (rc != size) { ... handle errors ... }           if (rc != size) { ... handle errors ... }
   
       In  this  example,  the  bytes  that  comprise the compiled pattern are       In this example, the bytes  that  comprise  the  compiled  pattern  are
       copied exactly. Note that this is binary data that may contain  any  of       copied  exactly.  Note that this is binary data that may contain any of
       the  256  possible  byte  values.  On  systems  that make a distinction       the 256 possible byte  values.  On  systems  that  make  a  distinction
        between binary and non-binary data, be sure that the file is opened for         between binary and non-binary data, be sure that the file is opened for
        binary output.         binary output.
   
       If  you want to write more than one pattern to a file, you will have to       If you want to write more than one pattern to a file, you will have  to
       devise a way of separating them. For binary data, preceding  each  pat-       devise  a  way of separating them. For binary data, preceding each pat-
       tern  with  its  length  is probably the most straightforward approach.       tern with its length is probably  the  most  straightforward  approach.
       Another possibility is to write out the data in hexadecimal instead  of       Another  possibility is to write out the data in hexadecimal instead of
        binary, one pattern to a line.         binary, one pattern to a line.
   
       Saving  compiled patterns in a file is only one possible way of storing       Saving compiled patterns in a file is only one possible way of  storing
       them for later use. They could equally well be saved in a database,  or       them  for later use. They could equally well be saved in a database, or
       in  the  memory  of some daemon process that passes them via sockets to       in the memory of some daemon process that passes them  via  sockets  to
        the processes that want them.         the processes that want them.
   
        If the pattern has been studied, it is also possible to save the normal         If the pattern has been studied, it is also possible to save the normal
        study data in a similar way to the compiled pattern itself. However, if         study data in a similar way to the compiled pattern itself. However, if
        the PCRE_STUDY_JIT_COMPILE was used, the just-in-time data that is cre-         the PCRE_STUDY_JIT_COMPILE was used, the just-in-time data that is cre-
       ated  cannot  be saved because it is too dependent on the current envi-       ated cannot be saved because it is too dependent on the  current  envi-
       ronment. When studying generates additional  information,  pcre_study()       ronment.    When    studying    generates    additional    information,
       returns  a pointer to a pcre_extra data block. Its format is defined in       pcre[16]_study() returns a pointer to a pcre[16]_extra data block.  Its
       the section on matching a pattern in  the  pcreapi  documentation.  The       format  is  defined in the section on matching a pattern in the pcreapi
       study_data  field points to the binary study data, and this is what you       documentation. The study_data field points to the  binary  study  data,
       must save (not the pcre_extra block itself). The length  of  the  study       and  this  is what you must save (not the pcre[16]_extra block itself).
       data  can  be  obtained  by calling pcre_fullinfo() with an argument of       The  length  of  the  study   data   can   be   obtained   by   calling
       PCRE_INFO_STUDYSIZE. Remember to check that pcre_study() did  return  a       pcre[16]_fullinfo()  with  an argument of PCRE_INFO_STUDYSIZE. Remember
       non-NULL value before trying to save the study data.       to check that pcre[16]_study() did return a non-NULL value before  try-
        ing to save the study data.
   
   
 RE-USING A PRECOMPILED PATTERN  RE-USING A PRECOMPILED PATTERN
   
        Re-using  a  precompiled pattern is straightforward. Having reloaded it         Re-using  a  precompiled pattern is straightforward. Having reloaded it
       into  main  memory,  you   pass   its   pointer   to   pcre_exec()   or       into main memory, called pcre[16]_pattern_to_host_byte_order() if  nec-
       pcre_dfa_exec()  in  the  usual  way.  This should work even on another       essary,  you pass its pointer to pcre[16]_exec() or pcre[16]_dfa_exec()
       host, and even if that host has the  opposite  endianness  to  the  one       in the usual way.
       where the pattern was compiled. 
   
       However,  if  you  passed a pointer to custom character tables when the       However, if you passed a pointer to custom character  tables  when  the
       pattern was compiled (the tableptr  argument  of  pcre_compile()),  you       pattern was compiled (the tableptr argument of pcre[16]_compile()), you
       must  now  pass  a  similar  pointer to pcre_exec() or pcre_dfa_exec(),       must   now   pass   a   similar   pointer   to    pcre[16]_exec()    or
       because the value saved with the compiled  pattern  will  obviously  be       pcre[16]_dfa_exec(),  because the value saved with the compiled pattern
       nonsense. A field in a pcre_extra() block is used to pass this data, as       will obviously be nonsense. A field in a pcre[16]_extra() block is used
       described in the section on matching a pattern in the pcreapi  documen-       to pass this data, as described in the section on matching a pattern in
       tation.       the pcreapi documentation.
   
       If  you  did  not  provide custom character tables when the pattern was       If you did not provide custom character tables  when  the  pattern  was
       compiled, the pointer in the compiled pattern  is  NULL,  which  causes       compiled, the pointer in the compiled pattern is NULL, which causes the
       pcre_exec()  to  use  PCRE's  internal tables. Thus, you do not need to       matching functions to use PCRE's internal tables. Thus, you do not need
       take any special action at run time in this case.       to take any special action at run time in this case.
   
       If you saved study data with the compiled pattern, you need  to  create       If  you  saved study data with the compiled pattern, you need to create
       your own pcre_extra data block and set the study_data field to point to       your own pcre[16]_extra data block and  set  the  study_data  field  to
       the reloaded study data. You must also  set  the  PCRE_EXTRA_STUDY_DATA       point   to   the   reloaded   study   data.   You  must  also  set  the
       bit  in  the  flags  field to indicate that study data is present. Then       PCRE_EXTRA_STUDY_DATA bit in the flags field  to  indicate  that  study
       pass the pcre_extra block to  pcre_exec()  or  pcre_dfa_exec()  in  the       data  is  present.  Then  pass the pcre[16]_extra block to the matching
       usual  way.  If  the pattern was studied for just-in-time optimization,       function in the usual way. If the pattern was studied for  just-in-time
       that data cannot be saved, and so is lost by a save/restore cycle.       optimization,  that  data  cannot  be  saved,  and  so  is  lost  by  a
        save/restore cycle.
   
   
 COMPATIBILITY WITH DIFFERENT PCRE RELEASES  COMPATIBILITY WITH DIFFERENT PCRE RELEASES
Line 7384  AUTHOR Line 8044  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 26 August 2011       Last updated: 10 January 2012
       Copyright (c) 1997-2011 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 7405  PCRE PERFORMANCE Line 8065  PCRE PERFORMANCE
   
 COMPILED PATTERN MEMORY USAGE  COMPILED PATTERN MEMORY USAGE
   
       Patterns are compiled by PCRE into a reasonably efficient byte code, so       Patterns  are compiled by PCRE into a reasonably efficient interpretive
       that most simple patterns do not use much memory. However, there is one       code, so that most simple patterns do not  use  much  memory.  However,
       case  where  the memory usage of a compiled pattern can be unexpectedly       there  is  one case where the memory usage of a compiled pattern can be
       large. If a parenthesized subpattern has a quantifier  with  a  minimum       unexpectedly large. If a parenthesized subpattern has a quantifier with
       greater  than  1  and/or  a  limited  maximum,  the whole subpattern is       a minimum greater than 1 and/or a limited maximum, the whole subpattern
       repeated in the compiled code. For example, the pattern       is repeated in the compiled code. For example, the pattern
   
          (abc|def){2,4}           (abc|def){2,4}
   
Line 7428  COMPILED PATTERN MEMORY USAGE Line 8088  COMPILED PATTERN MEMORY USAGE
   
          ((ab){1,1000}c){1,3}           ((ab){1,1000}c){1,3}
   
       uses 51K bytes when compiled. When PCRE is compiled  with  its  default       uses 51K bytes when compiled using the 8-bit library. When PCRE is com-
       internal  pointer  size of two bytes, the size limit on a compiled pat-       piled  with  its  default  internal pointer size of two bytes, the size
       tern is 64K, and this is reached with the above pattern  if  the  outer       limit on a compiled pattern is 64K data units, and this is reached with
       repetition is increased from 3 to 4. PCRE can be compiled to use larger       the  above  pattern  if  the outer repetition is increased from 3 to 4.
       internal pointers and thus handle larger compiled patterns, but  it  is       PCRE can be compiled to use larger internal pointers  and  thus  handle
       better to try to rewrite your pattern to use less memory if you can.       larger  compiled patterns, but it is better to try to rewrite your pat-
        tern to use less memory if you can.
   
       One  way  of reducing the memory usage for such patterns is to make use       One way of reducing the memory usage for such patterns is to  make  use
        of PCRE's "subroutine" facility. Re-writing the above pattern as         of PCRE's "subroutine" facility. Re-writing the above pattern as
   
          ((ab)(?2){0,999}c)(?1){0,2}           ((ab)(?2){0,999}c)(?1){0,2}
   
        reduces the memory requirements to 18K, and indeed it remains under 20K         reduces the memory requirements to 18K, and indeed it remains under 20K
       even  with the outer repetition increased to 100. However, this pattern       even with the outer repetition increased to 100. However, this  pattern
       is not exactly equivalent, because the "subroutine" calls  are  treated       is  not  exactly equivalent, because the "subroutine" calls are treated
       as  atomic groups into which there can be no backtracking if there is a       as atomic groups into which there can be no backtracking if there is  a
       subsequent matching failure. Therefore, PCRE cannot  do  this  kind  of       subsequent  matching  failure.  Therefore,  PCRE cannot do this kind of
       rewriting  automatically.   Furthermore,  there is a noticeable loss of       rewriting automatically.  Furthermore, there is a  noticeable  loss  of
       speed when executing the modified pattern. Nevertheless, if the  atomic       speed  when executing the modified pattern. Nevertheless, if the atomic
       grouping  is  not  a  problem and the loss of speed is acceptable, this       grouping is not a problem and the loss of  speed  is  acceptable,  this
       kind of rewriting will allow you to process patterns that  PCRE  cannot       kind  of  rewriting will allow you to process patterns that PCRE cannot
        otherwise handle.         otherwise handle.
   
   
 STACK USAGE AT RUN TIME  STACK USAGE AT RUN TIME
   
       When  pcre_exec()  is  used  for matching, certain kinds of pattern can       When pcre_exec() or pcre16_exec() is used for matching,  certain  kinds
       cause it to use large amounts of the process stack.  In  some  environ-       of  pattern  can cause it to use large amounts of the process stack. In
       ments  the default process stack is quite small, and if it runs out the       some environments the default process stack is quite small, and  if  it
       result is often SIGSEGV.  This issue is probably  the  most  frequently       runs  out  the result is often SIGSEGV. This issue is probably the most
       raised  problem  with  PCRE. Rewriting your pattern can often help. The       frequently raised problem with PCRE. Rewriting your pattern  can  often
       pcrestack documentation discusses this issue in detail.       help. The pcrestack documentation discusses this issue in detail.
   
   
 PROCESSING TIME  PROCESSING TIME
   
       Certain items in regular expression patterns are processed  more  effi-       Certain  items  in regular expression patterns are processed more effi-
        ciently than others. It is more efficient to use a character class like         ciently than others. It is more efficient to use a character class like
       [aeiou]  than  a  set  of   single-character   alternatives   such   as       [aeiou]   than   a   set   of  single-character  alternatives  such  as
       (a|e|i|o|u).  In  general,  the simplest construction that provides the       (a|e|i|o|u). In general, the simplest construction  that  provides  the
        required behaviour is usually the most efficient. Jeffrey Friedl's book         required behaviour is usually the most efficient. Jeffrey Friedl's book
       contains  a  lot  of useful general discussion about optimizing regular       contains a lot of useful general discussion  about  optimizing  regular
       expressions for efficient performance. This  document  contains  a  few       expressions  for  efficient  performance.  This document contains a few
        observations about PCRE.         observations about PCRE.
   
       Using  Unicode  character  properties  (the  \p, \P, and \X escapes) is       Using Unicode character properties (the \p,  \P,  and  \X  escapes)  is
       slow, because PCRE has to scan a structure that contains data for  over       slow,  because PCRE has to scan a structure that contains data for over
       fifteen  thousand  characters whenever it needs a character's property.       fifteen thousand characters whenever it needs a  character's  property.
       If you can find an alternative pattern  that  does  not  use  character       If  you  can  find  an  alternative pattern that does not use character
        properties, it will probably be faster.         properties, it will probably be faster.
   
       By  default,  the  escape  sequences  \b, \d, \s, and \w, and the POSIX       By default, the escape sequences \b, \d, \s,  and  \w,  and  the  POSIX
       character classes such as [:alpha:]  do  not  use  Unicode  properties,       character  classes  such  as  [:alpha:]  do not use Unicode properties,
        partly for backwards compatibility, and partly for performance reasons.         partly for backwards compatibility, and partly for performance reasons.
       However, you can set PCRE_UCP if you want Unicode character  properties       However,  you can set PCRE_UCP if you want Unicode character properties
       to  be  used.  This  can double the matching time for items such as \d,       to be used. This can double the matching time for  items  such  as  \d,
       when matched with  pcre_exec();  the  performance  loss  is  less  with       when matched with a traditional matching function; the performance loss
       pcre_dfa_exec(), and in both cases there is not much difference for \b.       is less with a DFA matching function, and in both cases  there  is  not
        much difference for \b.
   
        When  a  pattern  begins  with .* not in parentheses, or in parentheses         When  a  pattern  begins  with .* not in parentheses, or in parentheses
        that are not the subject of a backreference, and the PCRE_DOTALL option         that are not the subject of a backreference, and the PCRE_DOTALL option
Line 7552  AUTHOR Line 8214  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 16 May 2010       Last updated: 09 January 2012
       Copyright (c) 1997-2010 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 7582  SYNOPSIS OF POSIX API Line 8244  SYNOPSIS OF POSIX API
   
 DESCRIPTION  DESCRIPTION
   
       This  set  of  functions provides a POSIX-style API to the PCRE regular       This  set  of functions provides a POSIX-style API for the PCRE regular
       expression package. See the pcreapi documentation for a description  of       expression 8-bit library. See the pcreapi documentation for a  descrip-
       PCRE's native API, which contains much additional functionality.       tion  of  PCRE's native API, which contains much additional functional-
        ity. There is no POSIX-style wrapper for PCRE's 16-bit library.
   
        The functions described here are just wrapper functions that ultimately         The functions described here are just wrapper functions that ultimately
        call  the  PCRE  native  API.  Their  prototypes  are  defined  in  the         call  the  PCRE  native  API.  Their  prototypes  are  defined  in  the
       pcreposix.h  header  file,  and  on  Unix systems the library itself is       pcreposix.h header file, and on Unix  systems  the  library  itself  is
       called pcreposix.a, so can be accessed by  adding  -lpcreposix  to  the       called  pcreposix.a,  so  can  be accessed by adding -lpcreposix to the
       command  for  linking  an application that uses them. Because the POSIX       command for linking an application that uses them.  Because  the  POSIX
        functions call the native ones, it is also necessary to add -lpcre.         functions call the native ones, it is also necessary to add -lpcre.
   
       I have implemented only those POSIX option bits that can be  reasonably       I  have implemented only those POSIX option bits that can be reasonably
       mapped  to PCRE native options. In addition, the option REG_EXTENDED is       mapped to PCRE native options. In addition, the option REG_EXTENDED  is
       defined with the value zero. This has no  effect,  but  since  programs       defined  with  the  value  zero. This has no effect, but since programs
       that  are  written  to  the POSIX interface often use it, this makes it       that are written to the POSIX interface often use  it,  this  makes  it
       easier to slot in PCRE as a replacement library.  Other  POSIX  options       easier  to  slot  in PCRE as a replacement library. Other POSIX options
        are not even defined.         are not even defined.
   
       There  are also some other options that are not defined by POSIX. These       There are also some other options that are not defined by POSIX.  These
        have been added at the request of users who want to make use of certain         have been added at the request of users who want to make use of certain
        PCRE-specific features via the POSIX calling interface.         PCRE-specific features via the POSIX calling interface.
   
       When  PCRE  is  called  via these functions, it is only the API that is       When PCRE is called via these functions, it is only  the  API  that  is
       POSIX-like in style. The syntax and semantics of  the  regular  expres-       POSIX-like  in  style.  The syntax and semantics of the regular expres-
       sions  themselves  are  still  those of Perl, subject to the setting of       sions themselves are still those of Perl, subject  to  the  setting  of
       various PCRE options, as described below. "POSIX-like in  style"  means       various  PCRE  options, as described below. "POSIX-like in style" means
       that  the  API  approximates  to  the POSIX definition; it is not fully       that the API approximates to the POSIX  definition;  it  is  not  fully
       POSIX-compatible, and in multi-byte encoding  domains  it  is  probably       POSIX-compatible,  and  in  multi-byte  encoding domains it is probably
        even less compatible.         even less compatible.
   
       The  header for these functions is supplied as pcreposix.h to avoid any       The header for these functions is supplied as pcreposix.h to avoid  any
       potential clash with other POSIX  libraries.  It  can,  of  course,  be       potential  clash  with  other  POSIX  libraries.  It can, of course, be
        renamed or aliased as regex.h, which is the "correct" name. It provides         renamed or aliased as regex.h, which is the "correct" name. It provides
       two structure types, regex_t for  compiled  internal  forms,  and  reg-       two  structure  types,  regex_t  for  compiled internal forms, and reg-
       match_t  for  returning  captured substrings. It also defines some con-       match_t for returning captured substrings. It also  defines  some  con-
       stants whose names start  with  "REG_";  these  are  used  for  setting       stants  whose  names  start  with  "REG_";  these  are used for setting
        options and identifying error codes.         options and identifying error codes.
   
   
 COMPILING A PATTERN  COMPILING A PATTERN
   
       The  function regcomp() is called to compile a pattern into an internal       The function regcomp() is called to compile a pattern into an  internal
       form. The pattern is a C string terminated by a  binary  zero,  and  is       form.  The  pattern  is  a C string terminated by a binary zero, and is
       passed  in  the  argument  pattern. The preg argument is a pointer to a       passed in the argument pattern. The preg argument is  a  pointer  to  a
       regex_t structure that is used as a base for storing information  about       regex_t  structure that is used as a base for storing information about
        the compiled regular expression.         the compiled regular expression.
   
        The argument cflags is either zero, or contains one or more of the bits         The argument cflags is either zero, or contains one or more of the bits
Line 7640  COMPILING A PATTERN Line 8303  COMPILING A PATTERN
   
          REG_ICASE           REG_ICASE
   
       The PCRE_CASELESS option is set when the regular expression  is  passed       The  PCRE_CASELESS  option is set when the regular expression is passed
        for compilation to the native function.         for compilation to the native function.
   
          REG_NEWLINE           REG_NEWLINE
   
       The  PCRE_MULTILINE option is set when the regular expression is passed       The PCRE_MULTILINE option is set when the regular expression is  passed
       for compilation to the native function. Note that this does  not  mimic       for  compilation  to the native function. Note that this does not mimic
       the  defined  POSIX  behaviour  for REG_NEWLINE (see the following sec-       the defined POSIX behaviour for REG_NEWLINE  (see  the  following  sec-
        tion).         tion).
   
          REG_NOSUB           REG_NOSUB
   
       The PCRE_NO_AUTO_CAPTURE option is set when the regular  expression  is       The  PCRE_NO_AUTO_CAPTURE  option is set when the regul       The  PCRE_NO_AUTO_CAPTURE  option is set when the regular expression is
        passed for compilation to the native function. In addition, when a pat-         passed for compilation to the native function. In addition, when a pat-
       tern that is compiled with this flag is passed to regexec() for  match-       tern  that is compiled with this flag is passed to regexec() for match-
       ing,  the  nmatch  and  pmatch  arguments  are ignored, and no captured       ing, the nmatch and pmatch  arguments  are  ignored,  and  no  captured
        strings are returned.         strings are returned.
   
          REG_UCP           REG_UCP
   
       The PCRE_UCP option is set when the regular expression  is  passed  for       The  PCRE_UCP  option  is set when the regular expression is passed for
       compilation  to  the  native  function. This causes PCRE to use Unicode       compilation to the native function. This causes  PCRE  to  use  Unicode
       properties when matchine \d, \w,  etc.,  instead  of  just  recognizing       properties  when  matchine  \d,  \w,  etc., instead of just recognizing
        ASCII values. Note that REG_UTF8 is not part of the POSIX standard.         ASCII values. Note that REG_UTF8 is not part of the POSIX standard.
   
          REG_UNGREEDY           REG_UNGREEDY
   
       The  PCRE_UNGREEDY  option is set when the regular expression is passed       The PCRE_UNGREEDY option is set when the regular expression  is  passed
       for compilation to the native function. Note that REG_UNGREEDY  is  not       for  compilation  to the native function. Note that REG_UNGREEDY is not
        part of the POSIX standard.         part of the POSIX standard.
   
          REG_UTF8           REG_UTF8
   
       The  PCRE_UTF8  option is set when the regular expression is passed for       The PCRE_UTF8 option is set when the regular expression is  passed  for
       compilation to the native function. This causes the pattern itself  and       compilation  to the native function. This causes the pattern itself and
       all  data  strings used for matching it to be treated as UTF-8 strings.       all data strings used for matching it to be treated as  UTF-8  strings.
        Note that REG_UTF8 is not part of the POSIX standard.         Note that REG_UTF8 is not part of the POSIX standard.
   
       In the absence of these flags, no options  are  passed  to  the  native       In  the  absence  of  these  flags, no options are passed to the native
       function.   This  means  the  the  regex  is compiled with PCRE default       function.  This means the the  regex  is  compiled  with  PCRE  default
       semantics. In particular, the way it handles newline characters in  the       semantics.  In particular, the way it handles newline characters in the
       subject  string  is  the Perl way, not the POSIX way. Note that setting       subject string is the Perl way, not the POSIX way.  Note  that  setting
       PCRE_MULTILINE has only some of the effects specified for  REG_NEWLINE.       PCRE_MULTILINE  has only some of the effects specified for REG_NEWLINE.
       It  does not affect the way newlines are matched by . (they are not) or       It does not affect the way newlines are matched by . (they are not)  or
        by a negative class such as [^a] (they are).         by a negative class such as [^a] (they are).
   
       The yield of regcomp() is zero on success, and non-zero otherwise.  The       The  yield of regcomp() is zero on success, and non-zero otherwise. The
        preg structure is filled in on success, and one member of the structure         preg structure is filled in on success, and one member of the structure
       is public: re_nsub contains the number of capturing subpatterns in  the       is  public: re_nsub contains the number of capturing subpatterns in the
        regular expression. Various error codes are defined in the header file.         regular expression. Various error codes are defined in the header file.
   
       NOTE:  If  the  yield of regcomp() is non-zero, you must not attempt to       NOTE: If the yield of regcomp() is non-zero, you must  not  attempt  to
        use the contents of the preg structure. If, for example, you pass it to         use the contents of the preg structure. If, for example, you pass it to
        regexec(), the result is undefined and your program is likely to crash.         regexec(), the result is undefined and your program is likely to crash.
   
Line 7699  COMPILING A PATTERN Line 8362  COMPILING A PATTERN
 MATCHING NEWLINE CHARACTERS  MATCHING NEWLINE CHARACTERS
   
        This area is not simple, because POSIX and Perl take different views of         This area is not simple, because POSIX and Perl take different views of
       things.  It is not possible to get PCRE to obey  POSIX  semantics,  but       things.   It  is  not possible to get PCRE to obey POSIX semantics, but
       then  PCRE was never intended to be a POSIX engine. The following table       then PCRE was never intended to be a POSIX engine. The following  table
       lists the different possibilities for matching  newline  characters  in       lists  the  different  possibilities for matching newline characters in
        PCRE:         PCRE:
   
                                  Default   Change with                                   Default   Change with
Line 7723  MATCHING NEWLINE CHARACTERS Line 8386  MATCHING NEWLINE CHARACTERS
          ^ matches \n in middle     no     REG_NEWLINE           ^ matches \n in middle     no     REG_NEWLINE
   
        PCRE's behaviour is the same as Perl's, except that there is no equiva-         PCRE's behaviour is the same as Perl's, except that there is no equiva-
       lent for PCRE_DOLLAR_ENDONLY in Perl. In both PCRE and Perl,  there  is       lent  for  PCRE_DOLLAR_ENDONLY in Perl. In both PCRE and Perl, there is
        no way to stop newline from matching [^a].         no way to stop newline from matching [^a].
   
       The   default  POSIX  newline  handling  can  be  obtained  by  setting       The  default  POSIX  newline  handling  can  be  obtained  by   setting
       PCRE_DOTALL and PCRE_DOLLAR_ENDONLY, but there is no way to  make  PCRE       PCRE_DOTALL  and  PCRE_DOLLAR_ENDONLY, but there is no way to make PCRE
        behave exactly as for the REG_NEWLINE action.         behave exactly as for the REG_NEWLINE action.
   
   
 MATCHING A PATTERN  MATCHING A PATTERN
   
       The  function  regexec()  is  called  to  match a compiled pattern preg       The function regexec() is called  to  match  a  compiled  pattern  preg
       against a given string, which is by default terminated by a  zero  byte       against  a  given string, which is by default terminated by a zero byte
       (but  see  REG_STARTEND below), subject to the options in eflags. These       (but see REG_STARTEND below), subject to the options in  eflags.  These
        can be:         can be:
   
          REG_NOTBOL           REG_NOTBOL
Line 7757  MATCHING A PATTERN Line 8420  MATCHING A PATTERN
   
          REG_STARTEND           REG_STARTEND
   
       The  string  is  considered to start at string + pmatch[0].rm_so and to       The string is considered to start at string +  pmatch[0].rm_so  and  to
       have a terminating NUL located at string + pmatch[0].rm_eo (there  need       have  a terminating NUL located at string + pmatch[0].rm_eo (there need
       not  actually  be  a  NUL at that location), regardless of the value of       not actually be a NUL at that location), regardless  of  the  value  of
       nmatch. This is a BSD extension, compatible with but not  specified  by       nmatch.  This  is a BSD extension, compatible with but not specified by
       IEEE  Standard  1003.2  (POSIX.2),  and  should be used with caution in       IEEE Standard 1003.2 (POSIX.2), and should  be  used  with  caution  in
        software intended to be portable to other systems. Note that a non-zero         software intended to be portable to other systems. Note that a non-zero
        rm_so does not imply REG_NOTBOL; REG_STARTEND affects only the location         rm_so does not imply REG_NOTBOL; REG_STARTEND affects only the location
        of the string, not how it is matched.         of the string, not how it is matched.
   
       If the pattern was compiled with the REG_NOSUB flag, no data about  any       If  the pattern was compiled with the REG_NOSUB flag, no data about any
       matched  strings  is  returned.  The  nmatch  and  pmatch  arguments of       matched strings  is  returned.  The  nmatch  and  pmatch  arguments  of
        regexec() are ignored.         regexec() are ignored.
   
        If the value of nmatch is zero, or if the value pmatch is NULL, no data         If the value of nmatch is zero, or if the value pmatch is NULL, no data
Line 7775  MATCHING A PATTERN Line 8438  MATCHING A PATTERN
   
        Otherwise,the portion of the string that was matched, and also any cap-         Otherwise,the portion of the string that was matched, and also any cap-
        tured substrings, are returned via the pmatch argument, which points to         tured substrings, are returned via the pmatch argument, which points to
       an  array  of nmatch structures of type regmatch_t, containing the mem-       an array of nmatch structures of type regmatch_t, containing  the  mem-
       bers rm_so and rm_eo. These contain the offset to the  first  character       bers  rm_so  and rm_eo. These contain the offset to the first character
       of  each  substring and the offset to the first character after the end       of each substring and the offset to the first character after  the  end
       of each substring, respectively. The 0th element of the vector  relates       of  each substring, respectively. The 0th element of the vector relates
       to  the  entire portion of string that was matched; subsequent elements       to the entire portion of string that was matched;  subsequent  elements
       relate to the capturing subpatterns of the regular  expression.  Unused       relate  to  the capturing subpatterns of the regular expression. Unused
        entries in the array have both structure members set to -1.         entries in the array have both structure members set to -1.
   
       A  successful  match  yields  a  zero  return;  various error codes are       A successful match yields  a  zero  return;  various  error  codes  are
       defined in the header file, of  which  REG_NOMATCH  is  the  "expected"       defined  in  the  header  file,  of which REG_NOMATCH is the "expected"
        failure code.         failure code.
   
   
 ERROR MESSAGES  ERROR MESSAGES
   
        The regerror() function maps a non-zero errorcode from either regcomp()         The regerror() function maps a non-zero errorcode from either regcomp()
       or regexec() to a printable message. If preg is  not  NULL,  the  error       or  regexec()  to       or  regexec()  to  a  printable message. If preg is not NULL, the error
        should have arisen from the use of that structure. A message terminated         should have arisen from the use of that structure. A message terminated
       by a binary zero is placed  in  errbuf.  The  length  of  the  message,       by  a  binary  zero  is  placed  in  errbuf. The length of the message,
       including  the  zero, is limited to errbuf_size. The yield of the func-       including the zero, is limited to errbuf_size. The yield of  the  func-
        tion is the size of buffer needed to hold the whole message.         tion is the size of buffer needed to hold the whole message.
   
   
 MEMORY USAGE  MEMORY USAGE
   
       Compiling a regular expression causes memory to be allocated and  asso-       Compiling  a regular expression causes memory to be allocated and asso-
       ciated  with  the preg structure. The function regfree() frees all such       ciated with the preg structure. The function regfree() frees  all  such
       memory, after which preg may no longer be used as  a  compiled  expres-       memory,  after  which  preg may no longer be used as a compiled expres-
        sion.         sion.
   
   
Line 7815  AUTHOR Line 8478  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 16 May 2010       Last updated: 09 January 2012
       Copyright (c) 1997-2010 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 7837  DESCRIPTION Line 8500  DESCRIPTION
        The  C++  wrapper  for PCRE was provided by Google Inc. Some additional         The  C++  wrapper  for PCRE was provided by Google Inc. Some additional
        functionality was added by Giuseppe Maxia. This brief man page was con-         functionality was added by Giuseppe Maxia. This brief man page was con-
        structed  from  the  notes  in the pcrecpp.h file, which should be con-         structed  from  the  notes  in the pcrecpp.h file, which should be con-
       sulted for further details.       sulted for further details. Note that the C++ wrapper supports only the
        original 8-bit PCRE library. There is no 16-bit support at present.
   
   
 MATCHING INTERFACE  MATCHING INTERFACE
   
       The "FullMatch" operation checks that supplied text matches a  supplied       The  "FullMatch" operation checks that supplied text matches a supplied
       pattern  exactly.  If pointer arguments are supplied, it copies matched       pattern exactly. If pointer arguments are supplied, it  copies  matched
        sub-strings that match sub-patterns into them.         sub-strings that match sub-patterns into them.
   
          Example: successful match           Example: successful match
Line 7857  MATCHING INTERFACE Line 8521  MATCHING INTERFACE
          Example: creating a temporary RE object:           Example: creating a temporary RE object:
             pcrecpp::RE("h.*o").FullMatch("hello");              pcrecpp::RE("h.*o").FullMatch("hello");
   
       You can pass in a "const char*" or a "string" for "text". The  examples       You  can pass in a "const char*" or a "string" for "text". The examples
       below  tend to use a const char*. You can, as in the different examples       below tend to use a const char*. You can, as in the different  examples
       above, store the RE object explicitly in a variable or use a  temporary       above,  store the RE object explicitly in a variable or use a temporary
       RE  object.  The  examples below use one mode or the other arbitrarily.       RE object. The examples below use one mode or  the  other  arbitrarily.
        Either could correctly be used for any of these examples.         Either could correctly be used for any of these examples.
   
        You must supply extra pointer arguments to extract matched subpieces.         You must supply extra pointer arguments to extract matched subpieces.
Line 7886  MATCHING INTERFACE Line 8550  MATCHING INTERFACE
          Example: fails because string cannot be stored in integer           Example: fails because string cannot be stored in integer
             !pcrecpp::RE("(.*)").FullMatch("ruby", &i);              !pcrecpp::RE("(.*)").FullMatch("ruby", &i);
   
       The provided pointer arguments can be pointers to  any  scalar  numeric       The  provided  point       The  provided  point
        type, or one of:         type, or one of:
   
           string        (matched piece is copied to string)            string        (matched piece is copied to string)
Line 7894  MATCHING INTERFACE Line 8558  MATCHING INTERFACE
           T             (where "bool T::ParseFrom(const char*, int)" exists)            T             (where "bool T::ParseFrom(const char*, int)" exists)
           NULL          (the corresponding matched sub-pattern is not copied)            NULL          (the corresponding matched sub-pattern is not copied)
   
       The  function returns true iff all of the following conditions are sat-       The function returns true iff all of the following conditions are  sat-
        isfied:         isfied:
   
          a. "text" matches "pattern" exactly;           a. "text" matches "pattern" exactly;
Line 7909  MATCHING INTERFACE Line 8573  MATCHING INTERFACE
             number of sub-patterns, "i"th captured sub-pattern is              number of sub-patterns, "i"th captured sub-pattern is
             ignored.              ignored.
   
       CAVEAT: An optional sub-pattern that does  not  exist  in  the  matched       CAVEAT:  An  optional  sub-pattern  that  does not exist in the matched
       string  is  assigned  the  empty  string. Therefore, the following will       string is assigned the empty  string.  Therefore,  the  following  will
        return false (because the empty string is not a valid number):         return false (because the empty string is not a valid number):
   
           int number;            int number;
           pcrecpp::RE::FullMatch("abc", "[a-z]+(\\d+)?", &number);            pcrecpp::RE::FullMatch("abc", "[a-z]+(\\d+)?", &number);
   
       The matching interface supports at most 16 arguments per call.  If  you       The  matching interface supports at most 16 arguments per call.  If you
       need    more,    consider    using    the    more   general   interface       need   more,   consider    using    the    more    general    interface
        pcrecpp::RE::DoMatch. See pcrecpp.h for the signature for DoMatch.         pcrecpp::RE::DoMatch. See pcrecpp.h for the signature for DoMatch.
   
       NOTE: Do not use no_arg, which is used internally to mark the end of  a       NOTE:  Do not use no_arg, which is used internally to mark the end of a
       list  of optional arguments, as a placeholder for missing arguments, as       list of optional arguments, as a placeholder for missing arguments,  as
        this can lead to segfaults.         this can lead to segfaults.
   
   
 QUOTING METACHARACTERS  QUOTING METACHARACTERS
   
       You can use the "QuoteMeta" operation to insert backslashes before  all       You  can use the "QuoteMeta" operation to insert backslashes before all
       potentially  meaningful  characters  in  a string. The returned string,       potentially meaningful characters in a  string.  The  returned  string,
        used as a regular expression, will exactly match the original string.         used as a regular expression, will exactly match the original string.
   
          Example:           Example:
             string quoted = RE::QuoteMeta(unquoted);              string quoted = RE::QuoteMeta(unquoted);
   
       Note that it's legal to escape a character even if it  has  no  special       Note  that  it's  legal to escape a character even if it has no special
       meaning  in  a  regular expression -- so this function does that. (This       meaning in a regular expression -- so this function  does  that.  (This
       also makes it identical to the perl function  of  the  same  name;  see       also  makes  it  identical  to  the perl function of the same name; see
       "perldoc    -f    quotemeta".)    For   example,   "1.5-2.0?"   becomes       "perldoc   -f   quotemeta".)    For   example,    "1.5-2.0?"    becomes
        "1\.5\-2\.0\?".         "1\.5\-2\.0\?".
   
   
 PARTIAL MATCHES  PARTIAL MATCHES
   
       You can use the "PartialMatch" operation when you want the  pattern  to       You  can  use the "PartialMatch" operation when you want t       You  can  use the "PartialMatch" operation when you want the pattern to
        match any substring of the text.         match any substring of the text.
   
          Example: simple search for a string:           Example: simple search for a string:
Line 7958  PARTIAL MATCHES Line 8622  PARTIAL MATCHES
   
 UTF-8 AND THE MATCHING INTERFACE  UTF-8 AND THE MATCHING INTERFACE
   
       By  default,  pattern  and text are plain text, one byte per character.       By default, pattern and text are plain text, one  byte  per  character.
       The UTF8 flag, passed to  the  constructor,  causes  both  pattern  and       The  UTF8  flag,  passed  to  the  constructor, causes both pattern and
        string to be treated as UTF-8 text, still a byte stream but potentially         string to be treated as UTF-8 text, still a byte stream but potentially
       multiple bytes per character. In practice, the text is likelier  to  be       multiple  bytes  per character. In practice, the text is likelier to be
       UTF-8  than  the pattern, but the match returned may depend on the UTF8       UTF-8 than the pattern, but the match returned may depend on  the  UTF8
       flag, so always use it when matching UTF8 text. For example,  "."  will       flag,  so  always use it when matching UTF8 text. For example, "." will
       match  one  byte normally but with UTF8 set may match up to three bytes       match one byte normally but with UTF8 set may match up to  three  bytes
        of a multi-byte character.         of a multi-byte character.
   
          Example:           Example:
Line 7983  UTF-8 AND THE MATCHING INTERFACE Line 8647  UTF-8 AND THE MATCHING INTERFACE
   
 PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE  PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE
   
       PCRE defines some modifiers to  change  the  behavior  of  the  regular       PCRE  defines  some  modifiers  to  change  the behavior of the regular
       expression   engine.  The  C++  wrapper  defines  an  auxiliary  class,       expression  engine.  The  C++  wrapper  defines  an  auxiliary   class,
       RE_Options, as a vehicle to pass such modifiers to  a  RE  class.  Cur-       RE_Options,  as  a  vehicle  to pass such modifiers to a RE class. Cur-
        rently, the following modifiers are supported:         rently, the following modifiers are supported:
   
           modifier              description               Perl corresponding            modifier              description               Perl corresponding
Line 7995  PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE Line 8659  PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE
           PCRE_DOTALL           dot matches newlines        /s            PCRE_DOTALL           dot matches newlines        /s
           PCRE_DOLLAR_ENDONLY   $ matches only at end       N/A            PCRE_DOLLAR_ENDONLY   $ matches only at end       N/A
           PCRE_EXTRA            strict escape parsing       N/A            PCRE_EXTRA            strict escape parsing       N/A
          PCRE_EXTENDED         ignore whitespaces          /x          PCRE_EXTENDED         ignore white spaces         /x
           PCRE_UTF8             handles UTF8 chars          built-in            PCRE_UTF8             handles UTF8 chars          built-in
           PCRE_UNGREEDY         reverses * and *?           N/A            PCRE_UNGREEDY         reverses * and *?           N/A
           PCRE_NO_AUTO_CAPTURE  disables capturing parens   N/A (*)            PCRE_NO_AUTO_CAPTURE  disables capturing parens   N/A (*)
   
       (*)  Both Perl and PCRE allow non capturing parentheses by means of the       (*) Both Perl and PCRE allow non capturing parentheses by means of  the
       "?:" modifier within the pattern itself. e.g. (?:ab|cd) does  not  cap-       "?:"  modifier  within the pattern itself. e.g. (?:ab|cd) does not cap-
        ture, while (ab|cd) does.         ture, while (ab|cd) does.
   
       For  a  full  account on how each modifier works, please check the PCRE       For a full account on how each modifier works, please  check  the  PCRE
        API reference page.         API reference page.
   
       For each modifier, there are two member functions whose  name  is  made       For  each  modifier,  there are two member functions whose name is made
       out  of  the  modifier  in  lowercase,  without the "PCRE_" prefix. For       out of the modifier in  lowercase,  without  the  "PCRE_"  prefix.  For
        instance, PCRE_CASELESS is handled by         instance, PCRE_CASELESS is handled by
   
          bool caseless()           bool caseless()
Line 8018  PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE Line 8682  PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE
          RE_Options & set_caseless(bool)           RE_Options & set_caseless(bool)
   
        which sets or unsets the modifier. Moreover, PCRE_EXTRA_MATCH_LIMIT can         which sets or unsets the modifier. Moreover, PCRE_EXTRA_MATCH_LIMIT can
       be  accessed  through  the  set_match_limit()  and match_limit() member       be accessed through  the  set_match_limit()  and  match_limit()  member
       functions. Setting match_limit to a non-zero value will limit the  exe-       functions.  Setting match_limit to a non-zero value will limit the exe-
       cution  of pcre to keep it from doing bad things like blowing the stack       cution of pcre to keep it from doing bad things like blowing the  stack
       or taking an eternity to return a result.  A  value  of  5000  is  good       or  taking  an  eternity  to  return  a result. A value of 5000 is good
       enough  to stop stack blowup in a 2MB thread stack. Setting match_limit       enough to stop stack blowup in a 2MB thread stack. Setting  match_limit
       to  zero  disables  match  limiting.  Alternatively,   you   can   call       to   zero   disables   match  limiting.  Alternatively,  you  can  call
       match_limit_recursion()  which uses PCRE_EXTRA_MATCH_LIMIT_RECURSION to       match_limit_recursion() which uses PCRE_EXTRA_MATCH_LIMIT_RECURSION  to
       limit how much  PCRE  recurses.  match_limit()  limits  the  number  of       limit  how  much  PCRE  recurses.  match_limit()  limits  the number of
        matches PCRE does; match_limit_recursion() limits the depth of internal         matches PCRE does; match_limit_recursion() limits the depth of internal
        recursion, and therefore the amount of stack that is used.         recursion, and therefore the amount of stack that is used.
   
       Normally, to pass one or more modifiers to a RE class,  you  declare  a       Normally,  to  pass  one or more modifiers to a RE class, you declare a
        RE_Options object, set the appropriate options, and pass this object to         RE_Options object, set the appropriate options, and pass this object to
        a RE constructor. Example:         a RE constructor. Example:
   
Line 8038  PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE Line 8702  PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE
           if (RE("HELLO", opt).PartialMatch("hello world")) ...            if (RE("HELLO", opt).PartialMatch("hello world")) ...
   
        RE_options has two constructors. The default constructor takes no argu-         RE_options has two constructors. The default constructor takes no argu-
       ments  and creates a set of flags that are off by default. The optional       ments and creates a set of flags that are off by default. The  optional
       parameter option_flags is to facilitate transfer of legacy code from  C       parameter  option_flags is to facilitate transfer of legacy code from C
        programs.  This lets you do         programs.  This lets you do
   
           RE(pattern,            RE(pattern,
Line 8053  PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE Line 8717  PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE
   
        If you are going to pass one of the most used modifiers, there are some         If you are going to pass one of the most used modifiers, there are some
        convenience functions that return a RE_Options class with the appropri-         convenience functions that return a RE_Options class with the appropri-
       ate  modifier  already  set: CASELESS(), UTF8(), MULTILINE(), DOTALL(),       ate modifier already set: CASELESS(),  UTF8(),  MULTILINE(),  DOTALL(),
        and EXTENDED().         and EXTENDED().
   
       If you need to set several options at once, and you don't  want  to  go       If  you  need  to set several options at once, and you don't want to go
       through  the pains of declaring a RE_Options object and setting several       through the pains of declaring a RE_Options object and setting  several
       options, there is a parallel method that give you such ability  on  the       options,  there  is a parallel method that give you such ability on the
       fly.  You  can  concatenate several set_xxxxx() member functions, since       fly. You can concatenate several set_xxxxx()  member  functions,  since
       each of them returns a reference to its class object. For  example,  to       each  of  them returns a reference to its class object. For example, to
       pass  PCRE_CASELESS, PCRE_EXTENDED, and PCRE_MULTILINE to a RE with one       pass PCRE_CASELESS, PCRE_EXTENDED, and PCRE_MULTILINE to a RE with  one
        statement, you may write:         statement, you may write:
   
           RE(" ^ xyz \\s+ .* blah$",            RE(" ^ xyz \\s+ .* blah$",
Line 8073  PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE Line 8737  PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE
   
 SCANNING TEXT INCREMENTALLY  SCANNING TEXT INCREMENTALLY
   
       The "Consume" operation may be useful if you want to  repeatedly  match       The  "Consume"  operation may be useful if you want to repeatedl       The  "Consume"  operation may be useful if you want to repeatedl
        regular expressions at the front of a string and skip over them as they         regular expressions at the front of a string and skip over them as they
       match. This requires use of the "StringPiece" type, which represents  a       match.  This requires use of the "StringPiece" type, which represents a
       sub-range  of  a  real  string.  Like RE, StringPiece is defined in the       sub-range of a real string. Like RE,  StringPiece  is  defined  in  the
        pcrecpp namespace.         pcrecpp namespace.
   
          Example: read lines of the form "var = value" from a string.           Example: read lines of the form "var = value" from a string.
Line 8090  SCANNING TEXT INCREMENTALLY Line 8754  SCANNING TEXT INCREMENTALLY
               ...;                ...;
             }              }
   
       Each successful call  to  "Consume"  will  set  "var/value",  and  also       Each  successful  call  to  "Consume"  will  set  "var/value", and also
        advance "input" so it points past the matched text.         advance "input" so it points past the matched text.
   
       The  "FindAndConsume"  operation  is  similar to "Consume" but does not       The "FindAndConsume" operation is similar to  "Consume"  but  does  not
       anchor your match at the beginning of  the  string.  For  example,  you       anchor  your  match  at  the  beginning of the string. For example, you
        could extract all words from a string by repeatedly calling         could extract all words from a string by repeatedly calling
   
          pcrecpp::RE("(\\w+)").FindAndConsume(&input, &word)           pcrecpp::RE("(\\w+)").FindAndConsume(&input, &word)
Line 8103  SCANNING TEXT INCREMENTALLY Line 8767  SCANNING TEXT INCREMENTALLY
 PARSING HEX/OCTAL/C-RADIX NUMBERS  PARSING HEX/OCTAL/C-RADIX NUMBERS
   
        By default, if you pass a pointer to a numeric value, the corresponding         By default, if you pass a pointer to a numeric value, the corresponding
       text is interpreted as a base-10  number.  You  can  instead  wrap  the       text  is  interpreted  as  a  base-10  number. You can instead wrap the
        pointer with a call to one of the operators Hex(), Octal(), or CRadix()         pointer with a call to one of the operators Hex(), Octal(), or CRadix()
       to interpret the text in another base. The CRadix  operator  interprets       to  interpret  the text in another base. The CRadix operator interprets
       C-style  "0"  (base-8)  and  "0x"  (base-16)  prefixes, but defaults to       C-style "0" (base-8) and  "0x"  (base-16)  prefixes,  but  defaults  to
        base-10.         base-10.
   
          Example:           Example:
Line 8121  PARSING HEX/OCTAL/C-RADIX NUMBERS Line 8785  PARSING HEX/OCTAL/C-RADIX NUMBERS
   
 REPLACING PARTS OF STRINGS  REPLACING PARTS OF STRINGS
   
       You can replace the first match of "pattern" in "str"  with  "rewrite".       You  can  replace the first match of "pattern" in "str" with "rewrite".
       Within  "rewrite",  backslash-escaped  digits (\1 to \9) can be used to       Within "rewrite", backslash-escaped digits (\1 to \9) can  be  used  to
       insert text matching corresponding parenthesized group  from  the  pat-       insert  text  matching  corresponding parenthesized group from the pat-
        tern. \0 in "rewrite" refers to the entire matching text. For example:         tern. \0 in "rewrite" refers to the entire matching text. For example:
   
          string s = "yabba dabba doo";           string s = "yabba dabba doo";
          pcrecpp::RE("b+").Replace("d", &s);           pcrecpp::RE("b+").Replace("d", &s);
   
       will  leave  "s" containing "yada dabba doo". The result is true if the       will leave "s" containing "yada dabba doo". The result is true  if  the
        pattern matches and a replacement occurs, false otherwise.         pattern matches and a replacement occurs, false otherwise.
   
       GlobalReplace is like Replace except that it replaces  all  occurrences       GlobalReplace  is  like Replace except that it replaces all occurrences
       of  the  pattern  in  the string with the rewrite. Replacements are not       of the pattern in the string with the  rewrite.  Replacements  are  not
        subject to re-matching. For example:         subject to re-matching. For example:
   
          string s = "yabba dabba doo";           string s = "yabba dabba doo";
          pcrecpp::RE("b+").GlobalReplace("d", &s);           pcrecpp::RE("b+").GlobalReplace("d", &s);
   
       will leave "s" containing "yada dada doo". It  returns  the  number  of       will  leave  "s"  containing  "yada dada doo". It returns the number of
        replacements made.         replacements made.
   
       Extract  is like Replace, except that if the pattern matches, "rewrite"       Extract is like Replace, except that if the pattern matches,  "rewrite"
       is copied into "out" (an additional argument) with substitutions.   The       is  copied into "out" (an additional argument) with substitutions.  The
       non-matching  portions  of "text" are ignored. Returns true iff a match       non-matching portions of "text" are ignored. Returns true iff  a  match
        occurred and the extraction happened successfully;  if no match occurs,         occurred and the extraction happened successfully;  if no match occurs,
        the string is left unaffected.         the string is left unaffected.
   
Line 8157  AUTHOR Line 8821  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 17 March 2009       Last updated: 08 January 2012
       Minor typo fixed: 25 July 2011 
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 8177  PCRE SAMPLE PROGRAM Line 8840  PCRE SAMPLE PROGRAM
        do not have a copy of the PCRE distribution, you can save this  listing         do not have a copy of the PCRE distribution, you can save this  listing
        to re-create pcredemo.c.         to re-create pcredemo.c.
   
       The program compiles the regular expression that is its first argument,       The  demonstration program, which uses the original PCRE 8-bit library,
       and matches it against the subject string in its  second  argument.  No       compiles the regular expression that is its first argument, and matches
       PCRE  options are set, and default character tables are used. If match-       it  against  the subject string in its second argument. No PCRE options
       ing succeeds, the program outputs  the  portion  of  the  subject  that       are set, and default character tables are used. If  matching  succeeds,
       matched, together with the contents of any captured substrings.       the  program  outputs the portion of the subject that matched, together
        with the contents of any captured substrings.
   
        If the -g option is given on the command line, the program then goes on         If the -g option is given on the command line, the program then goes on
        to check for further matches of the same regular expression in the same         to check for further matches of the same regular expression in the same
       subject  string. The logic is a little bit tricky because of the possi-       subject string. The logic is a little bit tricky because of the  possi-
       bility of matching an empty string. Comments in the code  explain  what       bility  of  matching an empty string. Comments in the code explain what
        is going on.         is going on.
   
       If  PCRE  is  installed in the standard include and library directories       If PCRE is installed in the standard include  and  library  directories
        for your operating system, you should be able to compile the demonstra-         for your operating system, you should be able to compile the demonstra-
        tion program using this command:         tion program using this command:
   
          gcc -o pcredemo pcredemo.c -lpcre           gcc -o pcredemo pcredemo.c -lpcre
   
       If  PCRE is installed elsewhere, you may need to add additional options       If PCRE is installed elsewhere, you may need to add additional  options
       to the command line. For example, on a Unix-like system that  has  PCRE       to  the  command line. For example, on a Unix-like system that has PCRE
       installed  in  /usr/local,  you  can  compile the demonstration program       installed in /usr/local, you  can  compile  the  demonstration  program
        using a command like this:         using a command like this:
   
          gcc -o pcredemo -I/usr/local/include pcredemo.c \           gcc -o pcredemo -I/usr/local/include pcredemo.c \
              -L/usr/local/lib -lpcre               -L/usr/local/lib -lpcre
   
       In a Windows environment, if you want to statically  link  the  program       In  a  Windows  environment, if you want to statica       In  a  Windows  environment, if you want to statically link the program
        against a non-dll pcre.a file, you must uncomment the line that defines         against a non-dll pcre.a file, you must uncomment the line that defines
       PCRE_STATIC before including pcre.h, because  otherwise  the  pcre_mal-       PCRE_STATIC  before  including  pcre.h, because otherwise the pcre_mal-
        loc()   and   pcre_free()   exported   functions   will   be   declared         loc()   and   pcre_free()   exported   functions   will   be   declared
        __declspec(dllimport), with unwanted results.         __declspec(dllimport), with unwanted results.
   
       Once you have compiled and linked the demonstration  program,  you  can       Once  you  have  compiled and linked the demonstration program, you can
        run simple tests like this:         run simple tests like this:
   
          ./pcredemo 'cat|dog' 'the cat sat on the mat'           ./pcredemo 'cat|dog' 'the cat sat on the mat'
          ./pcredemo -g 'cat|dog' 'the dog sat on the cat'           ./pcredemo -g 'cat|dog' 'the dog sat on the cat'
   
       Note  that  there  is  a  much  more comprehensive test program, called       Note that there is a  much  more  comprehensive  test  program,  called
       pcretest, which supports  many  more  facilities  for  testing  regular       pcretest,  which  supports  many  more  facilities  for testing regular
       expressions and the PCRE library. The pcredemo program is provided as a       expressions and both PCRE libraries. The pcredemo program  is  provided
       simple coding example.       as a simple coding example.
   
       If you try to run pcredemo when PCRE is not installed in  the  standard       If  you  try to run pcredemo when PCRE is not installed in the standard
       library  directory,  you  may  get an error like this on some operating       library directory, you may get an error like  this  on  some  operating
        systems (e.g. Solaris):         systems (e.g. Solaris):
   
         ld.so.1: a.out: fatal: libpcre.so.0: open failed:  No  such  file  or         ld.so.1:  a.out:  fatal:  libpcre.so.0:  open failed: No such file or
        directory         directory
   
       This  is  caused  by the way shared library support works on those sys-       This is caused by the way shared library support works  on  those  sys-
        tems. You need to add         tems. You need to add
   
          -R/usr/local/lib           -R/usr/local/lib
Line 8244  AUTHOR Line 8908  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 17 November 2010       Last updated: 10 January 2012
       Copyright (c) 1997-2010 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
 PCRELIMITS(3)                                                    PCRELIMITS(3)  PCRELIMITS(3)                                                    PCRELIMITS(3)
   
Line 8259  SIZE AND OTHER LIMITATIONS Line 8923  SIZE AND OTHER LIMITATIONS
        There  are some size limitations in PCRE but it is hoped that they will         There  are some size limitations in PCRE but it is hoped that they will
        never in practice be relevant.         never in practice be relevant.
   
       The maximum length of a compiled pattern is 65539 (sic) bytes  if  PCRE       The maximum length of a compiled  pattern  is  approximately  64K  data
       is compiled with the default internal linkage size of 2. If you want to       units  (bytes  for  the  8-bit  library,  16-bit  units  for the 16-bit
       process regular expressions that are truly enormous,  you  can  compile       library) if PCRE is compiled with the default internal linkage size  of
       PCRE  with  an  internal linkage size of 3 or 4 (see the README file in       2  bytes.  If  you  want  to process regular expressions that are truly
       the source distribution and the pcrebuild documentation  for  details).       enormous, you can compile PCRE with an internal linkage size of 3 or  4
       In  these  cases the limit is substantially larger.  However, the speed       (when  building  the  16-bit  library,  3  is rounded up to 4). See the
       of execution is slower.       README file in the source distribution and the pcrebuild  documentation
        for  details.  In  these cases the limit is substantially larger.  How-
        ever, the speed of execution is slower.
   
        All values in repeating quantifiers must be less than 65536.         All values in repeating quantifiers must be less than 65536.
   
Line 8281  SIZE AND OTHER LIMITATIONS Line 8947  SIZE AND OTHER LIMITATIONS
        The maximum length of name for a named subpattern is 32 characters, and         The maximum length of name for a named subpattern is 32 characters, and
        the maximum number of named subpatterns is 10000.         the maximum number of named subpatterns is 10000.
   
          The maximum length of a  name  in  a  (*MARK),  (*PRUNE),  (*SKIP),  or
          (*THEN)  verb  is  255  for  the 8-bit library and 65535 for the 16-bit
          library.
   
        The maximum length of a subject string is the largest  positive  number         The maximum length of a subject string is the largest  positive  number
        that  an integer variable can hold. However, when using the traditional         that  an integer variable can hold. However, when using the traditional
        matching function, PCRE uses recursion to handle subpatterns and indef-         matching function, PCRE uses recursion to handle subpatterns and indef-
Line 8298  AUTHOR Line 8968  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 30 November 2011       Last updated: 04 May 2012
       Copyright (c) 1997-2011 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Line 8312  NAME Line 8982  NAME
   
 PCRE DISCUSSION OF STACK USAGE  PCRE DISCUSSION OF STACK USAGE
   
       When  you call pcre_exec(), it makes use of an internal function called       When  you  call  pcre[16]_exec(),  it makes use of an internal function
       match(). This calls itself recursively at branch points in the pattern,       called match(). This calls itself recursively at branch points  in  the
       in  order to remember the state of the match so that it can back up and       pattern,  in  order  to  remember the state of the match so that it can
       try a different alternative if the first one fails.  As  matching  pro-       back up and try a different alternative if  the  first  one  fails.  As
       ceeds  deeper  and deeper into the tree of possibilities, the recursion       matching proceeds deeper and deeper into the tree of possibilities, the
       depth increases. The match() function is also called in  other  circum-       recursion depth increases. The match() function is also called in other
       stances,  for example, whenever a parenthesized sub-pattern is entered,       circumstances,  for  example,  whenever  a parenthesized sub-pattern is
       and in certain cases of repetition.       entered, and in certain cases of repetition.
   
        Not all calls of match() increase the recursion depth; for an item such         Not all calls of match() increase the recursion depth; for an item such
        as  a* it may be called several times at the same level, after matching         as  a* it may be called several times at the same level, after matching
Line 8328  PCRE DISCUSSION OF STACK USAGE Line 8998  PCRE DISCUSSION OF STACK USAGE
        result of the current call (a "tail recursion"), the function  is  just         result of the current call (a "tail recursion"), the function  is  just
        restarted instead.         restarted instead.
   
       The  above  comments apply when pcre_exec() is run in its normal inter-       The  above  comments  apply  when  pcre[16]_exec() is run in its normal
       pretive manner. If the pattern was studied with the PCRE_STUDY_JIT_COM-       interpretive  manner.   If   the   pattern   was   studied   with   the
       PILE option, and just-in-time compiling was successful, and the options       PCRE_STUDY_JIT_COMPILE  option, and just-in-time compiling was success-
       passed to pcre_exec() were not incompatible, the matching process  uses       ful, and the options passed to pcre[16]_exec() were  not  incompatible,
       the  JIT-compiled  code  instead of the match() function. In this case,       the  matching process uses the JIT-compiled code instead of the match()
       the memory requirements are handled entirely differently. See the pcre-       function. In this case, the memory requirements  are  handled  entirely
       jit documentation for details.       differently. See the pcrejit documentation for details.
   
       The pcre_dfa_exec() function operates in an entirely different way, and       The pcre[16]_dfa_exec() function operates in an entirely different way,
       uses recursion only when there is a  regular  expression  recursion  or       and uses recursion only when there is a regular expression recursion or
        subroutine  call in the pattern. This includes the processing of asser-         subroutine  call in the pattern. This includes the processing of asser-
        tion and "once-only" subpatterns, which  are  handled  like  subroutine         tion and "once-only" subpatterns, which  are  handled  like  subroutine
        calls.  Normally,  these are never very deep, and the limit on the com-         calls.  Normally,  these are never very deep, and the limit on the com-
       plexity of pcre_dfa_exec() is controlled by the amount of workspace  it       plexity of pcre[16]_dfa_exec() is controlled by the amount of workspace
       is  given. However, it is possible to write patterns with runaway infi-       it  is  given.   However, it is possible to write patterns with runaway
       nite recursions; such patterns will cause pcre_dfa_exec() to run out of       infinite recursions; such patterns will  cause  pcre[16]_dfa_exec()  to
       stack. At present, there is no protection against this.       run out of stack. At present, there is no protection against this.
   
       The comments that follow do NOT apply to pcre_dfa_exec(); they are rel-       The  comments that follow do NOT apply to pcre[16]_dfa_exec(); they are
       evant only for pcre_exec() without the JIT optimization.       relevant only for pcre[16]_exec() without the JIT optimization.
   
   Reducing pcre_exec()'s stack usage   Reducing pcre[16]_exec()'s stack usage
   
        Each time that match() is actually called recursively, it  uses  memory         Each time that match() is actually called recursively, it  uses  memory
        from  the  process  stack.  For certain kinds of pattern and data, very         from  the  process  stack.  For certain kinds of pattern and data, very
Line 8382  PCRE DISCUSSION OF STACK USAGE Line 9052  PCRE DISCUSSION OF STACK USAGE
        ing long subject strings is to write repeated parenthesized subpatterns         ing long subject strings is to write repeated parenthesized subpatterns
        to match more than one character whenever possible.         to match more than one character whenever possible.
   
   Compiling PCRE to use heap instead of stack for pcre_exec()   Compiling PCRE to use heap instead of stack for pcre[16]_exec()
   
        In  environments  where  stack memory is constrained, you might want to         In  environments  where  stack memory is constrained, you might want to
        compile PCRE to use heap memory instead of stack for remembering  back-         compile PCRE to use heap memory instead of stack for remembering  back-
       up  points  when  pcre_exec()  is running. This makes it run a lot more       up points when pcre[16]_exec() is running. This makes it run a lot more
        slowly, however.  Details of how to do this are given in the  pcrebuild         slowly, however.  Details of how to do this are given in the  pcrebuild
        documentation. When built in this way, instead of using the stack, PCRE         documentation. When built in this way, instead of using the stack, PCRE
        obtains and frees memory by calling the functions that are  pointed  to         obtains and frees memory by calling the functions that are  pointed  to
       by  the  pcre_stack_malloc  and  pcre_stack_free variables. By default,       by  the  pcre[16]_stack_malloc  and  pcre[16]_stack_free  variables. By
       these point to malloc() and free(), but you can replace the pointers to       default, these point to malloc() and free(), but you  can  replace  the
       cause  PCRE to use your own functions. Since the block sizes are always       pointers to cause PCRE to use your own functions. Since the block sizes
       the same, and are always freed in reverse order, it may be possible  to       are always the same, and are always freed in reverse order, it  may  be
       implement  customized  memory handlers that are more efficient than the       possible  to  implement  customized memory handlers that are more effi-
       standard functions.       cient than the standard functions.
   
   Limiting pcre_exec()'s stack usage   Limiting pcre[16]_exec()'s stack usage
   
        You can set limits on the number of times that match() is called,  both         You can set limits on the number of times that match() is called,  both
       in  total  and recursively. If a limit is exceeded, pcre_exec() returns       in  total  and  recursively.  If  a  limit is exceeded, pcre[16]_exec()
       an error code. Setting suitable limits should prevent it  from  running       returns an error code. Setting suitable limits should prevent  it  from
       out  of  stack.  The  default  values of the limits are very large, and       running  out of stack. The default values of the limits are very large,
       unlikely ever to operate. They can be changed when PCRE is  built,  and       and unlikely ever to operate. They can be changed when PCRE  is  built,
       they  can  also be set when pcre_exec() is called. For details of these       and they can also be set when pcre[16]_exec() is called. For details of
       interfaces, see the pcrebuild documentation and the  section  on  extra       these interfaces, see the pcrebuild documentation and  the  section  on
       data for pcre_exec() in the pcreapi documentation.       extra data for pcre[16]_exec() in the pcreapi documentation.
   
        As a very rough rule of thumb, you should reckon on about 500 bytes per         As a very rough rule of thumb, you should reckon on about 500 bytes per
        recursion. Thus, if you want to limit your  stack  usage  to  8Mb,  you         recursion. Thus, if you want to limit your  stack  usage  to  8Mb,  you
Line 8417  PCRE DISCUSSION OF STACK USAGE Line 9087  PCRE DISCUSSION OF STACK USAGE
        option (-S) that can be used to increase the size of its stack. As long         option (-S) that can be used to increase the size of its stack. As long
        as the stack is large enough, another option (-M) can be used  to  find         as the stack is large enough, another option (-M) can be used  to  find
        the  smallest  limits  that allow a particular pattern to match a given         the  smallest  limits  that allow a particular pattern to match a given
       subject string. This is done by  calling  pcre_exec()  repeatedly  with       subject string. This is done by calling pcre[16]_exec() repeatedly with
        different limits.         different limits.
   
      Obtaining an estimate of stack usage
   
          The  actual  amount  of  stack used per recursion can vary quite a lot,
          depending on the compiler that was used to build PCRE and the optimiza-
          tion or debugging options that were set for it. The rule of thumb value
          of 500 bytes mentioned above may be larger  or  smaller  than  what  is
          actually needed. A better approximation can be obtained by running this
          command:
   
            pcretest -m -C
   
          The -C option causes pcretest to output information about  the  options
          with which PCRE was compiled. When -m is also given (before -C), infor-
          mation about stack use is given in a line like this:
   
            Match recursion uses stack: approximate frame size = 640 bytes
   
          The value is approximate because some recursions need a bit more (up to
          perhaps 16 more bytes).
   
          If  the  above  command  is given when PCRE is compiled to use the heap
          instead of the stack for recursion, the value that  is  output  is  the
          size of each block that is obtained from the heap.
   
    Changing stack size in Unix-like systems     Changing stack size in Unix-like systems
   
        In  Unix-like environments, there is not often a problem with the stack         In  Unix-like environments, there is not often a problem with the stack
Line 8440  PCRE DISCUSSION OF STACK USAGE Line 9134  PCRE DISCUSSION OF STACK USAGE
   
        This reads the current limits (soft and hard) using  getrlimit(),  then         This reads the current limits (soft and hard) using  getrlimit(),  then
        attempts  to  increase  the  soft limit to 100Mb using setrlimit(). You         attempts  to  increase  the  soft limit to 100Mb using setrlimit(). You
       must do this before calling pcre_exec().       must do this before calling pcre[16]_exec().
   
    Changing stack size in Mac OS X     Changing stack size in Mac OS X
   
Line 8459  AUTHOR Line 9153  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 26 August 2011       Last updated: 21 January 2012
       Copyright (c) 1997-2011 University of Cambridge.       Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
   
Removed from v.1.1.1.1  
changed lines
  Added in v.1.1.1.3

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>