[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.2 and 1.1.1.3

version 1.1.1.2, 2012/02/21 23:50:25 version 1.1.1.3, 2012/10/09 09:19:17
Line 367  OPTION NAMES Line 367  OPTION NAMES
        There   are   two   new   general   option   names,   PCRE_UTF16    and         There   are   two   new   general   option   names,   PCRE_UTF16    and
        PCRE_NO_UTF16_CHECK,     which     correspond    to    PCRE_UTF8    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         PCRE_NO_UTF8_CHECK in the 8-bit library. In  fact,  these  new  options
       define the same bits in the options word.       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       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       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       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.         given to pcre16_config(), the result is the PCRE_ERROR_BADOPTION error.
   
   
 CHARACTER CODES  CHARACTER CODES
   
       In 16-bit mode, when  PCRE_UTF16  is  not  set,  character  values  are       In  16-bit  mode,  when  PCRE_UTF16  is  not  set, charact       In  16-bit  mode,  when  PCRE_UTF16  is  not  set, charact
        treated in the same way as in 8-bit, non UTF-8 mode, except, of course,         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       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       types for characters less than 0xff can therefore be influenced by  the
       locale in the same way as before.  Characters greater  than  0xff  have       locale  in  the  same way as before.  Characters greater than 0xff have
        only one case, and no "type" (such as letter or digit).         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       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       0x10ffff,  with  the  exception of values in the range 0xd800 to 0xdfff
       because  those  are "surrogate" values that are used in pairs to encode       because those are "surrogate" values that are used in pairs  to  encode
        values greater than 0xffff.         values greater than 0xffff.
   
       A UTF-16 string can indicate its endianness by special code knows as  a       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         byte-order mark (BOM). The PCRE functions do not handle this, expecting
       strings  to  be  in  host  byte  order.  A  utility   function   called       strings   to   be  in  host  byte  order.  A  utility  function  called
       pcre16_utf16_to_host_byte_order()  is  provided  to help with this (see       pcre16_utf16_to_host_byte_order() is provided to help  with  this  (see
        above).         above).
   
   
 ERROR NAMES  ERROR NAMES
   
       The errors PCRE_ERROR_BADUTF16_OFFSET and PCRE_ERROR_SHORTUTF16  corre-       The  errors PCRE_ERROR_BADUTF16_OFFSET and PCRE_ERROR_SHORTUTF16 corre-
       spond  to  their  8-bit  counterparts.  The error PCRE_ERROR_BADMODE is       spond to their 8-bit  counterparts.  The  error  PCRE_ERROR_BADMODE  is
       given when a compiled pattern is passed to a  function  that  processes       given  when  a  compiled pattern is passed to a function that processes
       patterns  in  the  other  mode, for example, if a pattern compiled with       patterns in the other mode, for example, if  a  pattern  compiled  with
        pcre_compile() is passed to pcre16_exec().         pcre_compile() is passed to pcre16_exec().
   
       There are new error codes whose names  begin  with  PCRE_UTF16_ERR  for       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       invalid UTF-16 strings, corresponding to the  PCRE_UTF8_ERR  codes  for
       UTF-8 strings that are described in the section entitled "Reason  codes       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       for invalid UTF-8 strings" in the main pcreapi page. The UTF-16  errors
        are:         are:
   
          PCRE_UTF16_ERR1  Missing low surrogate at end of string           PCRE_UTF16_ERR1  Missing low surrogate at end of string
Line 418  ERROR NAMES Line 419  ERROR NAMES
   
 ERROR TEXTS  ERROR TEXTS
   
       If there is an error while compiling a pattern, the error text that  is       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       passed back by pcre16_compile() or pcre16_compile2() is still an  8-bit
        character string, zero-terminated.         character string, zero-terminated.
   
   
 CALLOUTS  CALLOUTS
   
       The subject and mark fields in the callout block that is  passed  to  a       The  subject  and  mark fields in the callout block that       The  subject  and  mark fields in the callout block that is passed to a
        callout function point to 16-bit vectors.         callout function point to 16-bit vectors.
   
   
 TESTING  TESTING
   
       The  pcretest  program continues to operate with 8-bit input and output       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       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-         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         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       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         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.         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       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       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.         16-bit libraries has been built, and runs the tests appropriately.
   
   
 NOT SUPPORTED IN 16-BIT MODE  NOT SUPPORTED IN 16-BIT MODE
   
        Not all the features of the 8-bit library are available with the 16-bit         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.  The  C++  and  POSIX wrapper functions support only the 8-bit
        library, and the pcregrep program is at present 8-bit only.         library, and the pcregrep program is at present 8-bit only.
   
   
Line 460  AUTHOR Line 461  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 08 January 2012       Last updated: 14 April 2012
        Copyright (c) 1997-2012 University of Cambridge.         Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
Line 567  UTF-8 and UTF-16 SUPPORT Line 568  UTF-8 and UTF-16 SUPPORT
        tern compiling functions.         tern compiling functions.
   
        If you set --enable-utf when compiling in an EBCDIC  environment,  PCRE         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 runtime       expects  its  input  to be either ASCII or UTF-8 (depending on the run-
       option). It is not possible to support both EBCDIC and UTF-8  codes  in       time option). It is not possible to support both EBCDIC and UTF-8 codes
       the  same  version  of  the  library.  Consequently,  --enable-utf  and       in  the  same  version  of  the library. Consequently, --enable-utf and
        --enable-ebcdic are mutually exclusive.         --enable-ebcdic are mutually exclusive.
   
   
Line 760  CREATING CHARACTER TABLES AT BUILD TIME Line 761  CREATING CHARACTER TABLES AT BUILD TIME
        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".)
   
   
Line 1310  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 1511  COMPILING A PATTERN Line 1512  COMPILING A PATTERN
        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() returns NULL, and
Line 1624  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 1641  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 1726  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). For the 8-bit library, the last two are         (paragraph  separator, U+2029). For the 8-bit library, the last two are
        recognized only in UTF-8 mode.         recognized only in UTF-8 mode.
Line 1740  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 1893  COMPILATION ERROR CODES Line 1894  COMPILATION ERROR CODES
          72  too many forward references           72  too many forward references
          73  disallowed Unicode code point (>= 0xd800 && <= 0xdfff)           73  disallowed Unicode code point (>= 0xd800 && <= 0xdfff)
          74  invalid UTF-16 string (specifically UTF-16)           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 1921  STUDYING A PATTERN Line 1924  STUDYING A PATTERN
        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. 
   
            PCRE_STUDY_JIT_COMPILE
            PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE
            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         JIT compilation is a heavyweight optimization. It can  take  some  time
        for  patterns  to  be analyzed, and for one-off matches and simple pat-         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         terns the benefit of faster execution might be offset by a much  slower
Line 1947  STUDYING A PATTERN Line 1956  STUDYING A PATTERN
        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):
Line 1981  STUDYING A PATTERN Line 1990  STUDYING A PATTERN
        which to start matching. (In 16-bit mode, the bitmap is used for 16-bit         which to start matching. (In 16-bit mode, the bitmap is used for 16-bit
        values less than 256.)         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 2055  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 pcre_info() function, which was removed from the       tern. It replaces the pcre_info() function, which was removed from  the
        library at version 8.30, after more than 10 years of obsolescence.         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
Line 2073  INFORMATION ABOUT A PATTERN Line 2081  INFORMATION ABOUT A PATTERN
                                    endianness                                     endianness
          PCRE_ERROR_BADOPTION      the value of what was invalid           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. The  endi-       an  simple check against passing an arbitrary memory pointer. The endi-
        anness error can occur if a compiled pattern is saved and reloaded on a         anness error can occur if a compiled pattern is saved and reloaded on a
       different host. Here is a typical call of  pcre_fullinfo(),  to  obtain       different  host.  Here  is a typical call of pcre_fullinfo(), to obtain
        the length of the compiled pattern:         the length of the compiled pattern:
   
          int rc;           int rc;
Line 2087  INFORMATION ABOUT A PATTERN Line 2095  INFORMATION ABOUT A PATTERN
            PCRE_INFO_SIZE,   /* what is required */             PCRE_INFO_SIZE,   /* what is required */
            &length);         /* where to put the data */             &length);         /* where to put the data */
   
       The  possible  values for the third argument are defined in pcre.h, and       The possible values for the third argument are defined in  pcre.h,  and
        are as follows:         are as follows:
   
          PCRE_INFO_BACKREFMAX           PCRE_INFO_BACKREFMAX
   
       Return the number of the highest back reference  in  the  pattern.  The       Return  the  number  of  the highest back reference in the pattern. The
       fourth  argument  should  point to an int variable. Zero is returned if       fourth argument should point to an int variable. Zero  is  returned  if
        there are no back references.         there are no back references.
   
          PCRE_INFO_CAPTURECOUNT           PCRE_INFO_CAPTURECOUNT
   
       Return the number of capturing subpatterns in the pattern.  The  fourth       Return  the  number of capturing subpatterns in the pattern. The fourth
        argument should point to an int variable.         argument should point to an int variable.
   
          PCRE_INFO_DEFAULT_TABLES           PCRE_INFO_DEFAULT_TABLES
   
       Return  a pointer to the internal default character tables within PCRE.       Return a pointer to the internal default character tables within  PCRE.
       The fourth argument should point to an unsigned char *  variable.  This       The  fourth  argument should point to an unsigned char * variable. This
        information call is provided for internal use by the pcre_study() func-         information call is provided for internal use by the pcre_study() func-
       tion. External callers can cause PCRE to use  its  internal  tables  by       tion.  External  callers  can  cause PCRE to use its internal tables by
        passing a NULL table pointer.         passing a NULL table pointer.
   
          PCRE_INFO_FIRSTBYTE           PCRE_INFO_FIRSTBYTE
   
        Return information about the first data unit of any matched string, for         Return information about the first data unit of any matched string, for
       a non-anchored pattern. (The name of this option refers  to  the  8-bit       a  non-anchored  pattern.  (The name of this option refers to the 8-bit
       library,  where data units are bytes.) The fourth argument should point       library, where data units are bytes.) The fourth argument should  point
        to an int variable.         to an int variable.
   
       If there is a fixed first value, for example, the  letter  "c"  from  a       If  there  is  a  fixed first value, for example, the letter "c" from a
       pattern  such  as (cat|cow|coyote), its value is returned. In the 8-bit       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       library,  the  value is always less than 256; in the 16-bit library the
        value can be up to 0xffff.         value can be up to 0xffff.
   
        If there is no fixed first value, and if either         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
   
        (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not         (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not
        set (if it were set, the pattern would be anchored),         set (if it were set, the pattern would be anchored),
   
       -1  is  returned, indicating that the pattern matches only at the start       -1 is returned, indicating that the pattern matches only at  the  start
       of a subject string or after any newline within the  string.  Otherwise       of  a  subject string or after any newline within the string. Otherwise
        -2 is returned. For anchored patterns, -2 is returned.         -2 is returned. For anchored patterns, -2 is returned.
   
          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 values for the first data  unit       256-bit  table indicating a fixed set of values for the first data unit
       in  any  matching string, a pointer to the table is returned. Otherwise       in any matching string, a pointer to the table is  returned.  Otherwise
       NULL is returned. The fourth argument should point to an unsigned  char       NULL  is returned. The fourth argument should point to an unsigned char
        * variable.         * variable.
   
          PCRE_INFO_HASCRORLF           PCRE_INFO_HASCRORLF
   
       Return  1  if  the  pattern  contains any explicit matches for CR or LF       Return 1 if the pattern contains any explicit  matches  for  CR  or  LF
       characters, otherwise 0. The fourth argument should  point  to  an  int       characters,  otherwise  0.  The  fourth argument should point to an int
       variable.  An explicit match is either a literal CR or LF character, or       variable. An explicit match is either a literal CR or LF character,  or
        \r or \n.         \r or \n.
   
          PCRE_INFO_JCHANGED           PCRE_INFO_JCHANGED
   
       Return 1 if the (?J) or (?-J) option setting is used  in  the  pattern,       Return  1  if  the (?J) or (?-J) option setting is used in the pattern,
       otherwise  0. The fourth argument should point to an int variable. (?J)       otherwise 0. The fourth argument should point to an int variable.  (?J)
        and (?-J) set and unset the local PCRE_DUPNAMES option, respectively.         and (?-J) set and unset the local PCRE_DUPNAMES option, respectively.
   
          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 data unit that must exist  in       Return  the value of the rightmost literal data unit that must exist in
       any  matched  string, other than at its start, if such a value 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 value, -1 is returned. For anchored patterns, a last literal         is no such value, -1 is returned. For anchored patterns, a last literal
       value 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
Line 2383  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2398  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
        In  the  16-bit  version  of  this  structure,  the mark field has type         In  the  16-bit  version  of  this  structure,  the mark field has type
        "PCRE_UCHAR16 **".         "PCRE_UCHAR16 **".
   
       The flags field is a bitmap that specifies which of  the  other  fields       The flags field is used to specify which of the other fields  are  set.
       are set. The flag bits are:       The flag bits are:
   
         PCRE_EXTRA_STUDY_DATA         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 2414  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 2436  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 2477  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2492  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
        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 2608  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 2642  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 pcreunicode page.  If  an  invalid       points to the start of a UTF-8 character. There is a  discussion  about
       sequence   of   bytes   is   found,   pcre_exec()   returns  the  error       the  validity  of  UTF-8 strings in the pcreunicode page. If an invalid
        sequence  of  bytes   is   found,   pcre_exec()   returns   the   error
        PCRE_ERROR_BADUTF8 or, if PCRE_PARTIAL_HARD is set and the problem is a         PCRE_ERROR_BADUTF8 or, if PCRE_PARTIAL_HARD is set and the problem is a
        truncated character at the end of the subject, PCRE_ERROR_SHORTUTF8. In         truncated character at the end of the subject, PCRE_ERROR_SHORTUTF8. In
       both cases, information about the precise nature of the error may  also       both  cases, information about the precise nature of the error may also
       be  returned (see the descriptions of these errors in the section enti-       be returned (see the descriptions of these errors in the section  enti-
       tled Error return values from pcre_exec() below).  If startoffset  con-       tled  Error return values from pcre_exec() below).  If startoffset con-
        tains a value that does not point to the start of a UTF-8 character (or         tains a value that does not point to the start of a UTF-8 character (or
        to the end of the subject), 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
       PCRE_NO_UTF8_CHECK option when calling pcre_exec(). You might  want  to       PCRE_NO_UTF8_CHECK  option  when calling pcre_exec(). You might want to
       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 character (or the end of  the  subject).  When       points  to  the  start of a character (or the end of the subject). When
        PCRE_NO_UTF8_CHECK is set, the effect of passing an invalid string as a         PCRE_NO_UTF8_CHECK is set, the effect of passing an invalid string as a
       subject or an invalid value of startoffset is undefined.  Your  program       subject  or  an invalid value of startoffset is undefined. Your program
        may crash.         may crash.
   
          PCRE_PARTIAL_HARD           PCRE_PARTIAL_HARD
          PCRE_PARTIAL_SOFT           PCRE_PARTIAL_SOFT
   
       These  options turn on the partial matching feature. For backwards com-       These options turn on the partial matching feature. For backwards  com-
       patibility, PCRE_PARTIAL is a synonym for PCRE_PARTIAL_SOFT. A  partial       patibility,  PCRE_PARTIAL is a synonym for PCRE_PARTIAL_SOFT. A partial
       match  occurs if the end of the subject string is reached successfully,       match occurs if the end of the subject string is reached  successfully,
       but there are not enough subject characters to complete the  match.  If       but  there  are not enough subject characters to complete the match. If
        this happens when PCRE_PARTIAL_SOFT (but not PCRE_PARTIAL_HARD) is set,         this happens when PCRE_PARTIAL_SOFT (but not PCRE_PARTIAL_HARD) is set,
       matching continues by testing any remaining alternatives.  Only  if  no       matching  continues  by  testing any remaining alternatives. Only if no
       complete  match  can be found is PCRE_ERROR_PARTIAL returned instead of       complete match can be found is PCRE_ERROR_PARTIAL returned  instead  of
       PCRE_ERROR_NOMATCH. In other words,  PCRE_PARTIAL_SOFT  says  that  the       PCRE_ERROR_NOMATCH.  In  other  words,  PCRE_PARTIAL_SOFT says that the
       caller  is  prepared to handle a partial match, but only if no complete       caller is prepared to handle a partial match, but only if  no  complete
        match can be found.         match can be found.
   
       If PCRE_PARTIAL_HARD is set, it overrides  PCRE_PARTIAL_SOFT.  In  this       If  PCRE_PARTIAL_HARD  is  set, it overrides PCRE_PARTIAL_SOFT. In this
       case,  if  a  partial  match  is found, pcre_exec() immediately returns       case, if a partial match  is  found,  pcre_exec()  immediately  returns
       PCRE_ERROR_PARTIAL, without  considering  any  other  alternatives.  In       PCRE_ERROR_PARTIAL,  without  considering  any  other  alternatives. In
       other  words, when PCRE_PARTIAL_HARD is set, a partial match is consid-       other words, when PCRE_PARTIAL_HARD is set, a partial match is  consid-
        ered to be more important that an alternative complete match.         ered to be more important that an alternative complete match.
   
       In both cases, the portion of the string that was  inspected  when  the       In  both  cases,  the portion of the string that was inspect       In  both  cases,  the portion of the string that was inspect
        partial match was found is set as the first matching string. There is a         partial match was found is set as the first matching string. There is a
       more detailed discussion of partial and  multi-segment  matching,  with       more  detailed  discussion  of partial and multi-segment matching, with
        examples, in the pcrepartial documentation.         examples, in the pcrepartial documentation.
   
    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,
        and this is by far the most common case. In UTF-8 mode, the byte offset         and this is by far the most common case. In UTF-8 mode, the byte offset
       must  point  to  the start of a UTF-8 character (or the end of the sub-       must point to the start of a UTF-8 character (or the end  of  the  sub-
       ject). Unlike the pattern string, the subject may contain  binary  zero       ject).  Unlike  the pattern string, the subject may contain binary zero
        bytes.         bytes.
   
       A  non-zero  starting offset is useful when searching for another match       A non-zero starting offset is useful when searching for  another  match
       in the same subject by calling pcre_exec() again after a previous  suc-       in  the same subject by calling pcre_exec() again after a previous suc-
       cess.   Setting  startoffset differs from just passing over a shortened       cess.  Setting startoffset differs from just passing over  a  shortened
       string and setting PCRE_NOTBOL in the case of  a  pattern  that  begins       string  and  setting  PCRE_NOTBOL  in the case of a pattern that begins
        with any kind of lookbehind. For example, consider the pattern         with any kind of lookbehind. For example, consider the pattern
   
          \Biss\B           \Biss\B
   
       which  finds  occurrences  of "iss" in the middle of words. (\B matches       which finds occurrences of "iss" in the middle of  words.  (\B  matches
       only if the current position in the subject is not  a  word  boundary.)       only  if  the  current position in the subject is not a word boundary.)
       When  applied  to the string "Mississipi" the first call to pcre_exec()       When applied to the string "Mississipi" the first call  to  pcre_exec()
       finds the first occurrence. If pcre_exec() is called  again  with  just       finds  the  first  occurrence. If pcre_exec() is called again with just
       the  remainder  of  the  subject,  namely  "issipi", it does not match,       the remainder of the subject,  namely  "issipi",  it  does  not  match,
        because \B is always false at the start of the subject, which is deemed         because \B is always false at the start of the subject, which is deemed
       to  be  a  word  boundary. However, if pcre_exec() is passed the entire       to be a word boundary. However, if pcre_exec()  is  passed  the  entire
        string again, but with startoffset set to 4, it finds the second occur-         string again, but with startoffset set to 4, it finds the second occur-
       rence  of "iss" because it is able to look behind the starting point to       rence of "iss" because it is able to look behind the starting point  to
        discover that it is preceded by a letter.         discover that it is preceded by a letter.
   
       Finding all the matches in a subject is tricky  when  the  pattern  can       Finding  all  the  matches  in a subject is tricky when the pattern can
        match an empty string. It is possible to emulate Perl's /g behaviour by         match an empty string. It is possible to emulate Perl's /g behaviour by
       first  trying  the  match  again  at  the   same   offset,   with   the       first   trying   the   match   again  at  the  same  offset,  with  the
       PCRE_NOTEMPTY_ATSTART  and  PCRE_ANCHORED  options,  and  then  if that       PCRE_NOTEMPTY_ATSTART and  PCRE_ANCHORED  options,  and  then  if  that
       fails, advancing the starting  offset  and  trying  an  ordinary  match       fails,  advancing  the  starting  offset  and  trying an ordinary match
        again. There is some code that demonstrates how to do this in the pcre-         again. There is some code that demonstrates how to do this in the pcre-
        demo sample program. In the most general case, you have to check to see         demo sample program. In the most general case, you have to check to see
       if  the newline convention recognizes CRLF as a newline, and if so, and       if the newline convention recognizes CRLF as a newline, and if so,  and
        the current character is CR followed by LF, advance the starting offset         the current character is CR followed by LF, advance the starting offset
        by two characters instead of one.         by two characters instead of one.
   
       If  a  non-zero starting offset is passed when the pattern is anchored,       If a non-zero starting offset is passed when the pattern  is  anchored,
        one attempt to match at the given offset is made. This can only succeed         one attempt to match at the given offset is made. This can only succeed
       if  the  pattern  does  not require the match to be at the start of the       if the pattern does not require the match to be at  the  start  of  the
        subject.         subject.
   
    How pcre_exec() returns captured substrings     How pcre_exec() returns captured substrings
   
       In general, a pattern matches a certain portion of the subject, and  in       In  general, a pattern matches a certain portion of the subject, and in
       addition,  further  substrings  from  the  subject may be picked out by       addition, further substrings from the subject  may  be  picked  out  by
       parts of the pattern. Following the usage  in  Jeffrey  Friedl's  book,       parts  of  the  pattern.  Following the usage in Jeffrey Friedl's book,
       this  is  called "capturing" in what follows, and the phrase "capturing       this is called "capturing" in what follows, and the  phrase  "capturing
       subpattern" is used for a fragment of a pattern that picks out  a  sub-       subpattern"  is  used for a fragment of a pattern that picks out a sub-
       string.  PCRE  supports several other kinds of parenthesized subpattern       string. PCRE supports several other kinds of  parenthesized  subpattern
        that do not cause substrings to be captured.         that do not cause substrings to be captured.
   
        Captured substrings are returned to the caller via a vector of integers         Captured substrings are returned to the caller via a vector of integers
       whose  address is passed in ovector. The number of elements in the vec-       whose address is passed in ovector. The number of elements in the  vec-
       tor is passed in ovecsize, which must be a non-negative  number.  Note:       tor  is  passed in ovecsize, which must be a non-negative number. Note:
        this argument is NOT the size of ovector in bytes.         this argument is NOT the size of ovector in bytes.
   
       The  first  two-thirds of the vector is used to pass back captured sub-       The first two-thirds of the vector is used to pass back  captured  sub-
       strings, each substring using a pair of integers. The  remaining  third       strings,  each  substring using a pair of integers. The remaining third
       of  the  vector is used as workspace by pcre_exec() while matching cap-       of the vector is used as workspace by pcre_exec() while  matching  cap-
       turing subpatterns, and is not available for passing back  information.       turing  subpatterns, and is not available for passing back information.
       The  number passed in ovecsize should always be a multiple of three. If       The number passed in ovecsize should always be a multiple of three.  If
        it is not, it is rounded down.         it is not, it is rounded down.
   
       When a match is successful, information about  captured  substrings  is       When  a  match  is successful, information about captured substrings is
       returned  in  pairs  of integers, starting at the beginning of ovector,       returned in pairs of integers, starting at the  beginning  of  ovector,
       and continuing up to two-thirds of its length at the  most.  The  first       and  continuing  up  to two-thirds of its length at the most. The first
       element  of  each pair is set to the byte offset of the first character       element of each pair is set to the byte offset of the  first  character
       in a substring, and the second is set to the byte offset of  the  first       in  a  substring, and the second is set to the byte offset of the first
       character  after  the end of a substring. Note: these values are always       character after the end of a substring. Note: these values  are  always
        byte offsets, even in UTF-8 mode. They are not character counts.         byte offsets, even in UTF-8 mode. They are not character counts.
   
       The first pair of integers, ovector[0]  and  ovector[1],  identify  the       The  first  pair  of  integers, ovector[0] and ovector[1], identify the
       portion  of  the subject string matched by the entire pattern. The next       portion of the subject string matched by the entire pattern.  The  next
       pair is used for the first capturing subpattern, and so on.  The  value       pair  is  used for the first capturing subpattern, and so on. The value
        returned by pcre_exec() is one more than the highest numbered pair that         returned by pcre_exec() is one more than the highest numbered pair that
       has been set.  For example, if two substrings have been  captured,  the       has  been  set.  For example, if two substrings have been captured, the
       returned  value is 3. If there are no capturing subpatterns, the return       returned value is 3. If there are no capturing subpatterns, the  return
        value from a successful match is 1, indicating that just the first pair         value from a successful match is 1, indicating that just the first pair
        of offsets has been set.         of offsets has been set.
   
        If a capturing subpattern is matched repeatedly, it is the last portion         If a capturing subpattern is matched repeatedly, it is the last portion
        of the string that it matched that is returned.         of the string that it matched that is returned.
   
       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
       use  during matching. Thus it is usually advisable to supply an ovector       use during matching. Thus it is usually advisable to supply an  ovector
        of reasonable size.         of reasonable size.
   
       There are some cases where zero is returned  (indicating  vector  over-       There  are  some  cases where zero is returned (indicating vector over-
       flow)  when  in fact the vector is exactly the right size for the final       flow) when in fact the vector is exactly the right size for  the  final
        match. For example, consider the pattern         match. For example, consider the pattern
   
          (a)(?:(b)c|bd)           (a)(?:(b)c|bd)
   
       If a vector of 6 elements (allowing for only 1 captured  substring)  is       If  a  vector of 6 elements (allowing for only 1 captured substring) is
        given with subject string "abd", pcre_exec() will try to set the second         given with subject string "abd", pcre_exec() will try to set the second
        captured string, thereby recording a vector overflow, before failing to         captured string, thereby recording a vector overflow, before failing to
       match  "c"  and  backing  up  to  try  the second alternative. The zero       match "c" and backing up  to  try  the  second  alternative.  The  zero
       return, however, does correctly indicate that  the  maximum  number  of       return,  however,  does  correctly  indicate that the maximum number of
        slots (namely 2) have been filled. In similar cases where there is tem-         slots (namely 2) have been filled. In similar cases where there is tem-
       porary overflow, but the final number of used slots  is  actually  less       porary  overflow,  but  the final number of used slots is actually less
        than the maximum, a non-zero value is returned.         than the maximum, a non-zero value is returned.
   
        The pcre_fullinfo() function can be used to find out how many capturing         The pcre_fullinfo() function can be used to find out how many capturing
       subpatterns there are in a compiled  pattern.  The  smallest  size  for       subpatterns  there  are  in  a  compiled pattern. The smallest size for
       ovector  that  will allow for n captured substrings, in addition to the       ovector that will allow for n captured substrings, in addition  to  the
        offsets of the substring matched by the whole pattern, is (n+1)*3.         offsets of the substring matched by the whole pattern, is (n+1)*3.
   
       It is possible for capturing subpattern number n+1 to match  some  part       It  is  possible for capturing subpattern number n+1 to match som       It  is  possible for capturing subpattern number n+1 to match som
        of the subject when subpattern n has not been used at all. For example,         of the subject when subpattern n has not been used at all. For example,
       if the string "abc" is matched  against  the  pattern  (a|(z))(bc)  the       if  the  string  "abc"       if  the  string  "abc"
        return from the function is 4, and subpatterns 1 and 3 are matched, but         return from the function is 4, and subpatterns 1 and 3 are matched, but
       2 is not. When this happens, both values in  the  offset  pairs  corre-       2  is  not.  When  this happens, both values in the offs       2  is  not.  When  this happens, both values in the offs
        sponding to unused subpatterns are set to -1.         sponding to unused subpatterns are set to -1.
   
       Offset  values  that correspond to unused subpatterns at the end of the       Offset values that correspond to unused subpatterns at the end  of  the
       expression are also set to -1. For example,  if  the  string  "abc"  is       expression  are  also  set  to  -1. For example, if the string "abc" is
       matched  against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are not       matched against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are  not
       matched. The return from the function is 2, because  the  highest  used       matched.  The  return  from the function is 2, because the highest used
       capturing  subpattern  number  is 1, and the offsets for for the second       capturing subpattern number is 1, and the offsets for  for  the  second
       and third capturing subpatterns (assuming the vector is  large  enough,       and  third  capturing subpatterns (assuming the vector is large enough,
        of course) are set to -1.         of course) are set to -1.
   
       Note:  Elements  in  the first two-thirds of ovector that do not corre-       Note: Elements in the first two-thirds of ovector that  do  not  corre-
       spond to capturing parentheses in the pattern are never  changed.  That       spond  to  capturing parentheses in the pattern are never changed. That
       is,  if  a pattern contains n capturing parentheses, no more than ovec-       is, if a pattern contains n capturing parentheses, no more  than  ovec-
       tor[0] to ovector[2n+1] are set by pcre_exec(). The other elements  (in       tor[0]  to ovector[2n+1] are set by pcre_exec(). The other elements (in
        the first two-thirds) retain whatever values they previously had.         the first two-thirds) retain whatever values they previously had.
   
       Some  convenience  functions  are  provided for extracting the captured       Some convenience functions are provided  for  extracting  the  captured
        substrings as separate strings. These are described below.         substrings as separate strings. These are described below.
   
    Error return values from pcre_exec()     Error return values from pcre_exec()
   
       If pcre_exec() fails, it returns a negative number. The  following  are       If  pcre_exec()  fails, it returns a negative number. T       If  pcre_exec()  fails, it returns a negative number. The following are
        defined in the header file:         defined in the header file:
   
          PCRE_ERROR_NOMATCH        (-1)           PCRE_ERROR_NOMATCH        (-1)
Line 2844  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2862  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
   
          PCRE_ERROR_NULL           (-2)           PCRE_ERROR_NULL           (-2)
   
       Either  code  or  subject  was  passed as NULL, or ovector was NULL and       Either code or subject was passed as NULL,  or  ovector  was  NULL  and
        ovecsize was not zero.         ovecsize was not zero.
   
          PCRE_ERROR_BADOPTION      (-3)           PCRE_ERROR_BADOPTION      (-3)
Line 2853  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2871  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
   
          PCRE_ERROR_BADMAGIC       (-4)           PCRE_ERROR_BADMAGIC       (-4)
   
       PCRE stores a 4-byte "magic number" at the start of the compiled  code,       PCRE  stores a 4-byte "magic number" at the start of the compiled code,
        to catch the case when it is passed a junk pointer and to detect when a         to catch the case when it is passed a junk pointer and to detect when a
        pattern that was compiled in an environment of one endianness is run in         pattern that was compiled in an environment of one endianness is run in
       an  environment  with the other endianness. This is the error that PCRE       an environment with the other endianness. This is the error  that  PCRE
        gives when the magic number is not present.         gives when the magic number is not present.
   
          PCRE_ERROR_UNKNOWN_OPCODE (-5)           PCRE_ERROR_UNKNOWN_OPCODE (-5)
   
        While running the pattern match, an unknown item was encountered in the         While running the pattern match, an unknown item was encountered in the
       compiled  pattern.  This  error  could be caused by a bug in PCRE or by       compiled pattern. This error could be caused by a bug  in  PCRE  or  by
        overwriting of the compiled pattern.         overwriting of the compiled pattern.
   
          PCRE_ERROR_NOMEMORY       (-6)           PCRE_ERROR_NOMEMORY       (-6)
   
       If a pattern contains back references, but the ovector that  is  passed       If  a  pattern contains back references, but the ovector that is passed
        to pcre_exec() is not big enough to remember the referenced substrings,         to pcre_exec() is not big enough to remember the referenced substrings,
       PCRE gets a block of memory at the start of matching to  use  for  this       PCRE  gets  a  block of memory at the start of matching to use for this
       purpose.  If the call via pcre_malloc() fails, this error is given. The       purpose. If the call via pcre_malloc() fails, this error is given.  The
        memory is automatically freed at the end of matching.         memory is automatically freed at the end of matching.
   
       This error is also given if pcre_stack_malloc() fails  in  pcre_exec().       This  error  is also given if pcre_stack_malloc() fails in pcre_exec().
       This  can happen only when PCRE has been compiled with --disable-stack-       This can happen only when PCRE has been compiled with  --disable-stack-
        for-recursion.         for-recursion.
   
          PCRE_ERROR_NOSUBSTRING    (-7)           PCRE_ERROR_NOSUBSTRING    (-7)
   
       This error is used by the pcre_copy_substring(),  pcre_get_substring(),       This  error is used by the pcre_copy_substring(), pcre_get_substring(),
        and  pcre_get_substring_list()  functions  (see  below).  It  is  never         and  pcre_get_substring_list()  functions  (see  below).  It  is  never
        returned by pcre_exec().         returned by pcre_exec().
   
          PCRE_ERROR_MATCHLIMIT     (-8)           PCRE_ERROR_MATCHLIMIT     (-8)
   
       The backtracking limit, as specified by  the  match_limit  field  in  a       The  backtracking  limit,  as  specified  by the match_limit field in a
       pcre_extra  structure  (or  defaulted) was reached. See the description       pcre_extra structure (or defaulted) was reached.  See  the  description
        above.         above.
   
          PCRE_ERROR_CALLOUT        (-9)           PCRE_ERROR_CALLOUT        (-9)
   
        This error is never generated by pcre_exec() itself. It is provided for         This error is never generated by pcre_exec() itself. It is provided for
       use  by  callout functions that want to yield a distinctive error code.       use by callout functions that want to yield a distinctive  error  code.
        See the pcrecallout documentation for details.         See the pcrecallout documentation for details.
   
          PCRE_ERROR_BADUTF8        (-10)           PCRE_ERROR_BADUTF8        (-10)
   
       A string that contains an invalid UTF-8 byte sequence was passed  as  a       A  string  that contains an invalid UTF-8 byte sequence was passed as a
       subject,  and the PCRE_NO_UTF8_CHECK option was not set. If the size of       subject, and the PCRE_NO_UTF8_CHECK option was not set. If the size  of
       the output vector (ovecsize) is at least 2,  the  byte  offset  to  the       the  output  vector  (ovecsize)  is  at least 2, the byte offset to the
       start  of  the  the invalid UTF-8 character is placed in the first ele-       start of the the invalid UTF-8 character is placed in  the  first  ele-
       ment, and a reason code is placed in the  second  element.  The  reason       ment,  and  a  reason  code is placed in the second element. The reason
        codes are listed in the following section.  For backward compatibility,         codes are listed in the following section.  For backward compatibility,
       if PCRE_PARTIAL_HARD is set and the problem is a truncated UTF-8  char-       if  PCRE_PARTIAL_HARD is set and the problem is a truncated UTF-8 char-
       acter   at   the   end   of   the   subject  (reason  codes  1  to  5),       acter  at  the  end  of  the   subject   (reason   codes   1   to   5),
        PCRE_ERROR_SHORTUTF8 is returned instead of PCRE_ERROR_BADUTF8.         PCRE_ERROR_SHORTUTF8 is returned instead of PCRE_ERROR_BADUTF8.
   
          PCRE_ERROR_BADUTF8_OFFSET (-11)           PCRE_ERROR_BADUTF8_OFFSET (-11)
   
       The UTF-8 byte sequence that was passed as a subject  was  checked  and       The  UTF-8  byte  sequence that was passed as a subject was checked and
       found  to be valid (the PCRE_NO_UTF8_CHECK option was not set), but the       found to be valid (the PCRE_NO_UTF8_CHECK option was not set), but  the
       value of startoffset did not point to the beginning of a UTF-8  charac-       value  of startoffset did not point to the beginning of a UTF-8 charac-
        ter or the end of the subject.         ter or the end of the subject.
   
          PCRE_ERROR_PARTIAL        (-12)           PCRE_ERROR_PARTIAL        (-12)
   
       The  subject  string did not match, but it did match partially. See the       The subject string did not match, but it did match partially.  See  the
        pcrepartial documentation for details of partial matching.         pcrepartial documentation for details of partial matching.
   
          PCRE_ERROR_BADPARTIAL     (-13)           PCRE_ERROR_BADPARTIAL     (-13)
   
       This code is no longer in  use.  It  was  formerly  returned  when  the       This  code  is  no  longer  in  use.  It was formerly returned when the
       PCRE_PARTIAL  option  was used with a compiled pattern containing items       PCRE_PARTIAL option was used with a compiled pattern  containing  items
       that were  not  supported  for  partial  matching.  From  release  8.00       that  were  not  supported  for  partial  matching.  From  release 8.00
        onwards, there are no restrictions on partial matching.         onwards, there are no restrictions on partial matching.
   
          PCRE_ERROR_INTERNAL       (-14)           PCRE_ERROR_INTERNAL       (-14)
   
       An  unexpected  internal error has occurred. This error could be caused       An unexpected internal error has occurred. This error could  be  caused
        by a bug in PCRE or by overwriting of the compiled pattern.         by a bug in PCRE or by overwriting of the compiled pattern.
   
          PCRE_ERROR_BADCOUNT       (-15)           PCRE_ERROR_BADCOUNT       (-15)
Line 2938  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2956  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
          PCRE_ERROR_RECURSIONLIMIT (-21)           PCRE_ERROR_RECURSIONLIMIT (-21)
   
        The internal recursion limit, as specified by the match_limit_recursion         The internal recursion limit, as specified by the match_limit_recursion
       field  in  a  pcre_extra  structure (or defaulted) was reached. See the       field in a pcre_extra structure (or defaulted)  was  reached.  See  the
        description above.         description above.
   
          PCRE_ERROR_BADNEWLINE     (-23)           PCRE_ERROR_BADNEWLINE     (-23)
Line 2952  MATCHING A PATTERN: THE TRADITIONAL FUNCTION Line 2970  MATCHING A PATTERN: THE TRADITIONAL FUNCTION
   
          PCRE_ERROR_SHORTUTF8      (-25)           PCRE_ERROR_SHORTUTF8      (-25)
   
       This  error  is returned instead of PCRE_ERROR_BADUTF8 when the subject       This error is returned instead of PCRE_ERROR_BADUTF8 when  the  subject
       string ends with a truncated UTF-8 character and the  PCRE_PARTIAL_HARD       string  ends with a truncated UTF-8 character and the PCRE_PARTIAL_HARD
       option  is  set.   Information  about  the  failure  is returned as for       option is set.  Information  about  the  failure  is  returned  as  for
       PCRE_ERROR_BADUTF8. It is in fact sufficient to detect this  case,  but       PCRE_ERROR_BADUTF8.  It  is in fact sufficient to detect this case, but
       this  special error code for PCRE_PARTIAL_HARD precedes the implementa-       this special error code for PCRE_PARTIAL_HARD precedes the  implementa-
       tion of returned information; it is retained for backwards  compatibil-       tion  of returned information; it is retained for backwards compatibil-
        ity.         ity.
   
          PCRE_ERROR_RECURSELOOP    (-26)           PCRE_ERROR_RECURSELOOP    (-26)
   
        This error is returned when pcre_exec() detects a recursion loop within         This error is returned when pcre_exec() detects a recursion loop within
       the pattern. Specifically, it means that either the whole pattern or  a       the  pattern. Specifically, it means that either the whole pattern or a
       subpattern  has been called recursively for the second time at the same       subpattern has been called recursively for the second time at the  same
        position in the subject string. Some simple patterns that might do this         position in the subject string. Some simple patterns that might do this
       are  detected  and faulted at compile time, but more complicated cases,       are detected and faulted at compile time, but more  complicated  cases,
        in particular mutual recursions between two different subpatterns, can-         in particular mutual recursions between two different subpatterns, can-
        not be detected until run time.         not be detected until run time.
   
          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.
   
         PCRE_ERROR_BADMODE (-28)         PCRE_ERROR_BADMODE        (-28)
   
        This error is given if a pattern that was compiled by the 8-bit library         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.         is passed to a 16-bit library function, or vice versa.
   
         PCRE_ERROR_BADENDIANNESS (-29)         PCRE_ERROR_BADENDIANNESS  (-29)
   
       This  error  is  given  if  a  pattern  that  was compiled and saved is       This error is given if  a  pattern  that  was  compiled  and  saved  is
       reloaded on a host with  different  endianness.  The  utility  function       reloaded  on  a  host  with  different endianness. The utility function
        pcre_pattern_to_host_byte_order() can be used to convert such a pattern         pcre_pattern_to_host_byte_order() can be used to convert such a pattern
        so that it runs on the new host.         so that it runs on the new host.
   
       Error numbers -16 to -20 and -22 are not used by pcre_exec().       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       This  section  applies  only  to  the  8-bit library. The corresponding
        information for the 16-bit library is given in the pcre16 page.         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 3009  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 3022  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 3048  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 3079  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 3169  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 3178  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 3215  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  OBTAINING AN ESTIMATE OF STACK USAGE
   
       Matching  certain  patterns  using pcre_exec() can use a lot of process       Matching certain patterns using pcre_exec() can use a  lot  of  process
       stack, which in certain environments can be  rather  limited  in  size.       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       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       that  is  used  by  pcre_exec(),  to help them set recursion limits, as
       described  in  the pcrestack documentation. The estimate that is output       described in the pcrestack documentation. The estimate that  is  output
        by pcretest when called with the -m and -C options is obtained by call-         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       ing pcre_exec with the values NULL, NULL, NULL, -999, and -999 for  its
        first five arguments.         first five arguments.
   
       Normally, if  its  first  argument  is  NULL,  pcre_exec()  immediately       Normally,  if  its  first  argument  is  NULL,  pcre_exec() immediately
       returns  the negative error code PCRE_ERROR_NULL, but with this special       returns the negative error code PCRE_ERROR_NULL, but with this  special
       combination of arguments, it returns instead a  negative  number  whose       combination  of  arguments,  it returns instead a negative number whose
       absolute  value  is the approximate stack frame size in bytes. (A nega-       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.)       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       The value is approximate because in  some  cases,  recursive  calls  to
        pcre_exec() occur when there are one or two additional variables on the         pcre_exec() occur when there are one or two additional variables on the
        stack.         stack.
   
       If  PCRE  has  been  compiled  to use the heap instead of the stack for       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       recursion,  the  value  returned  is  the  size  of  each block that is
        obtained from the heap.         obtained from the heap.
   
   
Line 3295  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 3336  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 3399  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
   
        pcre16(3),  pcrebuild(3),  pcrecallout(3),  pcrecpp(3)(3),   pcrematch-         pcre16(3),  pcrebuild(3),  pcrecallout(3),  pcrecpp(3)(3),   pcrematch-
Line 3469  AUTHOR Line 3494  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 21 January 2012       Last updated: 17 June 2012
        Copyright (c) 1997-2012 University of Cambridge.         Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
Line 3761  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 3783  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 3843  AUTHOR Line 3876  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 08 Januray 2012       Last updated: 01 June 2012
        Copyright (c) 1997-2012 University of Cambridge.         Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
Line 4029  BACKSLASH Line 4062  BACKSLASH
        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 4067  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 4109  BACKSLASH Line 4142  BACKSLASH
        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-
Line 4196  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 4281  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
Line 4301  BACKSLASH Line 4336  BACKSLASH
        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 other modes, 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-
Line 4366  BACKSLASH Line 4401  BACKSLASH
        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-
Line 4501  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 4681  MATCHING A SINGLE DATA UNIT Line 4718  MATCHING A SINGLE DATA UNIT
        means that the rest of the string may start with a malformed UTF  char-         means that the rest of the string may start with a malformed UTF  char-
        acter.  This  has  undefined  results,  because PCRE assumes that it is         acter.  This  has  undefined  results,  because PCRE assumes that it is
        dealing with valid UTF strings (and by default it checks  this  at  the         dealing with valid UTF strings (and by default it checks  this  at  the
       start of processing unless the PCRE_NO_UTF8_CHECK option is used).       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 a UTF 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. However, one way of         In general, the \C escape sequence is best avoided. However, one way of
       using it that avoids the problem of malformed UTF characters is to  use       using  it that avoids the problem of malformed UTF characters is to use
       a  lookahead to check the length of the next character, as in this pat-       a lookahead to check the length of the next character, as in this  pat-
       tern, which could be used with a UTF-8 string (ignore white  space  and       tern,  which  could be used with a UTF-8 string (ignore white space and
        line breaks):         line breaks):
   
          (?| (?=[\x00-\x7f])(\C) |           (?| (?=[\x00-\x7f])(\C) |
Line 4698  MATCHING A SINGLE DATA UNIT Line 4736  MATCHING A SINGLE DATA UNIT
              (?=[\x{800}-\x{ffff}])(\C)(\C)(\C) |               (?=[\x{800}-\x{ffff}])(\C)(\C)(\C) |
              (?=[\x{10000}-\x{1fffff}])(\C)(\C)(\C)(\C))               (?=[\x{10000}-\x{1fffff}])(\C)(\C)(\C)(\C))
   
       A  group  that starts with (?| resets the capturing parentheses numbers       A group that starts with (?| resets the capturing  parentheses  numbers
       in each alternative (see "Duplicate  Subpattern  Numbers"  below).  The       in  each  alternative  (see  "Duplicate Subpattern Numbers" below). The
       assertions  at  the start of each branch check the next UTF-8 character       assertions at the start of each branch check the next  UTF-8  character
       for values whose encoding uses 1, 2, 3, or 4 bytes,  respectively.  The       for  values  whose encoding uses 1, 2, 3, or 4 bytes, respectively. The
       character's  individual bytes are then captured by the appropriate num-       character's individual bytes are then captured by the appropriate  num-
        ber of groups.         ber of groups.
   
   
Line 4712  SQUARE BRACKETS AND CHARACTER CLASSES Line 4750  SQUARE BRACKETS AND CHARACTER CLASSES
        closing square bracket. A closing square bracket on its own is not spe-         closing square bracket. A closing square bracket on its own is not spe-
        cial by default.  However, if the PCRE_JAVASCRIPT_COMPAT option is set,         cial by default.  However, if the PCRE_JAVASCRIPT_COMPAT option is set,
        a lone closing square bracket causes a compile-time error. If a closing         a lone closing square bracket causes a compile-time error. If a closing
       square bracket is required as a member of the class, it should  be  the       square  bracket  is required as a member of the class, it should be the
       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  a  UTF       A  character  class matches a single character in the subject. In a UTF
       mode,  the  character  may  be  more than one data unit long. A matched       mode, the character may be more than one  data  unit  long.  A  matched
        character must be in the set of characters defined by the class, unless         character must be in the set of characters defined by the class, unless
       the  first  character in the class definition is a circumflex, in which       the first character in the class definition is a circumflex,  in  which
        case the subject character must not be in the set defined by the class.         case the subject character must not be in the set defined by the class.
       If  a  circumflex is actually required as a member of the class, ensure       If a circumflex is actually required as a member of the  class,  ensure
        it is 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.
        Note that a circumflex is just a convenient notation for specifying the         Note that a circumflex is just a convenient notation for specifying the
       characters  that  are in the class by enumerating those that are not. A       characters that are in the class by enumerating those that are  not.  A
       class that starts with a circumflex is not an assertion; it still  con-       class  that starts with a circumflex is not an assertion; it still con-
       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  (UTF-16)  mode,  characters  with  values  greater  than  255       In  UTF-8  (UTF-16)  mode,  characters  with  values  greater  than 255
       (0xffff)  can be included in a class as a literal string of data units,       (0xffff) can be included in a class as a literal string of data  units,
        or by using the \x{ escaping 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 a UTF 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 a UTF 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 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
       sequence is in  use,  and  whatever  setting  of  the  PCRE_DOTALL  and       sequence  is  in  use,  and  whatever  setting  of  the PCRE_DOTALL and
        PCRE_MULTILINE options is used. A class such as [^a] always matches one         PCRE_MULTILINE options is used. A class such as [^a] always matches one
        of these characters.         of these characters.
   
       The minus (hyphen) character can be used to specify a range of  charac-       The  minus (hyphen) character can be used to specify a range of charac-
       ters  in  a  character  class.  For  example,  [d-m] matches any letter       ters in a character  class.  For  example,  [d-m]  matches  any  letter
       between d and m, inclusive. If a  minus  character  is  required  in  a       between  d  and  m,  inclusive.  If  a minus character is required in a
       class,  it  must  be  escaped  with a backslash or appear in a position       class, it must be escaped with a backslash  or  appear  in  a  position
       where it cannot be interpreted as indicating a range, typically as  the       where  it cannot be interpreted as indicating a range, typically as the
        first or last character in the class.         first or last character in the class.
   
        It is not possible to have the literal character "]" as the end charac-         It is not possible to have the literal character "]" as the end charac-
       ter of a range. A pattern such as [W-]46] is interpreted as a class  of       ter  of a range. A pattern such as [W-]46] is interpreted as a class of
       two  characters ("W" and "-") followed by a literal string "46]", so it       two characters ("W" and "-") followed by a literal string "46]", so  it
       would match "W46]" or "-46]". However, if the "]"  is  escaped  with  a       would  match  "W46]"  or  "-46]". However, if the "]" is escaped with a
       backslash  it is interpreted as the end of range, so [W-\]46] is inter-       backslash it is interpreted as the end of range, so [W-\]46] is  inter-
       preted as a class containing a range followed by two other  characters.       preted  as a class containing a range followed by two other characters.
       The  octal or hexadecimal representation of "]" can also be used to end       The octal or hexadecimal representation of "]" can also be used to  end
        a range.         a range.
   
       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]. Ranges can include any characters that are valid  for  the       [\000-\037].  Ranges  can include any characters that are valid for the
        current mode.         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 a non-UTF 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 modes, 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 modes, 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
       meaning inside a character class; it matches the  backspace  character.       meaning  inside  a character class; it matches the backspace character.
       The  sequences  \B,  \N,  \R, and \X are not special inside a character       The sequences \B, \N, \R, and \X are not  special  inside  a  character
       class. Like any other unrecognized escape sequences, they  are  treated       class.  Like  any other unrecognized escape sequences, they are treated
       as  the literal characters "B", "N", "R", and "X" by default, but cause       as the literal characters "B", "N", "R", and "X" by default, but  cause
        an error if the PCRE_EXTRA option is set.         an error if the PCRE_EXTRA option is set.
   
       A circumflex can conveniently be used with  the  upper  case  character       A  circumflex  can  conveniently  be used with the upper case character
       types  to specify a more restricted set of characters than the matching       types to specify a more restricted set of characters than the  matching
       lower case type.  For example, the class [^\W_] matches any  letter  or       lower  case  type.  For example, the class [^\W_] matches any letter or
        digit, but not underscore, whereas [\w] includes underscore. A positive         digit, but not underscore, whereas [\w] includes underscore. A positive
        character class should be read as "something OR something OR ..." and a         character class should be read as "something OR something OR ..." and a
        negative class as "NOT something AND NOT something AND NOT ...".         negative class as "NOT something AND NOT something AND NOT ...".
   
       The  only  metacharacters  that are recognized in character classes are       The only metacharacters that are recognized in  character  classes  are
       backslash, hyphen (only where it can be  interpreted  as  specifying  a       backslash,  hyphen  (only  where  it can be interpreted as specifying a
       range),  circumflex  (only  at the start), opening square bracket (only       range), circumflex (only at the start), opening  square  bracket  (only
       when it can be interpreted as introducing a POSIX class name - see  the       when  it can be interpreted as introducing a POSIX class name - see the
       next  section),  and  the  terminating closing square bracket. However,       next section), and the terminating  closing  square  bracket.  However,
        escaping other non-alphanumeric characters does no harm.         escaping other non-alphanumeric characters does no harm.
   
   
 POSIX CHARACTER CLASSES  POSIX CHARACTER CLASSES
   
        Perl supports the POSIX notation for character classes. This uses names         Perl supports the POSIX notation for character classes. This uses names
       enclosed  by  [: and :] within the enclosing square brackets. PCRE also       enclosed by [: and :] within the enclosing square brackets.  PCRE  also
        supports this notation. For example,         supports this notation. For example,
   
          [01[:alpha:]%]           [01[:alpha:]%]
Line 4837  POSIX CHARACTER CLASSES Line 4875  POSIX CHARACTER CLASSES
          word     "word" characters (same as \w)           word     "word" characters (same as \w)
          xdigit   hexadecimal digits           xdigit   hexadecimal digits
   
       The  "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13),       The "space" characters are HT (9), LF (10), VT (11), FF (12), CR  (13),
       and space (32). Notice that this list includes the VT  character  (code       and  space  (32). Notice that this list includes the VT character (code
        11). This makes "space" different to \s, which does not include VT (for         11). This makes "space" different to \s, which does not include VT (for
        Perl compatibility).         Perl compatibility).
   
       The name "word" is a Perl extension, and "blank"  is  a  GNU  extension       The  name  "word"  is  a Perl extension, and "blank" is a GNU extension
       from  Perl  5.8. Another Perl extension is negation, which is indicated       from Perl 5.8. Another Perl extension is negation, which  is  indicated
        by a ^ character after the colon. For example,         by a ^ character after the colon. For example,
   
          [12[:^digit:]]           [12[:^digit:]]
   
       matches "1", "2", or any non-digit. PCRE (and Perl) also recognize  the       matches  "1", "2", or any non-digit. PCRE (and Perl) also recognize the
        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 modes, 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-
        ing the POSIX classes by other sequences, as follows:         ing the POSIX classes by other sequences, as follows:
   
Line 4867  POSIX CHARACTER CLASSES Line 4905  POSIX CHARACTER CLASSES
          [:upper:]  becomes  \p{Lu}           [:upper:]  becomes  \p{Lu}
          [:word:]   becomes  \p{Xwd}           [:word:]   becomes  \p{Xwd}
   
       Negated versions, such as [:^alpha:] use \P instead of  \p.  The  other       Negated  versions,  such  as [:^alpha:] use \P instead of \p. The other
        POSIX classes are unchanged, and match only characters with code points         POSIX classes are unchanged, and match only characters with code points
        less than 128.         less than 128.
   
   
 VERTICAL BAR  VERTICAL BAR
   
       Vertical bar characters are used to separate alternative patterns.  For       Vertical  bar characters are used to separate alternative patterns. For
        example, the pattern         example, the pattern
   
          gilbert|sullivan           gilbert|sullivan
   
       matches  either "gilbert" or "sullivan". Any number of alternatives may       matches either "gilbert" or "sullivan". Any number of alternatives  may
       appear, and an empty  alternative  is  permitted  (matching  the  empty       appear,  and  an  empty  alternative  is  permitted (matching the empty
        string). The matching process tries each alternative in turn, from left         string). The matching process tries each alternative in turn, from left
       to right, and the first one that succeeds is used. If the  alternatives       to  right, and the first one that succeeds is used. If the alternatives
       are  within a subpattern (defined below), "succeeds" means matching the       are within a subpattern (defined below), "succeeds" means matching  the
        rest of the main pattern as well as the alternative in the subpattern.         rest of the main pattern as well as the alternative in the subpattern.
   
   
 INTERNAL OPTION SETTING  INTERNAL OPTION SETTING
   
       The settings of the  PCRE_CASELESS,  PCRE_MULTILINE,  PCRE_DOTALL,  and       The  settings  of  the  PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and
       PCRE_EXTENDED  options  (which are Perl-compatible) can be changed from       PCRE_EXTENDED options (which are Perl-compatible) can be  changed  from
       within the pattern by  a  sequence  of  Perl  option  letters  enclosed       within  the  pattern  by  a  sequence  of  Perl option letters enclosed
        between "(?" and ")".  The option letters are         between "(?" and ")".  The option letters are
   
          i  for PCRE_CASELESS           i  for PCRE_CASELESS
Line 4901  INTERNAL OPTION SETTING Line 4939  INTERNAL OPTION SETTING
   
        For example, (?im) sets caseless, multiline matching. It is also possi-         For example, (?im) sets caseless, multiline matching. It is also possi-
        ble to unset these options by preceding the letter with a hyphen, and a         ble to unset these options by preceding the letter with a hyphen, and a
       combined  setting and unsetting such as (?im-sx), which sets PCRE_CASE-       combined setting and unsetting such as (?im-sx), which sets  PCRE_CASE-
       LESS and PCRE_MULTILINE while unsetting PCRE_DOTALL and  PCRE_EXTENDED,       LESS  and PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED,
       is  also  permitted.  If  a  letter  appears  both before and after the       is also permitted. If a  letter  appears  both  before  and  after  the
        hyphen, the option is unset.         hyphen, the option is unset.
   
       The PCRE-specific options PCRE_DUPNAMES, PCRE_UNGREEDY, and  PCRE_EXTRA       The  PCRE-specific options PCRE_DUPNAMES, PCRE_UNGREEDY, and PCRE_EXTRA
       can  be changed in the same way as the Perl-compatible options by using       can be changed in the same way as the Perl-compatible options by  using
        the characters J, U and X respectively.         the characters J, U and X respectively.
   
       When one of these option changes occurs at  top  level  (that  is,  not       When  one  of  these  option  changes occurs at top level (that is, not
       inside  subpattern parentheses), the change applies to the remainder of       inside subpattern parentheses), the change applies to the remainder  of
        the pattern that follows. If the change is placed right at the start of         the pattern that follows. If the change is placed right at the start of
        a pattern, PCRE extracts it into the global options (and it will there-         a pattern, PCRE extracts it into the global options (and it will there-
        fore show up in data extracted by the pcre_fullinfo() function).         fore show up in data extracted by the pcre_fullinfo() function).
   
       An option change within a subpattern (see below for  a  description  of       An  option  chan       An  option  chan
       subpatterns)  affects only that part of the subpattern that follows it,       subpatterns) affects only that part of the subpattern that follows  it,
        so         so
   
          (a(?i)b)c           (a(?i)b)c
   
        matches abc and aBc and no other strings (assuming PCRE_CASELESS is not         matches abc and aBc and no other strings (assuming PCRE_CASELESS is not
       used).   By  this means, options can be made to have different settings       used).  By this means, options can be made to have  different  settings
       in different parts of the pattern. Any changes made in one  alternative       in  different parts of the pattern. Any changes made in one alternative
       do  carry  on  into subsequent branches within the same subpattern. For       do carry on into subsequent branches within the  same  subpattern.  For
        example,         example,
   
          (a(?i)b|c)           (a(?i)b|c)
   
       matches "ab", "aB", "c", and "C", even though  when  matching  "C"  the       matches  "ab",  "aB",  "c",  and "C", even though when matching "C" the
       first  branch  is  abandoned before the option setting. This is because       first branch is abandoned before the option setting.  This  is  because
       the effects of option settings happen at compile time. There  would  be       the  effects  of option settings happen at compile time. There would be
        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 compiling or matching  functions  are  called.  In       application  when  the  compiling  or matching functions are called. In
       some  cases  the  pattern can contain special leading sequences such as       some cases the pattern can contain special leading  sequences  such  as
       (*CRLF) to override what the application  has  set  or  what  has  been       (*CRLF)  to  override  what  the  application  has set or what has been
       defaulted.   Details   are  given  in  the  section  entitled  "Newline       defaulted.  Details  are  given  in  the  section   entitled   "Newline
       sequences" above. There are also  the  (*UTF8),  (*UTF16),  and  (*UCP)       sequences"  above.  There  are  also  the (*UTF8), (*UTF16), and (*UCP)
       leading  sequences  that  can  be  used to set UTF and Unicode property       leading sequences that can be used to  set  UTF  and  Unicode  property
       modes; they are equivalent to setting the  PCRE_UTF8,  PCRE_UTF16,  and       modes;  they  are  equivalent to setting the PCRE_UTF8, PCRE_UTF16, and
        the PCRE_UCP options, respectively.         the PCRE_UCP options, respectively.
   
   
Line 4955  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 the matching function. (This applies  only  to  the       ovector  argument  of  the matching function. (This applies only to the
       traditional  matching functions; the DFA matching functions do not sup-       traditional matching functions; the DFA matching functions do not  sup-
        port capturing.)         port capturing.)
   
        Opening parentheses are counted from left to right (starting from 1) to         Opening parentheses are counted from left to right (starting from 1) to
       obtain  numbers  for  the  capturing  subpatterns.  For example, if the       obtain numbers for the  capturing  subpatterns.  For  example,  if  the
        string "the red king" is matched against the pattern         string "the red king" is matched against the pattern
   
          the ((red|white) (king|queen))           the ((red|white) (king|queen))
Line 4974  SUBPATTERNS Line 5012  SUBPATTERNS
        the captured substrings are "red king", "red", and "king", and are num-         the captured substrings are "red king", "red", and "king", and are num-
        bered 1, 2, and 3, respectively.         bered 1, 2, and 3, respectively.
   
       The  fact  that  plain  parentheses  fulfil two functions is not always       The fact that plain parentheses fulfil  two  functions  is  not  always
       helpful.  There are often times when a grouping subpattern is  required       helpful.   There are often times when a grouping subpattern is required
       without  a capturing requirement. If an opening parenthesis is followed       without a capturing requirement. If an opening parenthesis is  followed
       by a question mark and a colon, the subpattern does not do any  captur-       by  a question mark and a colon, the subpattern does not do any captur-
       ing,  and  is  not  counted when computing the number of any subsequent       ing, and is not counted when computing the  number  of  any  subsequent
       capturing subpatterns. For example, if the string "the white queen"  is       capturing  subpatterns. For example, if the string "the white queen" is
        matched against the pattern         matched against the pattern
   
          the ((?:red|white) (king|queen))           the ((?:red|white) (king|queen))
Line 4987  SUBPATTERNS Line 5025  SUBPATTERNS
        the captured substrings are "white queen" and "queen", and are numbered         the captured substrings are "white queen" and "queen", and are numbered
        1 and 2. The maximum number of capturing subpatterns is 65535.         1 and 2. The maximum number of capturing subpatterns is 65535.
   
       As a convenient shorthand, if any option settings are required  at  the       As  a  convenient shorthand, if any option settings are required at the
       start  of  a  non-capturing  subpattern,  the option letters may appear       start of a non-capturing subpattern,  the  option  letters  may  appear
        between the "?" and the ":". Thus the two patterns         between the "?" and the ":". Thus the two patterns
   
          (?i:saturday|sunday)           (?i:saturday|sunday)
          (?:(?i)saturday|sunday)           (?:(?i)saturday|sunday)
   
        match exactly the same set of strings. Because alternative branches are         match exactly the same set of strings. Because alternative branches are
       tried  from  left  to right, and options are not reset until the end of       tried from left to right, and options are not reset until  the  end  of
       the subpattern is reached, an option setting in one branch does  affect       the  subpattern is reached, an option setting in one branch does affect
       subsequent  branches,  so  the above patterns match "SUNDAY" as well as       subsequent branches, so the above patterns match "SUNDAY"  as  well  as
        "Saturday".         "Saturday".
   
   
 DUPLICATE SUBPATTERN NUMBERS  DUPLICATE SUBPATTERN NUMBERS
   
        Perl 5.10 introduced a feature whereby each alternative in a subpattern         Perl 5.10 introduced a feature whereby each alternative in a subpattern
       uses  the same numbers for its capturing parentheses. Such a subpattern       uses the same numbers for its capturing parentheses. Such a  subpattern
       starts with (?| and is itself a non-capturing subpattern. For  example,       starts  with (?| and is itself a non-capturing subpattern. For example,
        consider this pattern:         consider this pattern:
   
          (?|(Sat)ur|(Sun))day           (?|(Sat)ur|(Sun))day
   
       Because  the two alternatives are inside a (?| group, both sets of cap-       Because the two alternatives are inside a (?| group, both sets of  cap-
       turing parentheses are numbered one. Thus, when  the  pattern  matches,       turing  parentheses  are  numbered one. Thus, when the pattern matches,
       you  can  look  at captured substring number one, whichever alternative       you can look at captured substring number  one,  whichever  alternative
       matched. This construct is useful when you want to  capture  part,  but       matched.  This  construct  is useful when you want to capture part, but
        not all, of one of a number of alternatives. Inside a (?| group, paren-         not all, of one of a number of alternatives. Inside a (?| group, paren-
       theses are numbered as usual, but the number is reset at the  start  of       theses  are  numbered as usual, but the number is reset at the start of
       each  branch.  The numbers of any capturing parentheses that follow the       each branch. The numbers of any capturing parentheses that  follow  the
       subpattern start after the highest number used in any branch. The  fol-       subpattern  start after the highest number used in any branch. The fol-
        lowing example is taken from the Perl documentation. The numbers under-         lowing example is taken from the Perl documentation. The numbers under-
        neath show in which buffer the captured content will be stored.         neath show in which buffer the captured content will be stored.
   
Line 5025  DUPLICATE SUBPATTERN NUMBERS Line 5063  DUPLICATE SUBPATTERN NUMBERS
          / ( a )  (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x           / ( a )  (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x
          # 1            2         2  3        2     3     4           # 1            2         2  3        2     3     4
   
       A back reference to a numbered subpattern uses the  most  recent  value       A  back  reference  to a numbered subpattern uses the most recent value
       that  is  set  for that number by any subpattern. The following pattern       that is set for that number by any subpattern.  The  following  pattern
        matches "abcabc" or "defdef":         matches "abcabc" or "defdef":
   
          /(?|(abc)|(def))\1/           /(?|(abc)|(def))\1/
   
       In contrast, a subroutine call to a numbered subpattern  always  refers       In  contrast,  a subroutine call to a numbered subpattern always refers
       to  the  first  one in the pattern with the given number. The following       to the first one in the pattern with the given  number.  The  following
        pattern matches "abcabc" or "defabc":         pattern matches "abcabc" or "defabc":
   
          /(?|(abc)|(def))(?1)/           /(?|(abc)|(def))(?1)/
   
       If a condition test for a subpattern's having matched refers to a  non-       If  a condition test for a subpattern's having matched refers to a non-
       unique  number, the test is true if any of the subpatterns of that num-       unique number, the test is true if any of the subpatterns of that  num-
        ber have matched.         ber have matched.
   
       An alternative approach to using this "branch reset" feature is to  use       An  alternative approach to using this "branch reset" feature is to use
        duplicate named subpatterns, as described in the next section.         duplicate named subpatterns, as described in the next section.
   
   
 NAMED SUBPATTERNS  NAMED SUBPATTERNS
   
       Identifying  capturing  parentheses  by number is simple, but it can be       Identifying capturing parentheses by number is simple, but  it  can  be
       very hard to keep track of the numbers in complicated  regular  expres-       very  hard  to keep track of the numbers in complicated regular expres-
       sions.  Furthermore,  if  an  expression  is  modified, the numbers may       sions. Furthermore, if an  expression  is  modified,  the  numbers  may
       change. To help with this difficulty, PCRE supports the naming of  sub-       change.  To help with this difficulty, PCRE supports the naming of sub-
        patterns. This feature was not added to Perl until release 5.10. Python         patterns. This feature was not added to Perl until release 5.10. Python
       had the feature earlier, and PCRE introduced it at release  4.0,  using       had  the  feature earlier, and PCRE introduced it at release 4.0, using
       the  Python syntax. PCRE now supports both the Perl and the Python syn-       the Python syntax. PCRE now supports both the Perl and the Python  syn-
       tax. Perl allows identically numbered  subpatterns  to  have  different       tax.  Perl  allows  identically  numbered subpatterns to have different
        names, but PCRE does not.         names, but PCRE does not.
   
       In  PCRE,  a subpattern can be named in one of three ways: (?<name>...)       In PCRE, a subpattern can be named in one of three  ways:  (?<name>...)
       or (?'name'...) as in Perl, or (?P<name>...) as in  Python.  References       or  (?'name'...)  as in Perl, or (?P<name>...) as in Python. References
       to  capturing parentheses from other parts of the pattern, such as back       to capturing parentheses from other parts of the pattern, such as  back
       references, recursion, and conditions, can be made by name as  well  as       references,  recursion,  and conditions, can be made by name as well as
        by number.         by number.
   
       Names  consist  of  up  to  32 alphanumeric characters and underscores.       Names consist of up to  32  alphanumeric  characters  and  underscores.
       Named capturing parentheses are still  allocated  numbers  as  well  as       Named  capturing  parentheses  are  still  allocated numbers as well as
       names,  exactly as if the names were not present. The PCRE API provides       names, exactly as if the names were not present. The PCRE API  provides
        function calls for extracting the name-to-number translation table from         function calls for extracting the name-to-number translation table from
        a compiled pattern. There is also a convenience function for extracting         a compiled pattern. There is also a convenience function for extracting
        a captured substring by name.         a captured substring by name.
   
       By default, a name must be unique within a pattern, but it is  possible       By  default, a name must be unique within a pattern, but it is possible
        to relax this constraint by setting the PCRE_DUPNAMES option at compile         to relax this constraint by setting the PCRE_DUPNAMES option at compile
       time. (Duplicate names are also always permitted for  subpatterns  with       time.  (Duplicate  names are also always permitted for subpatterns with
       the  same  number, set up as described in the previous section.) Dupli-       the same number, set up as described in the previous  section.)  Dupli-
       cate names can be useful for patterns where only one  instance  of  the       cate  names  can  be useful for patterns where only one instance of the
       named  parentheses  can  match. Suppose you want to match the name of a       named parentheses can match. Suppose you want to match the  name  of  a
       weekday, either as a 3-letter abbreviation or as the full name, and  in       weekday,  either as a 3-letter abbreviation or as the full name, and in
        both cases you want to extract the abbreviation. This pattern (ignoring         both cases you want to extract the abbreviation. This pattern (ignoring
        the line breaks) does the job:         the line breaks) does the job:
   
Line 5086  NAMED SUBPATTERNS Line 5124  NAMED SUBPATTERNS
          (?<DN>Thu)(?:rsday)?|           (?<DN>Thu)(?:rsday)?|
          (?<DN>Sat)(?:urday)?           (?<DN>Sat)(?:urday)?
   
       There are five capturing substrings, but only one is ever set  after  a       There  are  five capturing substrings, but only one is ever set after a
        match.  (An alternative way of solving this problem is to use a "branch         match.  (An alternative way of solving this problem is to use a "branch
        reset" subpattern, as described in the previous section.)         reset" subpattern, as described in the previous section.)
   
       The convenience function for extracting the data by  name  returns  the       The  convenience  function  for extracting the data by name returns the
       substring  for  the first (and in this example, the only) subpattern of       substring for the first (and in this example, the only)  subpattern  of
       that name that matched. This saves searching  to  find  which  numbered       that  name  that  matched.  This saves searching to find which numbered
        subpattern it was.         subpattern it was.
   
       If  you  make  a  back  reference to a non-unique named subpattern from       If you make a back reference to  a  non-unique  named  subpattern  from
       elsewhere in the pattern, the one that corresponds to the first  occur-       elsewhere  in the pattern, the one that corresponds to the first occur-
        rence of the name is used. In the absence of duplicate numbers (see the         rence of the name is used. In the absence of duplicate numbers (see the
       previous section) this is the one with the lowest number. If you use  a       previous  section) this is the one with the lowest number. If you use a
       named  reference  in a condition test (see the section about conditions       named reference in a condition test (see the section  about  conditions
       below), either to check whether a subpattern has matched, or  to  check       below),  either  to check whether a subpattern has matched, or to check
       for  recursion,  all  subpatterns with the same name are tested. If the       for recursion, all subpatterns with the same name are  tested.  If  the
       condition is true for any one of them, the overall condition  is  true.       condition  is  true for any one of them, the overall condition is true.
        This is the same behaviour as testing by number. For further details of         This is the same behaviour as testing by number. For further details of
        the interfaces for handling named subpatterns, see the pcreapi documen-         the interfaces for handling named subpatterns, see the pcreapi documen-
        tation.         tation.
   
        Warning: You cannot use different names to distinguish between two sub-         Warning: You cannot use different names to distinguish between two sub-
       patterns with the same number because PCRE uses only the  numbers  when       patterns  with  the same number because PCRE uses only the numbers when
        matching. For this reason, an error is given at compile time if differ-         matching. For this reason, an error is given at compile time if differ-
       ent names are given to subpatterns with the same number.  However,  you       ent  names  are given to subpatterns with the same number. However, you
       can  give  the same name to subpatterns with the same number, even when       can give the same name to subpatterns with the same number,  even  when
        PCRE_DUPNAMES is not set.         PCRE_DUPNAMES is not set.
   
   
 REPETITION  REPETITION
   
       Repetition is specified by quantifiers, which can  follow  any  of  the       Repetition  is  specified  by  quantifiers, which can follow any of the
        following items:         following items:
   
          a literal data character           a literal data character
Line 5131  REPETITION Line 5169  REPETITION
          a parenthesized subpattern (including assertions)           a parenthesized subpattern (including assertions)
          a subroutine call to a subpattern (recursive or otherwise)           a subroutine call to a subpattern (recursive or otherwise)
   
       The  general repetition quantifier specifies a minimum and maximum num-       The general repetition quantifier specifies a minimum and maximum  num-
       ber of permitted matches, by giving the two numbers in  curly  brackets       ber  of  permitted matches, by giving the two numbers in curly brackets
       (braces),  separated  by  a comma. The numbers must be less than 65536,       (braces), separated by a comma. The numbers must be  less  than  65536,
        and the first must be less than or equal to the second. For example:         and the first must be less than or equal to the second. For example:
   
          z{2,4}           z{2,4}
   
       matches "zz", "zzz", or "zzzz". A closing brace on its  own  is  not  a       matches  "zz",  "zzz",  or  "zzzz". A closing brace on its own is not a
       special  character.  If  the second number is omitted, but the comma is       special character. If the second number is omitted, but  the  comma  is
       present, there is no upper limit; if the second number  and  the  comma       present,  there  is  no upper limit; if the second number and the comma
       are  both omitted, the quantifier specifies an exact number of required       are both omitted, the quantifier specifies an exact number of  required
        matches. Thus         matches. Thus
   
          [aeiou]{3,}           [aeiou]{3,}
Line 5150  REPETITION Line 5188  REPETITION
   
          \d{8}           \d{8}
   
       matches exactly 8 digits. An opening curly bracket that  appears  in  a       matches  exactly  8  digits. An opening curly bracket that appears in a
       position  where a quantifier is not allowed, or one that does not match       position where a quantifier is not allowed, or one that does not  match
       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 modes, quantifiers apply to characters rather than to individual         In UTF modes, quantifiers apply to characters rather than to individual
       data units. Thus, for example, \x{100}{2} matches two characters,  each       data  units. Thus, for example, \x{100}{2} matches two characters, each
        of which is represented by a two-byte sequence in a UTF-8 string. Simi-         of which is represented by a two-byte sequence in a UTF-8 string. Simi-
       larly, \X{3} matches three Unicode extended sequences,  each  of  which       larly,  \X{3}  matches  three Unicode extended sequences, each of which
        may be several data units long (and they may be of different lengths).         may be several data units long (and they 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 5201  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 5221  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 5259  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 5270  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 5326  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 5376  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 5405  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 5414  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 5448  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 5534  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 5574  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  a UTF 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 data unit even in a UTF 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  data       hind.  The \X and \R escapes, which can match different numbers of data
        units, 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 5638  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 5657  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 5688  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 5762  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 5815  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
       a compiling function or by a special sequence at the start of the  pat-       a  compiling function or by a special sequence at the start of the pat-
        tern, as described in the section entitled "Newline conventions" above.         tern, as described in the section entitled "Newline conventions" above.
        Note that the end of this type of comment is a literal newline sequence         Note that the end of this type of comment is a literal newline sequence
       in  the pattern; escape sequences that happen to represent a newline do       in the pattern; escape sequences that happen to represent a newline  do
       not count. For example, consider this  pattern  when  PCRE_EXTENDED  is       not  count.  For  example,  consider this pattern when PCRE_EXTENDED is
        set, 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 5859  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 6064  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  (8-bit  library)  or  pcre16_callout (16-bit library). By       pcre_callout (8-bit library) or  pcre16_callout  (16-bit  library).  By
        default, this variable contains NULL, which disables 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 a compiling function,  call-       If  the PCRE_AUTO_CALLOUT flag is passed to a compiling function, call-
       outs  are automatically installed before each item in the pattern. They       outs are automatically installed before each item in the pattern.  They
        are all numbered 255.         are all numbered 255.
   
       During matching, when PCRE reaches a callout point, the external  func-       During  matching, when PCRE reaches a callout point, the external func-
       tion  is  called.  It  is  provided with the number of the callout, the       tion is called. It is provided with the  number  of  the  callout,  the
       position in the pattern, and, optionally, one item of  data  originally       position  in  the pattern, and, optionally, one item of data originally
       supplied  by  the caller of the matching function. The callout function       supplied by the caller of the matching function. The  callout  function
       may cause matching to proceed, to backtrack, or to fail  altogether.  A       may  cause  matching to proceed, to backtrack, or to fail altogether. A
       complete  description of the interface to the callout function is given       complete description of the interface to the callout function 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  one  of       them  can  be  used only when the pattern is to be matched using one of
        the traditional matching functions, which use a backtracking algorithm.         the traditional matching functions, which use a backtracking algorithm.
       With the exception of (*FAIL), which behaves like  a  failing  negative       With  the  exception  of (*FAIL), which behaves like a failing negative
       assertion,  they  cause an error if encountered by a DFA matching func-       assertion, they cause an error if encountered by a DFA  matching  func-
        tion.         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
        confined to that subpattern; it does not extend to the surrounding pat-         confined to that subpattern; it does not extend to the surrounding pat-
        tern, with one exception: the name from a *(MARK), (*PRUNE), or (*THEN)         tern, with one exception: the name from a *(MARK), (*PRUNE), or (*THEN)
       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.
   
      Optimizations that affect backtracking verbs
   
        PCRE  contains some optimizations that are used to speed up matching by         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
Line 6189  BACKTRACKING CONTROL Line 6230  BACKTRACKING CONTROL
        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  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.
Line 6268  BACKTRACKING CONTROL Line 6311  BACKTRACKING CONTROL
          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-
Line 6448  AUTHOR Line 6495  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 09 January 2012       Last updated: 17 June 2012
        Copyright (c) 1997-2012 University of Cambridge.         Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
Line 6478  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 6494  CHARACTER TYPES Line 6541  CHARACTER TYPES
          \C         one data unit, even in UTF 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
Line 6571  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 6605  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 6889  UNICODE PROPERTY SUPPORT Line 6938  UNICODE PROPERTY SUPPORT
   
        When you set the PCRE_UTF8 flag, the byte strings  passed  as  patterns         When you set the PCRE_UTF8 flag, the byte strings  passed  as  patterns
        and subjects are (by default) checked for validity on entry to the rel-         and subjects are (by default) checked for validity on entry to the rel-
       evant functions. From release 7.3 of PCRE, the check is  according  the       evant functions. The entire string is checked before any other process-
        ing  takes  place. From release 7.3 of PCRE, the check is according the
        rules of RFC 3629, which are themselves derived from the Unicode speci-         rules of RFC 3629, which are themselves derived from the Unicode speci-
       fication. Earlier releases of PCRE followed  the  rules  of  RFC  2279,       fication.  Earlier  releases  of  PCRE  followed the rules of RFC 2279,
       which  allows  the  full  range of 31-bit values (0 to 0x7FFFFFFF). The       which allows the full range of 31-bit values  (0  to  0x7FFFFFFF).  The
       current check allows only values in the range U+0 to U+10FFFF,  exclud-       current  check allows only values in the range U+0 to U+10FFFF, exclud-
        ing U+D800 to U+DFFF.         ing U+D800 to U+DFFF.
   
       The  excluded code points are the "Surrogate Area" of Unicode. They are       The excluded code points are the "Surrogate Area" of Unicode. They  are
       reserved for use by UTF-16, where they are  used  in  pairs  to  encode       reserved  for  use  by  UTF-16,  where they are used in pairs to encode
       codepoints  with  values  greater than 0xFFFF. The code points that are       codepoints with values greater than 0xFFFF. The code  points  that  are
        encoded by UTF-16 pairs are available independently in the UTF-8 encod-         encoded by UTF-16 pairs are available independently in the UTF-8 encod-
       ing.  (In  other words, the whole surrogate thing is a fudge for UTF-16       ing. (In other words, the whole surrogate thing is a fudge  for  UTF-16
        which unfortunately messes up UTF-8.)         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.
   
    Validity of UTF-16 strings     Validity of UTF-16 strings
   
        When you set the PCRE_UTF16 flag, the strings of 16-bit data units that         When you set the PCRE_UTF16 flag, the strings of 16-bit data units that
        are passed as patterns and subjects are (by default) checked for valid-         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       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         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.         the surrogate range must be used in pairs in the correct manner.
   
       If  an  invalid  UTF-16  string  is  passed to PCRE, an error return is       If an invalid UTF-16 string is passed  to  PCRE,  an  error  return  is
       given. At compile time, the only additional information is  the  offset       given.  At  compile time, the only additional information is the offset
       to  the first data unit of the failing character. The runtime functions       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         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       well as a more detailed reason code if the caller has  provided  memory
        in which to do this.         in which to do 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_UTF16_CHECK flag at compile  time  or  at       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-         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         tively) contains only valid UTF-16 sequences. In this case, it does not
        diagnose an invalid UTF-16 string.         diagnose an invalid UTF-16 string.
   
    General comments about UTF modes     General comments about UTF modes
   
       1.  Codepoints  less  than  256  can  be  specified by either braced or       1. Codepoints less than 256  can  be  specified  by  either  braced  or
       unbraced hexadecimal escape sequences (for example,  \x{b3}  or  \xb3).       unbraced  hexadecimal  escape  sequences (for example, \x{b3} or \xb3).
        Larger values have to use braced sequences.         Larger values have to use braced sequences.
   
       2.  Octal  numbers  up  to \777 are recognized, and in UTF-8 mode, they       2. Octal numbers up to \777 are recognized, and  in  UTF-8  mode,  they
        match two-byte characters for values greater than \177.         match two-byte characters for values greater than \177.
   
        3. Repeat quantifiers apply to complete UTF characters, not to individ-         3. Repeat quantifiers apply to complete UTF characters, not to individ-
        ual data units, for example: \x{100}{3}.         ual data units, for example: \x{100}{3}.
   
       4.  The dot metacharacter matches one UTF character instead of a single       4. The dot metacharacter matches one UTF character instead of a  single
        data unit.         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, or a single 16-bit data unit in UTF-16 mode, but its use can lead         mode, or a single 16-bit data unit in UTF-16 mode, but its use can lead
        to some strange effects because it breaks up multi-unit characters (see         to some strange effects because it breaks up multi-unit characters (see
       the  description of \C in the pcrepattern documentation). The use of \C       the description of \C in the pcrepattern documentation). The use of  \C
       is   not   supported   in    the    alternative    matching    function       is    not    supported    in    the   alternative   matching   function
       pcre[16]_dfa_exec(),  nor  is it supported in UTF mode by the JIT opti-       pcre[16]_dfa_exec(), nor is it supported in UTF mode by the  JIT  opti-
        mization of pcre[16]_exec(). If JIT optimization is requested for a UTF         mization of pcre[16]_exec(). If JIT optimization is requested for a UTF
        pattern that contains \C, it will not succeed, and so the matching will         pattern that contains \C, it will not succeed, and so the matching will
        be carried out by the normal interpretive function.         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  in  non-UTF  mode, all with values less than 256. This remains       set as in non-UTF mode, all with values less  than  256.  This  remains
       true even when PCRE is  built  to  include  Unicode  property  support,       true  even  when  PCRE  is  built  to include Unicode property support,
        because to do otherwise would slow down PCRE in many common cases. Note         because to do otherwise would slow down PCRE in many common cases. Note
       in particular that this applies to \b and \B, because they are  defined       in  particular that this applies to \b and \B, because they are defined
        in terms of \w and \W. If you really want to test for a wider sense of,         in terms of \w and \W. If you really want to test for a wider sense of,
       say, "digit", you can use  explicit  Unicode  property  tests  such  as       say,  "digit",  you  can  use  explicit  Unicode property tests such as
        \p{Nd}. Alternatively, if you set the PCRE_UCP option, the way that the         \p{Nd}. Alternatively, if you set the PCRE_UCP option, the way that the
       character escapes work is changed so that Unicode properties  are  used       character  escapes  work is changed so that Unicode properties are used
        to determine which characters match. There are more details in the sec-         to determine which characters match. There are more details in the sec-
        tion on 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 7022  AUTHOR Line 7074  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 13 January 2012       Last updated: 14 April 2012
        Copyright (c) 1997-2012 University of Cambridge.         Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
Line 7072  AVAILABILITY OF JIT SUPPORT Line 7124  AVAILABILITY OF JIT SUPPORT
          MIPS 32-bit           MIPS 32-bit
          Power PC 32-bit and 64-bit           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 7099  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 7118  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 7150  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 7228  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 7237  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 7266  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 7378  AUTHOR Line 7459  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 08 January 2012       Last updated: 04 May 2012
        Copyright (c) 1997-2012 University of Cambridge.         Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
Line 7422  PARTIAL MATCHING IN PCRE Line 7503  PARTIAL MATCHING IN PCRE
        matching function. If both options  are  set,  PCRE_PARTIAL_HARD  takes         matching function. If both options  are  set,  PCRE_PARTIAL_HARD  takes
        precedence.         precedence.
   
       Setting  a partial matching option disables the use of any just-in-time       If  you  want to use partial matching with just-in-time optimized code,
       code that was  set  up  by  studying  the  compiled  pattern  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 data unit in a  pattern,
       and  abandons  matching immediately if it is not present in the subject         PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE
          PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE
 
        PCRE_STUDY_JIT_COMPILE  should also be set if you are going to run non-
        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         string. This optimization cannot be used  for  a  subject  string  that
        might  match only partially. If the pattern was studied, PCRE knows the         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         minimum length of a matching string, and does not  bother  to  run  the
Line 7682  MULTI-SEGMENT MATCHING WITH pcre_exec() OR pcre16_exec Line 7772  MULTI-SEGMENT MATCHING WITH pcre_exec() OR pcre16_exec
   
        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 the matching function         add  on  text  from  the  next  segment, and call the matching function
       again. Unlike the DFA matching functions  the  entire  matching  string       again. Unlike the DFA matching functions, the  entire  matching  string
        must  always be available, and the complete matching process occurs for         must  always be available, and the complete matching process occurs for
        each call, so more memory and more processing time is needed.         each call, so more memory and more processing time is needed.
   
Line 7690  MULTI-SEGMENT MATCHING WITH pcre_exec() OR pcre16_exec Line 7780  MULTI-SEGMENT MATCHING WITH pcre_exec() OR pcre16_exec
        with \b or \B, the string that is returned for a partial match includes         with \b or \B, the string that is returned for a partial match includes
        characters that precede the partially matched  string  itself,  because         characters that precede the partially matched  string  itself,  because
        these  must be retained when adding on more characters for a subsequent         these  must be retained when adding on more characters for a 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 7699  ISSUES WITH MULTI-SEGMENT MATCHING Line 7790  ISSUES WITH MULTI-SEGMENT MATCHING
        whichever matching function is used.         whichever matching function is used.
   
        1. If the pattern contains a test for the beginning of a line, you need         1. If the pattern contains a test for the beginning of a line, you need
       to pass the PCRE_NOTBOL option when the subject  string  for  any  call       to  pass  the  PCRE_NOTBOL  option when the subject string for any call
       does  start  at  the  beginning  of a line. There is also a PCRE_NOTEOL       does start at the beginning of a line.  There  is  also  a  PCRE_NOTEOL
        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,
        what  might  be  considered a partial match of an empty string actually
        gives a "no match" result. For example:
 
            re> /c(?<=abc)x/
          data> ab\P
          No match
 
        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         not always produce exactly the same result as matching over one  single
        long  string,  especially  when  PCRE_PARTIAL_SOFT is used. The section         long  string,  especially  when  PCRE_PARTIAL_SOFT is used. The section
        "Partial Matching and Word Boundaries" above describes  an  issue  that         "Partial Matching and Word Boundaries" above describes  an  issue  that
Line 7756  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. For example, consider this pattern:         PCRE_DFA_RESTART is used. For example, consider this pattern:
   
Line 7801  AUTHOR Line 7909  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 21 January 2012       Last updated: 24 February 2012
        Copyright (c) 1997-2012 University of Cambridge.         Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
Line 8551  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 (*)
Line 8839  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 8856  AUTHOR Line 8968  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 08 January 2012       Last updated: 04 May 2012
        Copyright (c) 1997-2012 University of Cambridge.         Copyright (c) 1997-2012 University of Cambridge.
 ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
   
Removed from v.1.1.1.2  
changed lines
  Added in v.1.1.1.3

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