/[pcre]/code/trunk/doc/pcre.txt

Diff of /code/trunk/doc/pcre.txt

Parent Directory | Revision Log | View Patch Patch

-revision 73 by nigel,
Sat Feb 24 21:40:30 2007 UTC
+revision 83 by nigel,
Sat Feb 24 21:41:06 2007 UTC
 Line 1
+ -----------------------------------------------------------------------------
  This file contains a concatenation of the PCRE man pages, converted to plain
  text format for ease of searching with a text editor, or for use on systems
  that do not have a man page processor. The small individual files that give
-Line 5 
 synopses of each function in the library
+Line 6 
 synopses of each function in the library
  separate text files for the pcregrep and pcretest commands.
  -----------------------------------------------------------------------------
- PCRE(3)                                                                PCRE(3)
+ PCRE(3)                                                                PCRE(3)
  NAME
         PCRE - Perl-compatible regular expressions
- DESCRIPTION
+ INTRODUCTION
         The  PCRE  library is a set of functions that implement regular expres-
         sion pattern matching using the same syntax and semantics as Perl, with
         just  a  few  differences.  The current implementation of PCRE (release
 .x) corresponds approximately with Perl  5.8,  including  support  for
-        UTF-8  encoded  strings.   However,  this  support has to be explicitly
+        UTF-8 encoded strings and Unicode general category properties. However,
-        enabled; it is not the default.
+        this support has to be explicitly enabled; it is not the default.
-        PCRE is written in C and released as a C library. However, a number  of
+        In addition to the Perl-compatible matching function,  PCRE  also  con-
-        people  have  written  wrappers  and interfaces of various kinds. A C++
+        tains  an  alternative matching function that matches the same compiled
-        class is included in these contributions, which can  be  found  in  the
+        patterns in a different way. In certain circumstances, the  alternative
+        function  has  some  advantages.  For  a discussion of the two matching
+        algorithms, see the pcrematching page.
+        PCRE is written in C and released as a C library. A  number  of  people
+        have  written  wrappers and interfaces of various kinds. In particular,
+        Google Inc.  have provided a comprehensive C++  wrapper.  This  is  now
+        included as part of the PCRE distribution. The pcrecpp page has details
+        of this interface. Other people's contributions can  be  found  in  the
         Contrib directory at the primary FTP site, which is:
         ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre
-Line 34 
 DESCRIPTION
+Line 44 
 DESCRIPTION
         Some  features  of  PCRE can be included, excluded, or changed when the
         library is built. The pcre_config() function makes it  possible  for  a
-        client  to  discover  which features are available. Documentation about
+        client  to  discover  which  features are available. The features them-
-        building PCRE for various operating systems can be found in the  README
+        selves are described in the pcrebuild page. Documentation about  build-
-        file in the source distribution.
+        ing  PCRE for various operating systems can be found in the README file
+        in the source distribution.
+        The library contains a number of undocumented  internal  functions  and
+        data  tables  that  are  used by more than one of the exported external
+        functions, but which are not intended  for  use  by  external  callers.
+        Their  names  all begin with "_pcre_", which hopefully will not provoke
+        any name clashes. In some environments, it is possible to control which
+        external  symbols  are  exported when a shared library is built, and in
+        these cases the undocumented symbols are not exported.
  USER DOCUMENTATION
-        The user documentation for PCRE has been split up into a number of dif-
+        The user documentation for PCRE comprises a number  of  different  sec-
-        ferent sections. In the "man" format, each of these is a separate  "man
+        tions.  In the "man" format, each of these is a separate "man page". In
-        page".  In  the  HTML  format, each is a separate page, linked from the
+        the HTML format, each is a separate page, linked from the  index  page.
-        index page. In the plain text format, all  the  sections  are  concate-
+        In  the  plain text format, all the sections are concatenated, for ease
-        nated, for ease of searching. The sections are as follows:
+        of searching. The sections are as follows:
           pcre              this document
-          pcreapi           details of PCRE's native API
+          pcreapi           details of PCRE's native C API
           pcrebuild         options for building PCRE
           pcrecallout       details of the callout feature
           pcrecompat        discussion of Perl compatibility
+          pcrecpp           details of the C++ wrapper
           pcregrep          description of the pcregrep command
+          pcrematching      discussion of the two matching algorithms
+          pcrepartial       details of the partial matching facility
           pcrepattern       syntax and semantics of supported
                               regular expressions
           pcreperform       discussion of performance issues
-          pcreposix         the POSIX-compatible API
+          pcreposix         the POSIX-compatible C API
+          pcreprecompile    details of saving and re-using precompiled patterns
           pcresample        discussion of the sample program
-          pcretest          the pcretest testing command
+          pcretest          description of the pcretest testing command
         In  addition,  in the "man" and HTML formats, there is a short page for
-        each library function, listing its arguments and results.
+        each C library function, listing its arguments and results.
  LIMITATIONS
-Line 74 
 LIMITATIONS
+Line 97 
 LIMITATIONS
         process  regular  expressions  that are truly enormous, you can compile
         PCRE with an internal linkage size of 3 or 4 (see the  README  file  in
         the  source  distribution and the pcrebuild documentation for details).
-        If these cases the limit is substantially larger.  However,  the  speed
+        In these cases the limit is substantially larger.  However,  the  speed
         of execution will be slower.
         All values in repeating quantifiers must be less than 65536.  The maxi-
-Line 86 
 LIMITATIONS
+Line 109 
 LIMITATIONS
         tern, is 200.
         The  maximum  length of a subject string is the largest positive number
-        that an integer variable can hold. However, PCRE uses recursion to han-
+        that an integer variable can hold. However, when using the  traditional
-        dle  subpatterns  and indefinite repetition. This means that the avail-
+        matching function, PCRE uses recursion to handle subpatterns and indef-
-        able stack space may limit the size of a subject  string  that  can  be
+        inite repetition.  This means that the available stack space may  limit
-        processed by certain patterns.
+        the size of a subject string that can be processed by certain patterns.
- UTF-8 SUPPORT
-        Starting  at  release  3.3,  PCRE  has  had  some support for character
+ UTF-8 AND UNICODE PROPERTY SUPPORT
-        strings encoded in the UTF-8 format. For  release  4.0  this  has  been
-        greatly extended to cover most common requirements.
+        From release 3.3, PCRE has  had  some  support  for  character  strings
+        encoded  in the UTF-8 format. For release 4.0 this was greatly extended
+        to cover most common requirements, and in release 5.0  additional  sup-
+        port for Unicode general category properties was added.
         In  order  process  UTF-8 strings, you must build PCRE to include UTF-8
         support in the code, and, in addition,  you  must  call  pcre_compile()
-Line 109 
 UTF-8 SUPPORT
+Line 133 
 UTF-8 SUPPORT
         is  limited  to testing the PCRE_UTF8 flag in several places, so should
         not be very large.
+        If PCRE is built with Unicode character property support (which implies
+        UTF-8  support),  the  escape sequences \p{..}, \P{..}, and \X are sup-
+        ported.  The available properties that can be tested are limited to the
+        general  category  properties such as Lu for an upper case letter or Nd
+        for a decimal number. A full list is given in the pcrepattern  documen-
+        tation. The PCRE library is increased in size by about 90K when Unicode
+        property support is included.
         The following comments apply when PCRE is running in UTF-8 mode:
 . When you set the PCRE_UTF8 flag, the strings passed as patterns  and
-Line 136 
 UTF-8 SUPPORT
+Line 168 
 UTF-8 SUPPORT
 . Repeat quantifiers apply to complete UTF-8 characters, not to  indi-
         vidual bytes, for example: \x{100}{3}.
-.  The  dot  metacharacter  matches  one  UTF-8 character instead of a
+.  The dot metacharacter matches one UTF-8 character instead of a sin-
-        single byte.
+        gle byte.
 . The escape sequence \C can be used to match a single byte  in  UTF-8
-        mode, but its use can lead to some strange effects.
+        mode,  but  its  use can lead to some strange effects. This facility is
+        not available in the alternative matching function, pcre_dfa_exec().
-.  The  character escapes \b, \B, \d, \D, \s, \S, \w, and \W correctly
-        test characters of any code value, but the characters that PCRE  recog-
-        nizes  as  digits,  spaces,  or  word characters remain the same set as
-        before, all with values less than 256.
-. Case-insensitive matching applies only to  characters  whose  values
-        are  less  than  256.  PCRE  does  not support the notion of "case" for
-        higher-valued characters.
-. PCRE does not support the use of Unicode tables  and  properties  or
+. The character escapes \b, \B, \d, \D, \s, \S, \w, and  \W  correctly
-        the Perl escapes \p, \P, and \X.
+        test  characters of any code value, but the characters that PCRE recog-
+        nizes as digits, spaces, or word characters  remain  the  same  set  as
+        before, all with values less than 256. This remains true even when PCRE
+        includes Unicode property support, because to do otherwise  would  slow
+        down  PCRE in many common cases. If you really want to test for a wider
+        sense of, say, "digit", you must use Unicode  property  tests  such  as
+        \p{Nd}.
+.  Similarly,  characters that match the POSIX named character classes
+        are all low-valued characters.
+. Case-insensitive matching applies only to  characters  whose  values
+        are  less than 128, unless PCRE is built with Unicode property support.
+        Even when Unicode property support is available, PCRE  still  uses  its
+        own  character  tables when checking the case of low-valued characters,
+        so as not to degrade performance.  The Unicode property information  is
+        used only for characters with higher values.
  AUTHOR
-        Philip Hazel <ph10@cam.ac.uk>
+        Philip Hazel
         University Computing Service,
         Cambridge CB2 3QG, England.
-        Phone: +44 1223 334714
- Last updated: 20 August 2003
+        Putting  an actual email address here seems to have been a spam magnet,
- Copyright (c) 1997-2003 University of Cambridge.
+        so I've taken it away. If you want to email me, use my initial and sur-
- -----------------------------------------------------------------------------
+        name, separated by a dot, at the domain ucs.cam.ac.uk.
+ Last updated: 07 March 2005
+ Copyright (c) 1997-2005 University of Cambridge.
+ ------------------------------------------------------------------------------
- PCRE(3)                                                                PCRE(3)
+ PCREBUILD(3)                                                      PCREBUILD(3)
  NAME
         PCRE - Perl-compatible regular expressions
  PCRE BUILD-TIME OPTIONS
         This  document  describes  the  optional  features  of PCRE that can be
         selected when the library is compiled. They are all selected, or  dese-
-        lected,  by  providing  options  to  the  configure script which is run
+        lected, by providing options to the configure script that is run before
-        before the make command. The complete list  of  options  for  configure
+        the make command. The complete list of  options  for  configure  (which
-        (which  includes the standard ones such as the selection of the instal-
+        includes  the  standard  ones such as the selection of the installation
-        lation directory) can be obtained by running
+        directory) can be obtained by running
           ./configure --help
-Line 192 
 PCRE BUILD-TIME OPTIONS
+Line 236 
 PCRE BUILD-TIME OPTIONS
         not described.
+ C++ SUPPORT
+        By default, the configure script will search for a C++ compiler and C++
+        header files. If it finds them, it automatically builds the C++ wrapper
+        library for PCRE. You can disable this by adding
+          --disable-cpp
+        to the configure command.
  UTF-8 SUPPORT
         To build PCRE with support for UTF-8 character strings, add
-Line 204 
 UTF-8 SUPPORT
+Line 259 
 UTF-8 SUPPORT
         function.
+ UNICODE CHARACTER PROPERTY SUPPORT
+        UTF-8 support allows PCRE to process character values greater than  255
+        in  the  strings that it handles. On its own, however, it does not pro-
+        vide any facilities for accessing the properties of such characters. If
+        you  want  to  be able to use the pattern escapes \P, \p, and \X, which
+        refer to Unicode character properties, you must add
+          --enable-unicode-properties
+        to the configure command. This implies UTF-8 support, even if you  have
+        not explicitly requested it.
+        Including  Unicode  property  support  adds around 90K of tables to the
+        PCRE library, approximately doubling its size. Only the  general  cate-
+        gory  properties  such as Lu and Nd are supported. Details are given in
+        the pcrepattern documentation.
  CODE VALUE OF NEWLINE
         By default, PCRE treats character 10 (linefeed) as the newline  charac-
-Line 231 
 BUILDING SHARED AND STATIC LIBRARIES
+Line 305 
 BUILDING SHARED AND STATIC LIBRARIES
  POSIX MALLOC USAGE
-        When PCRE is called through the  POSIX  interface  (see  the  pcreposix
+        When PCRE is called through the POSIX interface (see the pcreposix doc-
-        documentation),  additional working storage is required for holding the
+        umentation),  additional  working  storage  is required for holding the
-        pointers to capturing substrings because PCRE requires  three  integers
+        pointers to capturing substrings, because PCRE requires three  integers
         per  substring,  whereas  the POSIX interface provides only two. If the
         number of expected substrings is small, the wrapper function uses space
         on the stack, because this is faster than using malloc() for each call.
-Line 247 
 POSIX MALLOC USAGE
+Line 321 
 POSIX MALLOC USAGE
  LIMITING PCRE RESOURCE USAGE
-        Internally,  PCRE  has a function called match() which it calls repeat-
+        Internally,  PCRE has a function called match(), which it calls repeat-
-        edly (possibly recursively) when performing a  matching  operation.  By
+        edly  (possibly  recursively)  when  matching  a   pattern   with   the
-        limiting  the  number of times this function may be called, a limit can
+        pcre_exec()  function.  By controlling the maximum number of times this
-        be placed on the resources used by a single call  to  pcre_exec().  The
+        function may be called during a single matching operation, a limit  can
-        limit  can be changed at run time, as described in the pcreapi documen-
+        be  placed  on  the resources used by a single call to pcre_exec(). The
-        tation. The default is 10 million, but this can be changed by adding  a
+        limit can be changed at run time, as described in the pcreapi  documen-
+        tation.  The default is 10 million, but this can be changed by adding a
         setting such as
           --with-match-limit=500000
-        to the configure command.
+        to  the  configure  command.  This  setting  has  no  effect   on   the
+        pcre_dfa_exec() matching function.
  HANDLING VERY LARGE PATTERNS
         Within  a  compiled  pattern,  offset values are used to point from one
         part to another (for example, from an opening parenthesis to an  alter-
-        nation  metacharacter).  By  default two-byte values are used for these
+        nation  metacharacter).  By default, two-byte values are used for these
         offsets, leading to a maximum size for a  compiled  pattern  of  around
 K.  This  is sufficient to handle all but the most gigantic patterns.
         Nevertheless, some people do want to process enormous patterns,  so  it
-Line 285 
 HANDLING VERY LARGE PATTERNS
+Line 361 
 HANDLING VERY LARGE PATTERNS
  AVOIDING EXCESSIVE STACK USAGE
-        PCRE  implements  backtracking while matching by making recursive calls
+        When matching with the pcre_exec() function, PCRE implements backtrack-
-        to an internal function called match(). In environments where the  size
+        ing by making recursive calls to an internal function  called  match().
-        of the stack is limited, this can severely limit PCRE's operation. (The
+        In  environments  where  the size of the stack is limited, this can se-
-        Unix environment does not usually suffer from this problem.) An  alter-
+        verely limit PCRE's operation. (The Unix environment does  not  usually
-        native  approach  that  uses  memory  from  the  heap to remember data,
+        suffer  from  this  problem.)  An alternative approach that uses memory
-        instead of using recursive function calls, has been implemented to work
+        from the heap to remember data, instead  of  using  recursive  function
-        round  this  problem. If you want to build a version of PCRE that works
+        calls,  has been implemented to work round this problem. If you want to
-        this way, add
+        build a version of PCRE that works this way, add
           --disable-stack-for-recursion
         to the configure command. With this configuration, PCRE  will  use  the
-        pcre_stack_malloc   and   pcre_stack_free   variables  to  call  memory
+        pcre_stack_malloc  and pcre_stack_free variables to call memory manage-
-        management functions. Separate functions are provided because the usage
+        ment functions. Separate functions are provided because  the  usage  is
-        is very predictable: the block sizes requested are always the same, and
+        very  predictable:  the  block sizes requested are always the same, and
         the blocks are always freed in reverse order. A calling  program  might
         be  able  to implement optimized functions that perform better than the
         standard malloc() and  free()  functions.  PCRE  runs  noticeably  more
-        slowly when built in this way.
+        slowly when built in this way. This option affects only the pcre_exec()
+        function; it is not relevant for the the pcre_dfa_exec() function.
  USING EBCDIC CODE
-        PCRE  assumes  by  default that it will run in an environment where the
+        PCRE assumes by default that it will run in an  environment  where  the
-        character code is ASCII (or UTF-8, which is a superset of ASCII).  PCRE
+        character  code  is  ASCII  (or Unicode, which is a superset of ASCII).
-        can, however, be compiled to run in an EBCDIC environment by adding
+        PCRE can, however, be compiled to  run  in  an  EBCDIC  environment  by
+        adding
           --enable-ebcdic
         to the configure command.
- Last updated: 09 December 2003
+ Last updated: 15 August 2005
- Copyright (c) 1997-2003 University of Cambridge.
+ Copyright (c) 1997-2005 University of Cambridge.
- -----------------------------------------------------------------------------
+ ------------------------------------------------------------------------------
+ PCREMATCHING(3)                                                PCREMATCHING(3)
+ NAME
+        PCRE - Perl-compatible regular expressions
+ PCRE MATCHING ALGORITHMS
+        This document describes the two different algorithms that are available
+        in PCRE for matching a compiled regular expression against a given sub-
+        ject  string.  The  "standard"  algorithm  is  the  one provided by the
+        pcre_exec() function.  This works in the same was  as  Perl's  matching
+        function, and provides a Perl-compatible matching operation.
+        An  alternative  algorithm is provided by the pcre_dfa_exec() function;
+        this operates in a different way, and is not  Perl-compatible.  It  has
+        advantages  and disadvantages compared with the standard algorithm, and
+        these are described below.
+        When there is only one possible way in which a given subject string can
+        match  a pattern, the two algorithms give the same answer. A difference
+        arises, however, when there are multiple possibilities. For example, if
+        the pattern
+          ^<.*>
+        is matched against the string
+          <something> <something else> <something further>
+        there are three possible answers. The standard algorithm finds only one
+        of them, whereas the DFA algorithm finds all three.
+ REGULAR EXPRESSIONS AS TREES
+        The set of strings that are matched by a regular expression can be rep-
+        resented  as  a  tree structure. An unlimited repetition in the pattern
+        makes the tree of infinite size, but it is still a tree.  Matching  the
+        pattern  to a given subject string (from a given starting point) can be
+        thought of as a search of the tree.  There are  two  standard  ways  to
+        search  a  tree: depth-first and breadth-first, and these correspond to
+        the two matching algorithms provided by PCRE.
+ THE STANDARD MATCHING ALGORITHM
+        In the terminology of Jeffrey Friedl's book Mastering  Regular  Expres-
+        sions,  the  standard  algorithm  is  an "NFA algorithm". It conducts a
+        depth-first search of the pattern tree. That is, it  proceeds  along  a
+        single path through the tree, checking that the subject matches what is
+        required. When there is a mismatch, the algorithm  tries  any  alterna-
+        tives  at  the  current point, and if they all fail, it backs up to the
+        previous branch point in the  tree,  and  tries  the  next  alternative
+        branch  at  that  level.  This often involves backing up (moving to the
+        left) in the subject string as well.  The  order  in  which  repetition
+        branches  are  tried  is controlled by the greedy or ungreedy nature of
+        the quantifier.
+        If a leaf node is reached, a matching string has  been  found,  and  at
+        that  point the algorithm stops. Thus, if there is more than one possi-
+        ble match, this algorithm returns the first one that it finds.  Whether
+        this  is the shortest, the longest, or some intermediate length depends
+        on the way the greedy and ungreedy repetition quantifiers are specified
+        in the pattern.
+        Because  it  ends  up  with a single path through the tree, it is rela-
+        tively straightforward for this algorithm to keep  track  of  the  sub-
+        strings  that  are  matched  by portions of the pattern in parentheses.
+        This provides support for capturing parentheses and back references.
- PCRE(3)                                                                PCRE(3)
+ THE DFA MATCHING ALGORITHM
+        DFA stands for "deterministic finite automaton", but you do not need to
+        understand the origins of that name. This algorithm conducts a breadth-
+        first search of the tree. Starting from the first matching point in the
+        subject,  it scans the subject string from left to right, once, charac-
+        ter by character, and as it does  this,  it  remembers  all  the  paths
+        through the tree that represent valid matches.
+        The  scan  continues until either the end of the subject is reached, or
+        there are no more unterminated paths. At this point,  terminated  paths
+        represent  the different matching possibilities (if there are none, the
+        match has failed).  Thus, if there is more  than  one  possible  match,
+        this algorithm finds all of them, and in particular, it finds the long-
+        est. In PCRE, there is an option to stop the algorithm after the  first
+        match (which is necessarily the shortest) has been found.
+        Note that all the matches that are found start at the same point in the
+        subject. If the pattern
+          cat(er(pillar)?)
+        is matched against the string "the caterpillar catchment",  the  result
+        will  be the three strings "cat", "cater", and "caterpillar" that start
+        at the fourth character of the subject. The algorithm does not automat-
+        ically move on to find matches that start at later positions.
+        There are a number of features of PCRE regular expressions that are not
+        supported by the DFA matching algorithm. They are as follows:
+. Because the algorithm finds all  possible  matches,  the  greedy  or
+        ungreedy  nature  of repetition quantifiers is not relevant. Greedy and
+        ungreedy quantifiers are treated in exactly the same way.
+. When dealing with multiple paths through the tree simultaneously, it
+        is  not  straightforward  to  keep track of captured substrings for the
+        different matching possibilities, and  PCRE's  implementation  of  this
+        algorithm does not attempt to do this. This means that no captured sub-
+        strings are available.
+. Because no substrings are captured, back references within the  pat-
+        tern are not supported, and cause errors if encountered.
+.  For  the same reason, conditional expressions that use a backrefer-
+        ence as the condition are not supported.
+. Callouts are supported, but the value of the  capture_top  field  is
+        always 1, and the value of the capture_last field is always -1.
+.  The \C escape sequence, which (in the standard algorithm) matches a
+        single byte, even in UTF-8 mode, is not supported because the DFA algo-
+        rithm moves through the subject string one character at a time, for all
+        active paths through the tree.
+ ADVANTAGES OF THE DFA ALGORITHM
+        Using the DFA matching algorithm provides the following advantages:
+. All possible matches (at a single point in the subject) are automat-
+        ically  found,  and  in particular, the longest match is found. To find
+        more than one match using the standard algorithm, you have to do kludgy
+        things with callouts.
+.  There is much better support for partial matching. The restrictions
+        on the content of the pattern that apply when using the standard  algo-
+        rithm  for partial matching do not apply to the DFA algorithm. For non-
+        anchored patterns, the starting position of a partial match  is  avail-
+        able.
+.  Because  the  DFA algorithm scans the subject string just once, and
+        never needs to backtrack, it is possible  to  pass  very  long  subject
+        strings  to  the matching function in several pieces, checking for par-
+        tial matching each time.
+ DISADVANTAGES OF THE DFA ALGORITHM
+        The DFA algorithm suffers from a number of disadvantages:
+. It is substantially slower than  the  standard  algorithm.  This  is
+        partly  because  it has to search for all possible matches, but is also
+        because it is less susceptible to optimization.
+. Capturing parentheses and back references are not supported.
+. The "atomic group" feature of PCRE regular expressions is supported,
+        but  does not provide the advantage that it does for the standard algo-
+        rithm.
+ Last updated: 28 February 2005
+ Copyright (c) 1997-2005 University of Cambridge.
+ ------------------------------------------------------------------------------
+ PCREAPI(3)                                                          PCREAPI(3)
  NAME
         PCRE - Perl-compatible regular expressions
- SYNOPSIS OF PCRE API
+ PCRE NATIVE API
         #include <pcre.h>
-Line 335 
 SYNOPSIS OF PCRE API
+Line 582 
 SYNOPSIS OF PCRE API
              const char **errptr, int *erroffset,
              const unsigned char *tableptr);
+        pcre *pcre_compile2(const char *pattern, int options,
+             int *errorcodeptr,
+             const char **errptr, int *erroffset,
+             const unsigned char *tableptr);
         pcre_extra *pcre_study(const pcre *code, int options,
              const char **errptr);
-Line 342 
 SYNOPSIS OF PCRE API
+Line 594 
 SYNOPSIS OF PCRE API
              const char *subject, int length, int startoffset,
              int options, int *ovector, int ovecsize);
+        int pcre_dfa_exec(const pcre *code, const pcre_extra *extra,
+             const char *subject, int length, int startoffset,
+             int options, int *ovector, int ovecsize,
+             int *workspace, int wscount);
         int pcre_copy_named_substring(const pcre *code,
              const char *subject, int *ovector,
              int stringcount, const char *stringname,
-Line 377 
 SYNOPSIS OF PCRE API
+Line 634 
 SYNOPSIS OF PCRE API
         int pcre_info(const pcre *code, int *optptr, int *firstcharptr);
+        int pcre_refcount(pcre *code, int adjust);
         int pcre_config(int what, void *where);
         char *pcre_version(void);
-Line 392 
 SYNOPSIS OF PCRE API
+Line 651 
 SYNOPSIS OF PCRE API
         int (*pcre_callout)(pcre_callout_block *);
- PCRE API
+ PCRE API OVERVIEW
         PCRE has its own native API, which is described in this document. There
         is also a set of wrapper functions that correspond to the POSIX regular
-        expression API.  These are described in the pcreposix documentation.
+        expression  API.  These  are  described in the pcreposix documentation.
+        Both of these APIs define a set of C function calls. A C++  wrapper  is
-        The  native  API  function  prototypes  are  defined in the header file
+        distributed with PCRE. It is documented in the pcrecpp page.
-        pcre.h, and on Unix systems the library itself is called libpcre.a,  so
-        can be accessed by adding -lpcre to the command for linking an applica-
+        The  native  API  C  function prototypes are defined in the header file
-        tion which calls it. The header file defines the macros PCRE_MAJOR  and
+        pcre.h, and on Unix systems the library itself is called  libpcre.   It
-        PCRE_MINOR  to  contain  the  major  and  minor release numbers for the
+        can normally be accessed by adding -lpcre to the command for linking an
-        library. Applications can use these to include  support  for  different
+        application  that  uses  PCRE.  The  header  file  defines  the  macros
-        releases.
+        PCRE_MAJOR  and  PCRE_MINOR to contain the major and minor release num-
+        bers for the library.  Applications can use these  to  include  support
-        The  functions  pcre_compile(),  pcre_study(), and pcre_exec() are used
+        for different releases of PCRE.
-        for compiling and matching regular expressions. A sample  program  that
-        demonstrates  the simplest way of using them is given in the file pcre-
+        The   functions   pcre_compile(),  pcre_compile2(),  pcre_study(),  and
-        demo.c. The pcresample documentation describes how to run it.
+        pcre_exec() are used for compiling and matching regular expressions  in
+        a  Perl-compatible  manner. A sample program that demonstrates the sim-
-        There are convenience functions for extracting captured substrings from
+        plest way of using them is provided in the file  called  pcredemo.c  in
-        a matched subject string. They are:
+        the  source distribution. The pcresample documentation describes how to
+        run it.
+        A second matching function, pcre_dfa_exec(), which is not Perl-compati-
+        ble,  is  also provided. This uses a different algorithm for the match-
+        ing. This allows it to find all possible matches (at a given  point  in
+        the  subject),  not  just  one. However, this algorithm does not return
+        captured substrings. A description of the two matching  algorithms  and
+        their  advantages  and disadvantages is given in the pcrematching docu-
+        mentation.
+        In addition to the main compiling and  matching  functions,  there  are
+        convenience functions for extracting captured substrings from a subject
+        string that is matched by pcre_exec(). They are:
           pcre_copy_substring()
           pcre_copy_named_substring()
           pcre_get_substring()
           pcre_get_named_substring()
           pcre_get_substring_list()
+          pcre_get_stringnumber()
         pcre_free_substring() and pcre_free_substring_list() are also provided,
         to free the memory used for extracted strings.
-        The function pcre_maketables() is used (optionally) to build a  set  of
+        The  function  pcre_maketables()  is  used  to build a set of character
-        character tables in the current locale for passing to pcre_compile().
+        tables  in  the  current  locale   for   passing   to   pcre_compile(),
+        pcre_exec(),  or  pcre_dfa_exec(). This is an optional facility that is
-        The  function  pcre_fullinfo()  is used to find out information about a
+        provided for specialist use.  Most  commonly,  no  special  tables  are
-        compiled pattern; pcre_info() is an obsolete version which returns only
+        passed,  in  which case internal tables that are generated when PCRE is
-        some  of  the available information, but is retained for backwards com-
+        built are used.
-        patibility.  The function pcre_version() returns a pointer to a  string
+        The function pcre_fullinfo() is used to find out  information  about  a
+        compiled  pattern; pcre_info() is an obsolete version that returns only
+        some of the available information, but is retained for  backwards  com-
+        patibility.   The function pcre_version() returns a pointer to a string
         containing the version of PCRE and its date of release.
-        The  global  variables  pcre_malloc and pcre_free initially contain the
+        The function pcre_refcount() maintains a  reference  count  in  a  data
-        entry points of the standard  malloc()  and  free()  functions  respec-
+        block  containing  a compiled pattern. This is provided for the benefit
+        of object-oriented applications.
+        The global variables pcre_malloc and pcre_free  initially  contain  the
+        entry  points  of  the  standard malloc() and free() functions, respec-
         tively. PCRE calls the memory management functions via these variables,
-        so a calling program can replace them if it  wishes  to  intercept  the
+        so  a  calling  program  can replace them if it wishes to intercept the
         calls. This should be done before calling any PCRE functions.
-        The  global  variables  pcre_stack_malloc  and pcre_stack_free are also
+        The global variables pcre_stack_malloc  and  pcre_stack_free  are  also
-        indirections to memory management functions.  These  special  functions
+        indirections  to  memory  management functions. These special functions
-        are  used  only  when  PCRE is compiled to use the heap for remembering
+        are used only when PCRE is compiled to use  the  heap  for  remembering
-        data, instead of recursive function calls. This is a  non-standard  way
+        data, instead of recursive function calls, when running the pcre_exec()
-        of  building  PCRE,  for  use in environments that have limited stacks.
+        function. This is a non-standard way of building PCRE, for use in envi-
-        Because of the greater use of memory management, it runs  more  slowly.
+        ronments that have limited stacks. Because of the greater use of memory
-        Separate  functions  are provided so that special-purpose external code
+        management, it runs more slowly.  Separate functions  are  provided  so
-        can be used for this case. When used, these functions are always called
+        that  special-purpose  external  code  can  be used for this case. When
-        in  a  stack-like  manner  (last obtained, first freed), and always for
+        used, these functions are always called in a  stack-like  manner  (last
-        memory blocks of the same size.
+        obtained,  first freed), and always for memory blocks of the same size.
         The global variable pcre_callout initially contains NULL. It can be set
         by  the  caller  to  a "callout" function, which PCRE will then call at
-Line 467 
 MULTITHREADING
+Line 748 
 MULTITHREADING
         at once.
+ SAVING PRECOMPILED PATTERNS FOR LATER USE
+        The compiled form of a regular expression can be saved and re-used at a
+        later time, possibly by a different program, and even on a  host  other
+        than  the  one  on  which  it  was  compiled.  Details are given in the
+        pcreprecompile documentation.
  CHECKING BUILD-TIME OPTIONS
         int pcre_config(int what, void *where);
-        The  function pcre_config() makes it possible for a PCRE client to dis-
+        The function pcre_config() makes it possible for a PCRE client to  dis-
         cover which optional features have been compiled into the PCRE library.
-        The  pcrebuild documentation has more details about these optional fea-
+        The pcrebuild documentation has more details about these optional  fea-
         tures.
-        The first argument for pcre_config() is an  integer,  specifying  which
+        The  first  argument  for pcre_config() is an integer, specifying which
         information is required; the second argument is a pointer to a variable
-        into which the information is  placed.  The  following  information  is
+        into  which  the  information  is  placed. The following information is
         available:
           PCRE_CONFIG_UTF8
-        The  output is an integer that is set to one if UTF-8 support is avail-
+        The output is an integer that is set to one if UTF-8 support is  avail-
         able; otherwise it is set to zero.
+          PCRE_CONFIG_UNICODE_PROPERTIES
+        The  output  is  an  integer  that is set to one if support for Unicode
+        character properties is available; otherwise it is set to zero.
           PCRE_CONFIG_NEWLINE
         The output is an integer that is set to the value of the code  that  is
-Line 516 
 CHECKING BUILD-TIME OPTIONS
+Line 810 
 CHECKING BUILD-TIME OPTIONS
           PCRE_CONFIG_STACKRECURSE
-        The output is an integer that is set to one if  internal  recursion  is
+        The output is an integer that is set to one if internal recursion  when
-        implemented  by recursive function calls that use the stack to remember
+        running pcre_exec() is implemented by recursive function calls that use
-        their state. This is the usual way that PCRE is compiled. The output is
+        the stack to remember their state. This is the usual way that  PCRE  is
-        zero  if PCRE was compiled to use blocks of data on the heap instead of
+        compiled. The output is zero if PCRE was compiled to use blocks of data
-        recursive  function  calls.  In  this   case,   pcre_stack_malloc   and
+        on the  heap  instead  of  recursive  function  calls.  In  this  case,
-        pcre_stack_free  are  called  to manage memory blocks on the heap, thus
+        pcre_stack_malloc  and  pcre_stack_free  are  called  to  manage memory
-        avoiding the use of the stack.
+        blocks on the heap, thus avoiding the use of the stack.
  COMPILING A PATTERN
-Line 531 
 COMPILING A PATTERN
+Line 825 
 COMPILING A PATTERN
              const char **errptr, int *erroffset,
              const unsigned char *tableptr);
+        pcre *pcre_compile2(const char *pattern, int options,
+             int *errorcodeptr,
+             const char **errptr, int *erroffset,
+             const unsigned char *tableptr);
-        The function pcre_compile() is called to  compile  a  pattern  into  an
+        Either of the functions pcre_compile() or pcre_compile2() can be called
-        internal  form.  The pattern is a C string terminated by a binary zero,
+        to compile a pattern into an internal form. The only difference between
-        and is passed in the argument pattern. A pointer to a single  block  of
+        the two interfaces is that pcre_compile2() has an additional  argument,
-        memory  that is obtained via pcre_malloc is returned. This contains the
+        errorcodeptr, via which a numerical error code can be returned.
-        compiled code and related data.  The  pcre  type  is  defined  for  the
-        returned  block;  this  is a typedef for a structure whose contents are
+        The pattern is a C string terminated by a binary zero, and is passed in
-        not externally defined. It is up to the caller to free the memory  when
+        the pattern argument. A pointer to a single block  of  memory  that  is
-        it is no longer required.
+        obtained  via  pcre_malloc is returned. This contains the compiled code
+        and related data. The pcre type is defined for the returned block; this
+        is a typedef for a structure whose contents are not externally defined.
+        It is up to the caller  to  free  the  memory  when  it  is  no  longer
+        required.
         Although  the compiled code of a PCRE regex is relocatable, that is, it
         does not depend on memory location, the complete pcre data block is not
-        fully relocatable, because it contains a copy of the tableptr argument,
+        fully  relocatable, because it may contain a copy of the tableptr argu-
-        which is an address (see below).
+        ment, which is an address (see below).
         The options argument contains independent bits that affect the compila-
-        tion.  It  should  be  zero  if  no  options  are required. Some of the
+        tion.  It  should  be  zero  if  no options are required. The available
-        options, in particular, those that are compatible with Perl,  can  also
+        options are described below. Some of them, in  particular,  those  that
-        be  set and unset from within the pattern (see the detailed description
+        are  compatible  with  Perl,  can also be set and unset from within the
-        of regular expressions in the  pcrepattern  documentation).  For  these
+        pattern (see the detailed description  in  the  pcrepattern  documenta-
-        options,  the  contents of the options argument specifies their initial
+        tion).  For  these options, the contents of the options argument speci-
-        settings at the start of compilation and execution.  The  PCRE_ANCHORED
+        fies their initial settings at the start of compilation and  execution.
-        option can be set at the time of matching as well as at compile time.
+        The  PCRE_ANCHORED option can be set at the time of matching as well as
+        at compile time.
         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
         sets the variable pointed to by errptr to point to a textual error mes-
-        sage. The offset from the start of the pattern to the  character  where
+        sage.  The  offset from the start of the pattern to the character where
-        the  error  was  discovered  is  placed  in  the variable pointed to by
+        the error was discovered is  placed  in  the  variable  pointed  to  by
-        erroffset, which must not be NULL. If it  is,  an  immediate  error  is
+        erroffset,  which  must  not  be  NULL. If it is, an immediate error is
         given.
+        If pcre_compile2() is used instead of pcre_compile(),  and  the  error-
+        codeptr  argument is not NULL, a non-zero error code number is returned
+        via this argument in the event of an error. This is in addition to  the
+        textual error message. Error codes and messages are listed below.
         If  the  final  argument, tableptr, is NULL, PCRE uses a default set of
-        character tables which are built when it is compiled, using the default
+        character tables that are  built  when  PCRE  is  compiled,  using  the
-        C  locale.  Otherwise,  tableptr  must  be  the  result  of  a  call to
+        default  C  locale.  Otherwise, tableptr must be an address that is the
-        pcre_maketables(). See the section on locale support below.
+        result of a call to pcre_maketables(). This value is  stored  with  the
+        compiled  pattern,  and used again by pcre_exec(), unless another table
+        pointer is passed to it. For more discussion, see the section on locale
+        support below.
-        This code fragment shows a typical straightforward  call  to  pcre_com-
+        This  code  fragment  shows a typical straightforward call to pcre_com-
         pile():
           pcre *re;
-Line 581 
 COMPILING A PATTERN
+Line 892 
 COMPILING A PATTERN
             &erroffset,       /* for error offset */
             NULL);            /* use default character tables */
-        The following option bits are defined:
+        The following names for option bits are defined in  the  pcre.h  header
+        file:
           PCRE_ANCHORED
         If this bit is set, the pattern is forced to be "anchored", that is, it
         is constrained to match only at the first matching point in the  string
-        which is being searched (the "subject string"). This effect can also be
+        that  is being searched (the "subject string"). This effect can also be
         achieved by appropriate constructs in the pattern itself, which is  the
         only way to do it in Perl.
+          PCRE_AUTO_CALLOUT
+        If this bit is set, pcre_compile() automatically inserts callout items,
+        all with number 255, before each pattern item. For  discussion  of  the
+        callout facility, see the pcrecallout documentation.
           PCRE_CASELESS
         If  this  bit is set, letters in the pattern match both upper and lower
         case letters. It is equivalent to Perl's  /i  option,  and  it  can  be
-        changed within a pattern by a (?i) option setting.
+        changed  within a pattern by a (?i) option setting. In UTF-8 mode, PCRE
+        always understands the concept of case for characters whose values  are
+        less  than 128, so caseless matching is always possible. For characters
+        with higher values, the concept of case is supported if  PCRE  is  com-
+        piled  with Unicode property support, but not otherwise. If you want to
+        use caseless matching for characters 128 and  above,  you  must  ensure
+        that  PCRE  is  compiled  with Unicode property support as well as with
+        UTF-8 support.
           PCRE_DOLLAR_ENDONLY
-        If  this bit is set, a dollar metacharacter in the pattern matches only
+        If this bit is set, a dollar metacharacter in the pattern matches  only
-        at the end of the subject string. Without this option,  a  dollar  also
+        at  the  end  of the subject string. Without this option, a dollar also
-        matches  immediately before the final character if it is a newline (but
+        matches immediately before the final character if it is a newline  (but
-        not before any  other  newlines).  The  PCRE_DOLLAR_ENDONLY  option  is
+        not  before  any  other  newlines).  The  PCRE_DOLLAR_ENDONLY option is
         ignored if PCRE_MULTILINE is set. There is no equivalent to this option
         in Perl, and no way to set it within a pattern.
           PCRE_DOTALL
         If this bit is set, a dot metacharater in the pattern matches all char-
-        acters,  including  newlines.  Without  it, newlines are excluded. This
+        acters, including newlines. Without it,  newlines  are  excluded.  This
-        option is equivalent to Perl's /s option, and it can be changed  within
+        option  is equivalent to Perl's /s option, and it can be changed within
-        a  pattern  by  a  (?s)  option  setting. A negative class such as [^a]
+        a pattern by a (?s) option setting.  A  negative  class  such  as  [^a]
-        always matches a newline character, independent of the setting of  this
+        always  matches a newline character, independent of the setting of this
         option.
           PCRE_EXTENDED
-        If  this  bit  is  set,  whitespace  data characters in the pattern are
+        If this bit is set, whitespace  data  characters  in  the  pattern  are
-        totally ignored except  when  escaped  or  inside  a  character  class.
+        totally ignored except when escaped or inside a character class. White-
-        Whitespace  does  not  include the VT character (code 11). In addition,
+        space does not include the VT character (code 11). In addition, charac-
-        characters between an unescaped # outside a  character  class  and  the
+        ters between an unescaped # outside a character class and the next new-
-        next newline character, inclusive, are also ignored. This is equivalent
+        line character, inclusive, are also  ignored.  This  is  equivalent  to
-        to Perl's /x option, and it can be changed within a pattern by  a  (?x)
+        Perl's  /x  option,  and  it  can be changed within a pattern by a (?x)
         option setting.
-        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
+        Whitespace  characters  may  never  appear  within  special   character
-        sequences in a pattern, for  example  within  the  sequence  (?(  which
+        sequences  in  a  pattern,  for  example  within the sequence (?( which
         introduces a conditional subpattern.
           PCRE_EXTRA
-        This  option  was invented in order to turn on additional functionality
+        This option was invented in order to turn on  additional  functionality
-        of PCRE that is incompatible with Perl, but it  is  currently  of  very
+        of  PCRE  that  is  incompatible with Perl, but it is currently of very
-        little  use. When set, any backslash in a pattern that is followed by a
+        little use. When set, any backslash in a pattern that is followed by  a
-        letter that has no special meaning  causes  an  error,  thus  reserving
+        letter  that  has  no  special  meaning causes an error, thus reserving
-        these  combinations  for  future  expansion.  By default, as in Perl, a
+        these combinations for future expansion. By  default,  as  in  Perl,  a
-        backslash followed by a letter with no special meaning is treated as  a
+        backslash  followed by a letter with no special meaning is treated as a
-        literal.  There  are  at  present  no other features controlled by this
+        literal. There are at present no  other  features  controlled  by  this
         option. It can also be set by a (?X) option setting within a pattern.
+          PCRE_FIRSTLINE
+        If  this  option  is  set,  an  unanchored pattern is required to match
+        before or at the first newline character in the subject string,  though
+        the matched text may continue over the newline.
           PCRE_MULTILINE
-        By default, PCRE treats the subject string as consisting  of  a  single
+        By  default,  PCRE  treats the subject string as consisting of a single
-        "line"  of  characters (even if it actually contains several newlines).
+        line of characters (even if it actually contains newlines). The  "start
-        The "start of line" metacharacter (^) matches only at the start of  the
+        of  line"  metacharacter  (^)  matches only at the start of the string,
-        string,  while  the "end of line" metacharacter ($) matches only at the
+        while the "end of line" metacharacter ($) matches only at  the  end  of
-        end of the string, or before a terminating  newline  (unless  PCRE_DOL-
+        the string, or before a terminating newline (unless PCRE_DOLLAR_ENDONLY
-        LAR_ENDONLY is set). This is the same as Perl.
+        is set). This is the same as Perl.
-        When  PCRE_MULTILINE  it  is set, the "start of line" and "end of line"
+        When PCRE_MULTILINE it is set, the "start of line" and  "end  of  line"
-        constructs match immediately following or immediately before  any  new-
+        constructs  match  immediately following or immediately before any new-
-        line  in the subject string, respectively, as well as at the very start
+        line in the subject string, respectively, as well as at the very  start
-        and end. This is equivalent to Perl's /m option, and it can be  changed
+        and  end. This is equivalent to Perl's /m option, and it can be changed
         within a pattern by a (?m) option setting. If there are no "\n" charac-
-        ters in a subject string, or no occurrences of ^ or  $  in  a  pattern,
+        ters  in  a  subject  string, or no occurrences of ^ or $ in a pattern,
         setting PCRE_MULTILINE has no effect.
           PCRE_NO_AUTO_CAPTURE
         If this option is set, it disables the use of numbered capturing paren-
-        theses in the pattern. Any opening parenthesis that is not followed  by
+        theses  in the pattern. Any opening parenthesis that is not followed by
-        ?  behaves as if it were followed by ?: but named parentheses can still
+        ? behaves as if it were followed by ?: but named parentheses can  still
-        be used for capturing (and they acquire  numbers  in  the  usual  way).
+        be  used  for  capturing  (and  they acquire numbers in the usual way).
         There is no equivalent of this option in Perl.
           PCRE_UNGREEDY
-        This  option  inverts  the "greediness" of the quantifiers so that they
+        This option inverts the "greediness" of the quantifiers  so  that  they
-        are not greedy by default, but become greedy if followed by "?". It  is
+        are  not greedy by default, but become greedy if followed by "?". It is
-        not  compatible  with Perl. It can also be set by a (?U) option setting
+        not compatible with Perl. It can also be set by a (?U)  option  setting
         within the pattern.
           PCRE_UTF8
-        This option causes PCRE to regard both the pattern and the  subject  as
+        This  option  causes PCRE to regard both the pattern and the subject as
-        strings  of  UTF-8 characters instead of single-byte character strings.
+        strings of UTF-8 characters instead of single-byte  character  strings.
-        However, it is available only if PCRE has been built to  include  UTF-8
+        However,  it is available only when PCRE is built to include UTF-8 sup-
-        support.  If  not, the use of this option provokes an error. Details of
+        port. If not, the use of this option provokes an error. Details of  how
-        how this option changes the behaviour of PCRE are given in the  section
+        this  option  changes the behaviour of PCRE are given in the section on
-        on UTF-8 support in the main pcre page.
+        UTF-8 support in the main pcre page.
           PCRE_NO_UTF8_CHECK
         When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is
-        automatically checked. If an invalid UTF-8 sequence of bytes is  found,
+        automatically  checked. If an invalid UTF-8 sequence of bytes is found,
-        pcre_compile()  returns an error. If you already know that your pattern
+        pcre_compile() returns an error. If you already know that your  pattern
-        is valid, and you want to skip this check for performance reasons,  you
+        is  valid, and you want to skip this check for performance reasons, you
-        can  set  the  PCRE_NO_UTF8_CHECK option. When it is set, the effect of
+        can set the PCRE_NO_UTF8_CHECK option. When it is set,  the  effect  of
         passing an invalid UTF-8 string as a pattern is undefined. It may cause
-        your  program  to  crash.  Note that there is a similar option for sup-
+        your program to crash.  Note that this option can  also  be  passed  to
-        pressing the checking of subject strings passed to pcre_exec().
+        pcre_exec()  and pcre_dfa_exec(), to suppress the UTF-8 validity check-
+        ing of subject strings.
+ COMPILATION ERROR CODES
+        The following table lists the error  codes  than  may  be  returned  by
+        pcre_compile2(),  along with the error messages that may be returned by
+        both compiling functions.
+ no error
+ \ at end of pattern
+ \c at end of pattern
+ unrecognized character follows \
+ numbers out of order in {} quantifier
+ number too big in {} quantifier
+ missing terminating ] for character class
+ invalid escape sequence in character class
+ range out of order in character class
+ nothing to repeat
+ operand of unlimited repeat could match the empty string
+ internal error: unexpected repeat
+ unrecognized character after (?
+ POSIX named classes are supported only within a class
+ missing )
+ reference to non-existent subpattern
+ erroffset passed as NULL
+ unknown option bit(s) set
+ missing ) after comment
+ parentheses nested too deeply
+ regular expression too large
+ failed to get memory
+ unmatched parentheses
+ internal error: code overflow
+ unrecognized character after (?<
+ lookbehind assertion is not fixed length
+ malformed number after (?(
+ conditional group contains more than two branches
+ assertion expected after (?(
+ (?R or (?digits must be followed by )
+ unknown POSIX class name
+ POSIX collating elements are not supported
+ this version of PCRE is not compiled with PCRE_UTF8 support
+ spare error
+ character value in \x{...} sequence is too large
+ invalid condition (?(0)
+ \C not allowed in lookbehind assertion
+ PCRE does not support \L, \l, \N, \U, or \u
+ number after (?C is > 255
+ closing ) for (?C expected
+ recursive call could loop indefinitely
+ unrecognized character after (?P
+ syntax error after (?P
+ two named groups have the same name
+ invalid UTF-8 string
+ support for \P, \p, and \X has not been compiled
+ malformed \P or \p sequence
+ unknown property name after \P or \p
  STUDYING A PATTERN
-        pcre_extra *pcre_study(const pcre *code, int options,
+        pcre_extra *pcre_study(const pcre *code, int options
              const char **errptr);
-        When a pattern is going to be used several times, it is worth  spending
+        If a compiled pattern is going to be used several times,  it  is  worth
-        more  time  analyzing it in order to speed up the time taken for match-
+        spending more time analyzing it in order to speed up the time taken for
-        ing. The function pcre_study() takes a pointer to a compiled pattern as
+        matching. The function pcre_study() takes a pointer to a compiled  pat-
-        its first argument. If studing the pattern produces additional informa-
+        tern as its first argument. If studying the pattern produces additional
-        tion that will help speed up matching, pcre_study() returns  a  pointer
+        information that will help speed up matching,  pcre_study()  returns  a
-        to  a  pcre_extra  block,  in  which the study_data field points to the
+        pointer  to a pcre_extra block, in which the study_data field points to
-        results of the study.
+        the results of the study.
-        The returned value from  a  pcre_study()  can  be  passed  directly  to
+        The  returned  value  from  pcre_study()  can  be  passed  directly  to
-        pcre_exec().  However,  the pcre_extra block also contains other fields
+        pcre_exec().  However,  a  pcre_extra  block also contains other fields
         that can be set by the caller before the block  is  passed;  these  are
-        described  below.  If  studying  the pattern does not produce any addi-
+        described below in the section on matching a pattern.
-        tional information, pcre_study() returns NULL. In that circumstance, if
-        the  calling  program  wants  to  pass  some  of  the  other  fields to
-        pcre_exec(), it must set up its own pcre_extra block.
-        The second argument contains option bits. At present,  no  options  are
+        If  studying  the  pattern  does not produce any additional information
-        defined for pcre_study(), and this argument should always be zero.
+        pcre_study() returns NULL. In that circumstance, if the calling program
+        wants  to  pass  any of the other fields to pcre_exec(), it must set up
+        its own pcre_extra block.
+        The second argument of pcre_study() contains option bits.  At  present,
+        no options are defined, and this argument should always be zero.
         The  third argument for pcre_study() is a pointer for an error message.
         If studying succeeds (even if no data is  returned),  the  variable  it
-Line 736 
 STUDYING A PATTERN
+Line 1125 
 STUDYING A PATTERN
         At present, studying a pattern is useful only for non-anchored patterns
         that do not have a single fixed starting character. A bitmap of  possi-
-        ble starting characters is created.
+        ble starting bytes is created.
  LOCALE SUPPORT
         PCRE  handles  caseless matching, and determines whether characters are
-        letters, digits, or whatever, by reference to a  set  of  tables.  When
+        letters digits, or whatever, by reference to a set of  tables,  indexed
-        running  in UTF-8 mode, this applies only to characters with codes less
+        by  character  value.  When running in UTF-8 mode, this applies only to
-        than 256. The library contains a default set of tables that is  created
+        characters with codes less than 128. Higher-valued  codes  never  match
-        in  the  default  C locale when PCRE is compiled. This is used when the
+        escapes  such  as  \w or \d, but can be tested with \p if PCRE is built
-        final argument of pcre_compile() is NULL, and is  sufficient  for  many
+        with Unicode character property support.
-        applications.
+        An internal set of tables is created in the default C locale when  PCRE
-        An alternative set of tables can, however, be supplied. Such tables are
+        is  built.  This  is  used when the final argument of pcre_compile() is
-        built by calling the pcre_maketables() function,  which  has  no  argu-
+        NULL, and is sufficient for many applications. An  alternative  set  of
-        ments,  in  the  relevant  locale.  The  result  can  then be passed to
+        tables  can,  however, be supplied. These may be created in a different
-        pcre_compile() as often as necessary. For example,  to  build  and  use
+        locale from the default. As more and more applications change to  using
-        tables that are appropriate for the French locale (where accented char-
+        Unicode, the need for this locale support is expected to die away.
-        acters with codes greater than 128 are treated as letters), the follow-
-        ing code could be used:
+        External  tables  are  built by calling the pcre_maketables() function,
+        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
+        example, to build and use tables that are appropriate  for  the  French
+        locale  (where  accented  characters  with  values greater than 128 are
+        treated as letters), the following code could be used:
-          setlocale(LC_CTYPE, "fr");
+          setlocale(LC_CTYPE, "fr_FR");
           tables = pcre_maketables();
           re = pcre_compile(..., tables);
-        The  tables  are  built in memory that is obtained via pcre_malloc. The
+        When pcre_maketables() runs, the tables are built  in  memory  that  is
-        pointer that is passed to pcre_compile is saved with the compiled  pat-
+        obtained  via  pcre_malloc. It is the caller's responsibility to ensure
-        tern, and the same tables are used via this pointer by pcre_study() and
+        that the memory containing the tables remains available for as long  as
-        pcre_exec(). Thus, for any single pattern,  compilation,  studying  and
+        it is needed.
-        matching  all  happen in the same locale, but different patterns can be
-        compiled in different locales. It is  the  caller's  responsibility  to
+        The pointer that is passed to pcre_compile() is saved with the compiled
-        ensure  that  the memory containing the tables remains available for as
+        pattern, and the same tables are used via this pointer by  pcre_study()
-        long as it is needed.
+        and normally also by pcre_exec(). Thus, by default, for any single pat-
+        tern, compilation, studying and matching all happen in the same locale,
+        but different patterns can be compiled in different locales.
+        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
+        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
+        run time is discussed below in the section on matching a pattern.
  INFORMATION ABOUT A PATTERN
-Line 776 
 INFORMATION ABOUT A PATTERN
+Line 1178 
 INFORMATION ABOUT A PATTERN
         int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
              int what, void *where);
-        The pcre_fullinfo() function returns information about a compiled  pat-
+        The  pcre_fullinfo() function returns information about a compiled pat-
         tern. It replaces the obsolete pcre_info() function, which is neverthe-
         less retained for backwards compability (and is documented below).
-        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:
           PCRE_ERROR_NULL       the argument code was NULL
-Line 792 
 INFORMATION ABOUT A PATTERN
+Line 1194 
 INFORMATION ABOUT A PATTERN
           PCRE_ERROR_BADMAGIC   the "magic number" was not found
           PCRE_ERROR_BADOPTION  the value of what was invalid
-        Here  is a typical call of pcre_fullinfo(), to obtain the length of the
+        The "magic number" is placed at the start of each compiled  pattern  as
-        compiled pattern:
+        an  simple check against passing an arbitrary memory pointer. Here is a
+        typical call of pcre_fullinfo(), to obtain the length of  the  compiled
+        pattern:
           int rc;
           unsigned long int length;
-Line 803 
 INFORMATION ABOUT A PATTERN
+Line 1207 
 INFORMATION ABOUT A PATTERN
             PCRE_INFO_SIZE,   /* what is required */
             &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:
           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.
           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.
+          PCRE_INFO_DEFAULT_TABLES
+        Return  a pointer to the internal default character tables within PCRE.
+        The fourth argument should point to an unsigned char *  variable.  This
+        information call is provided for internal use by the pcre_study() func-
+        tion. External callers can cause PCRE to use  its  internal  tables  by
+        passing a NULL table pointer.
           PCRE_INFO_FIRSTBYTE
-        Return information about the first byte of any matched  string,  for  a
+        Return  information  about  the first byte of any matched string, for a
-        non-anchored    pattern.    (This    option    used    to   be   called
+        non-anchored   pattern.   (This    option    used    to    be    called
-        PCRE_INFO_FIRSTCHAR; the old name is  still  recognized  for  backwards
+        PCRE_INFO_FIRSTCHAR;  the  old  name  is still recognized for backwards
         compatibility.)
-        If  there  is  a  fixed  first  byte,  e.g.  from  a  pattern  such  as
+        If there is a fixed first byte, for example, from  a  pattern  such  as
-        (cat|cow|coyote), it is returned in the integer pointed  to  by  where.
+        (cat|cow|coyote),  it  is  returned in the integer pointed to by where.
         Otherwise, 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
         (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not
         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.
           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
 -bit table indicating a fixed set of bytes for the first byte in any
-        matching  string, a pointer to the table is returned. Otherwise NULL is
+        matching string, a pointer to the table is returned. Otherwise NULL  is
-        returned. The fourth argument should point to an unsigned char *  vari-
+        returned.  The fourth argument should point to an unsigned char * vari-
         able.
           PCRE_INFO_LASTLITERAL
-        Return  the  value of the rightmost literal byte that must exist in any
+        Return the value of the rightmost literal byte that must exist  in  any
-        matched string, other than at its  start,  if  such  a  byte  has  been
+        matched  string,  other  than  at  its  start,  if such a byte has been
         recorded. The fourth argument should point to an int variable. If there
-        is no such byte, -1 is returned. For anchored patterns, a last  literal
+        is  no such byte, -1 is returned. For anchored patterns, a last literal
-        byte  is  recorded only if it follows something of variable length. For
+        byte 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
         /^a\dz\d/ the returned value is -1.
-Line 860 
 INFORMATION ABOUT A PATTERN
+Line 1272 
 INFORMATION ABOUT A PATTERN
           PCRE_INFO_NAMEENTRYSIZE
           PCRE_INFO_NAMETABLE
-        PCRE  supports the use of named as well as numbered capturing parenthe-
+        PCRE supports the use of named as well as numbered capturing  parenthe-
-        ses. The names are just an additional way of identifying the  parenthe-
+        ses.  The names are just an additional way of identifying the parenthe-
-        ses,  which still acquire a number. A caller that wants to extract data
+        ses,  which  still  acquire  numbers.  A  convenience  function  called
-        from a named subpattern must convert the name to a number in  order  to
+        pcre_get_named_substring()  is  provided  for  extracting an individual
-        access  the  correct  pointers  in  the  output  vector (described with
+        captured substring by name. It is also possible  to  extract  the  data
-        pcre_exec() below). In order to do this, it must first use these  three
+        directly,  by  first converting the name to a number in order to access
-        values to obtain the name-to-number mapping table for the pattern.
+        the correct pointers in the output vector (described  with  pcre_exec()
+        below).  To  do the conversion, you need to use the name-to-number map,
+        which is described by these three values.
         The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT
         gives the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size
-        of  each  entry;  both  of  these  return  an int value. The entry size
+        of each entry; both of these  return  an  int  value.  The  entry  size
-        depends on the length of the longest name. PCRE_INFO_NAMETABLE  returns
+        depends  on the length of the longest name. PCRE_INFO_NAMETABLE returns
-        a  pointer  to  the  first  entry of the table (a pointer to char). The
+        a pointer to the first entry of the table  (a  pointer  to  char).  The
         first two bytes of each entry are the number of the capturing parenthe-
-        sis,  most  significant byte first. The rest of the entry is the corre-
+        sis, most significant byte first. The rest of the entry is  the  corre-
-        sponding name, zero terminated. The names are  in  alphabetical  order.
+        sponding  name,  zero  terminated. The names are in alphabetical order.
-        For  example,  consider  the following pattern (assume PCRE_EXTENDED is
+        For example, consider the following pattern  (assume  PCRE_EXTENDED  is
         set, so white space - including newlines - is ignored):
           (?P<date> (?P<year>(\d\d)?\d\d) -
           (?P<month>\d\d) - (?P<day>\d\d) )
-        There are four named subpatterns, so the table has  four  entries,  and
+        There  are  four  named subpatterns, so the table has four entries, and
-        each  entry  in the table is eight bytes long. The table is as follows,
+        each entry in the table is eight bytes long. The table is  as  follows,
-        with non-printing bytes shows in hex, and undefined bytes shown as ??:
+        with non-printing bytes shows in hexadecimal, and undefined bytes shown
+        as ??:
 01 d  a  t  e  00 ??
 05 d  a  y  00 ?? ??
 04 m  o  n  t  h  00
 02 y  e  a  r  00 ??
-        When writing code to extract data from named subpatterns, remember that
+        When writing code to extract data  from  named  subpatterns  using  the
-        the length of each entry may be different for each compiled pattern.
+        name-to-number map, remember that the length of each entry is likely to
+        be different for each compiled pattern.
           PCRE_INFO_OPTIONS
-        Return  a  copy of the options with which the pattern was compiled. The
+        Return a copy of the options with which the pattern was  compiled.  The
-        fourth argument should point to an unsigned long  int  variable.  These
+        fourth  argument  should  point to an unsigned long int variable. These
         option bits are those specified in the call to pcre_compile(), modified
         by any top-level option settings within the pattern itself.
-        A pattern is automatically anchored by PCRE if  all  of  its  top-level
+        A  pattern  is  automatically  anchored by PCRE if all of its top-level
         alternatives begin with one of the following:
           ^     unless PCRE_MULTILINE is set
-Line 915 
 INFORMATION ABOUT A PATTERN
+Line 1331 
 INFORMATION ABOUT A PATTERN
           PCRE_INFO_SIZE
-        Return the size of the compiled pattern, that is, the  value  that  was
+        Return  the  size  of the compiled pattern, that is, the value that was
         passed as the argument to pcre_malloc() when PCRE was getting memory in
         which to place the compiled data. The fourth argument should point to a
         size_t variable.
           PCRE_INFO_STUDYSIZE
-        Returns  the  size of the data block pointed to by the study_data field
+        Return the size of the data block pointed to by the study_data field in
-        in a pcre_extra block. That is, it is the  value  that  was  passed  to
+        a  pcre_extra  block.  That  is,  it  is  the  value that was passed to
         pcre_malloc() when PCRE was getting memory into which to place the data
-        created by pcre_study(). The fourth argument should point to  a  size_t
+        created  by  pcre_study(). The fourth argument should point to a size_t
         variable.
-Line 933 
 OBSOLETE INFO FUNCTION
+Line 1349 
 OBSOLETE INFO FUNCTION
         int pcre_info(const pcre *code, int *optptr, int *firstcharptr);
-        The  pcre_info()  function is now obsolete because its interface is too
+        The pcre_info() function is now obsolete because its interface  is  too
-        restrictive to return all the available data about a compiled  pattern.
+        restrictive  to return all the available data about a compiled pattern.
-        New   programs   should  use  pcre_fullinfo()  instead.  The  yield  of
+        New  programs  should  use  pcre_fullinfo()  instead.  The   yield   of
-        pcre_info() is the number of capturing subpatterns, or one of the  fol-
+        pcre_info()  is the number of capturing subpatterns, or one of the fol-
         lowing negative numbers:
           PCRE_ERROR_NULL       the argument code was NULL
           PCRE_ERROR_BADMAGIC   the "magic number" was not found
-        If  the  optptr  argument is not NULL, a copy of the options with which
+        If the optptr argument is not NULL, a copy of the  options  with  which
-        the pattern was compiled is placed in the integer  it  points  to  (see
+        the  pattern  was  compiled  is placed in the integer it points to (see
         PCRE_INFO_OPTIONS above).
-        If  the  pattern  is  not anchored and the firstcharptr argument is not
+        If the pattern is not anchored and the  firstcharptr  argument  is  not
-        NULL, it is used to pass back information about the first character  of
+        NULL,  it is used to pass back information about the first character of
         any matched string (see PCRE_INFO_FIRSTBYTE above).
- MATCHING A PATTERN
+ REFERENCE COUNTS
+        int pcre_refcount(pcre *code, int adjust);
+        The pcre_refcount() function is used to maintain a reference  count  in
+        the data block that contains a compiled pattern. It is provided for the
+        benefit of applications that  operate  in  an  object-oriented  manner,
+        where different parts of the application may be using the same compiled
+        pattern, but you want to free the block when they are all done.
+        When a pattern is compiled, the reference count field is initialized to
+        zero.   It is changed only by calling this function, whose action is to
+        add the adjust value (which may be positive or  negative)  to  it.  The
+        yield of the function is the new value. However, the value of the count
+        is constrained to lie between 0 and 65535, inclusive. If the new  value
+        is outside these limits, it is forced to the appropriate limit value.
+        Except  when it is zero, the reference count is not correctly preserved
+        if a pattern is compiled on one host and then  transferred  to  a  host
+        whose byte-order is different. (This seems a highly unlikely scenario.)
+ MATCHING A PATTERN: THE TRADITIONAL FUNCTION
         int pcre_exec(const pcre *code, const pcre_extra *extra,
              const char *subject, int length, int startoffset,
              int options, int *ovector, int ovecsize);
-        The  function pcre_exec() is called to match a subject string against a
+        The function pcre_exec() is called to match a subject string against  a
-        pre-compiled pattern, which is passed in the code argument. If the pat-
+        compiled  pattern, which is passed in the code argument. If the pattern
-        tern  has been studied, the result of the study should be passed in the
+        has been studied, the result of the study should be passed in the extra
-        extra argument.
+        argument.  This  function is the main matching facility of the library,
+        and it operates in a Perl-like manner. For specialist use there is also
+        an  alternative matching function, which is described below in the sec-
+        tion about the pcre_dfa_exec() function.
+        In most applications, the pattern will have been compiled (and  option-
+        ally  studied)  in the same process that calls pcre_exec(). However, it
+        is possible to save compiled patterns and study data, and then use them
+        later  in  different processes, possibly even on different hosts. For a
+        discussion about this, see the pcreprecompile documentation.
         Here is an example of a simple call to pcre_exec():
-Line 973 
 MATCHING A PATTERN
+Line 1420 
 MATCHING A PATTERN
 ,             /* the length of the subject string */
 ,              /* start at offset 0 in the subject */
 ,              /* default options */
-            ovector,        /* vector for substring information */
+            ovector,        /* vector of integers for substring information */
-);            /* number of elements in the vector */
+);            /* number of elements (NOT size in bytes) */
+    Extra data for pcre_exec()
         If the extra argument is not NULL, it must point to a  pcre_extra  data
         block.  The pcre_study() function returns such a block (when it doesn't
         return NULL), but you can also create one for yourself, and pass  addi-
-        tional information in it. The fields in the block are as follows:
+        tional  information in it. The fields in a pcre_extra block are as fol-
+        lows:
           unsigned long int flags;
           void *study_data;
           unsigned long int match_limit;
           void *callout_data;
+          const unsigned char *tables;
-        The  flags  field  is a bitmap that specifies which of the other fields
+        The flags field is a bitmap that specifies which of  the  other  fields
         are set. The flag bits are:
           PCRE_EXTRA_STUDY_DATA
           PCRE_EXTRA_MATCH_LIMIT
           PCRE_EXTRA_CALLOUT_DATA
+          PCRE_EXTRA_TABLES
-        Other flag bits should be set to zero. The study_data field is  set  in
+        Other  flag  bits should be set to zero. The study_data field is set in
-        the  pcre_extra  block  that is returned by pcre_study(), together with
+        the pcre_extra block that is returned by  pcre_study(),  together  with
-        the appropriate flag bit. You should not set this yourself, but you can
+        the appropriate flag bit. You should not set this yourself, but you may
-        add to the block by setting the other fields.
+        add to the block by setting the other fields  and  their  corresponding
+        flag bits.
         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
         match,  but  which  have  a very large number of possibilities in their
         search trees. The classic  example  is  the  use  of  nested  unlimited
-        repeats. Internally, PCRE uses a function called match() which it calls
+        repeats.
-        repeatedly (sometimes recursively). The limit is imposed on the  number
-        of  times  this function is called during a match, which has the effect
+        Internally,  PCRE uses a function called match() which it calls repeat-
-        of limiting the amount of recursion  and  backtracking  that  can  take
+        edly (sometimes recursively). The limit is imposed  on  the  number  of
-        place.  For  patterns that are not anchored, the count starts from zero
+        times  this  function is called during a match, which has the effect of
-        for each position in the subject string.
+        limiting the amount of recursion and backtracking that can take  place.
+        For patterns that are not anchored, the count starts from zero for each
+        position in the subject string.
         The default limit for the library can be set when PCRE  is  built;  the
         default  default  is 10 million, which handles all but the most extreme
-Line 1019 
 MATCHING A PATTERN
+Line 1474 
 MATCHING A PATTERN
         The  pcre_callout  field is used in conjunction with the "callout" fea-
         ture, which is described in the pcrecallout documentation.
-        The PCRE_ANCHORED option can be passed in the options  argument,  whose
+        The tables field  is  used  to  pass  a  character  tables  pointer  to
-        unused  bits  must  be zero. This limits pcre_exec() to matching at the
+        pcre_exec();  this overrides the value that is stored with the compiled
-        first matching position.  However,  if  a  pattern  was  compiled  with
+        pattern. A non-NULL value is stored with the compiled pattern  only  if
-        PCRE_ANCHORED,  or turned out to be anchored by virtue of its contents,
+        custom  tables  were  supplied to pcre_compile() via its tableptr argu-
-        it cannot be made unachored at matching time.
+        ment.  If NULL is passed to pcre_exec() using this mechanism, it forces
+        PCRE's  internal  tables  to be used. This facility is helpful when re-
-        When PCRE_UTF8 was set at compile time, the validity of the subject  as
+        using patterns that have been saved after compiling  with  an  external
-        a  UTF-8  string is automatically checked, and the value of startoffset
+        set  of  tables,  because  the  external tables might be at a different
-        is also checked to ensure that it points to the start of a UTF-8  char-
+        address when pcre_exec() is called. See the  pcreprecompile  documenta-
-        acter.  If  an  invalid  UTF-8  sequence of bytes is found, pcre_exec()
+        tion for a discussion of saving compiled patterns for later use.
-        returns  the  error  PCRE_ERROR_BADUTF8.  If  startoffset  contains  an
-        invalid value, PCRE_ERROR_BADUTF8_OFFSET is returned.
+    Option bits for pcre_exec()
-        If  you  already  know that your subject is valid, and you want to skip
+        The  unused  bits of the options argument for pcre_exec() must be zero.
-        these   checks   for   performance   reasons,   you   can    set    the
+        The  only  bits  that  may  be  set  are  PCRE_ANCHORED,   PCRE_NOTBOL,
-        PCRE_NO_UTF8_CHECK  option  when calling pcre_exec(). You might want to
+        PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK and PCRE_PARTIAL.
-        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
+          PCRE_ANCHORED
-        string. However, you should be  sure  that  the  value  of  startoffset
-        points  to  the  start of a UTF-8 character. When PCRE_NO_UTF8_CHECK is
-        set, the effect of passing an invalid UTF-8 string as a subject,  or  a
-        value  of startoffset that does not point to the start of a UTF-8 char-
-        acter, is undefined. Your program may crash.
-        There are also three further options that can be set only  at  matching
+        The  PCRE_ANCHORED  option  limits pcre_exec() to matching at the first
-        time:
+        matching position. If a pattern was  compiled  with  PCRE_ANCHORED,  or
+        turned  out to be anchored by virtue of its contents, it cannot be made
+        unachored at matching time.
           PCRE_NOTBOL
-        The  first  character  of the string is not the beginning of a line, so
+        This option specifies that first character of the subject string is not
-        the circumflex metacharacter should not match before it.  Setting  this
+        the  beginning  of  a  line, so the circumflex metacharacter should not
-        without  PCRE_MULTILINE  (at  compile  time) causes circumflex never to
+        match before it. Setting this without PCRE_MULTILINE (at compile  time)
-        match.
+        causes  circumflex  never to match. This option affects only the behav-
+        iour of the circumflex metacharacter. It does not affect \A.
           PCRE_NOTEOL
-        The end of the string is not the end of a line, so the dollar metachar-
+        This option specifies that the end of the subject string is not the end
-        acter  should  not  match  it  nor (except in multiline mode) a newline
+        of  a line, so the dollar metacharacter should not match it nor (except
-        immediately before it. Setting this without PCRE_MULTILINE (at  compile
+        in multiline mode) a newline immediately before it. Setting this  with-
-        time) causes dollar never to match.
+        out PCRE_MULTILINE (at compile time) causes dollar never to match. This
+        option affects only the behaviour of the dollar metacharacter. It  does
+        not affect \Z or \z.
           PCRE_NOTEMPTY
-Line 1078 
 MATCHING A PATTERN
+Line 1533 
 MATCHING A PATTERN
         cial case of a pattern match of the empty  string  within  its  split()
         function,  and  when  using  the /g modifier. It is possible to emulate
         Perl's behaviour after matching a null string by first trying the match
-        again at the same offset with PCRE_NOTEMPTY set, and then if that fails
+        again at the same offset with PCRE_NOTEMPTY and PCRE_ANCHORED, and then
-        by advancing the starting offset (see below)  and  trying  an  ordinary
+        if that fails by advancing the starting offset (see below)  and  trying
-        match again.
+        an ordinary match again. There is some code that demonstrates how to do
+        this in the pcredemo.c sample program.
-        The  subject string is passed to pcre_exec() as a pointer in subject, a
-        length in length, and a starting byte offset in startoffset. Unlike the
+          PCRE_NO_UTF8_CHECK
-        pattern  string,  the  subject  may contain binary zero bytes. When the
-        starting offset is zero, the search for a match starts at the beginning
+        When PCRE_UTF8 is set at compile time, the validity of the subject as a
-        of the subject, and this is by far the most common case.
+        UTF-8  string is automatically checked when pcre_exec() is subsequently
+        called.  The value of startoffset is also checked  to  ensure  that  it
-        If the pattern was compiled with the PCRE_UTF8 option, the subject must
+        points  to the start of a UTF-8 character. If an invalid UTF-8 sequence
-        be a sequence of bytes that is a valid UTF-8 string, and  the  starting
+        of bytes is found, pcre_exec() returns the error PCRE_ERROR_BADUTF8. If
-        offset  must point to the beginning of a UTF-8 character. If an invalid
+        startoffset  contains  an  invalid  value, PCRE_ERROR_BADUTF8_OFFSET is
-        UTF-8 string or offset is passed, an error  (either  PCRE_ERROR_BADUTF8
+        returned.
-        or   PCRE_ERROR_BADUTF8_OFFSET)   is   returned,   unless   the  option
-        PCRE_NO_UTF8_CHECK is set,  in  which  case  PCRE's  behaviour  is  not
+        If you already know that your subject is valid, and you  want  to  skip
-        defined.
+        these    checks    for   performance   reasons,   you   can   set   the
+        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
+        making repeated calls to find all  the  matches  in  a  single  subject
+        string.  However,  you  should  be  sure  that the value of startoffset
+        points to the start of a UTF-8 character.  When  PCRE_NO_UTF8_CHECK  is
+        set,  the  effect of passing an invalid UTF-8 string as a subject, or a
+        value of startoffset that does not point to the start of a UTF-8  char-
+        acter, is undefined. Your program may crash.
+          PCRE_PARTIAL
+        This  option  turns  on  the  partial  matching feature. If the subject
+        string fails to match the pattern, but at some point during the  match-
+        ing  process  the  end of the subject was reached (that is, the subject
+        partially matches the pattern and the failure to  match  occurred  only
+        because  there were not enough subject characters), pcre_exec() returns
+        PCRE_ERROR_PARTIAL instead of PCRE_ERROR_NOMATCH. When PCRE_PARTIAL  is
+        used,  there  are restrictions on what may appear in the pattern. These
+        are discussed in the pcrepartial documentation.
+    The string to be matched by pcre_exec()
+        The subject string is passed to pcre_exec() as a pointer in subject,  a
+        length  in  length, and a starting byte offset in startoffset. In UTF-8
+        mode, the byte offset must point to the start  of  a  UTF-8  character.
+        Unlike  the  pattern string, the subject may contain binary zero bytes.
+        When the starting offset is zero, the search for a match starts at  the
+        beginning of the subject, and this is by far the most common case.
         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-
-Line 1111 
 MATCHING A PATTERN
+Line 1594 
 MATCHING A PATTERN
         the  remainder  of  the  subject,  namely  "issipi", it does not match,
         because \B is always false at the start of the subject, which is deemed
         to  be  a  word  boundary. However, if pcre_exec() is passed the entire
-        string again, but with startoffset  set  to  4,  it  finds  the  second
+        string again, but with startoffset set to 4, it finds the second occur-
-        occurrence  of  "iss"  because  it  is able to look behind the starting
+        rence  of "iss" because it is able to look behind the starting point to
-        point to discover that it is preceded by a letter.
+        discover that it is preceded by a letter.
         If a non-zero starting offset is passed when the pattern  is  anchored,
-        one  attempt  to match at the given offset is tried. This can only suc-
+        one attempt to match at the given offset is made. This can only succeed
-        ceed if the pattern does not require the match to be at  the  start  of
+        if the pattern does not require the match to be at  the  start  of  the
-        the subject.
+        subject.
+    How pcre_exec() returns captured substrings
         In  general, a pattern matches a certain portion of the subject, and in
         addition, further substrings from the subject  may  be  picked  out  by
-Line 1130 
 MATCHING A PATTERN
+Line 1615 
 MATCHING A PATTERN
         Captured  substrings are returned to the caller via a vector of integer
         offsets whose address is passed in ovector. The number of  elements  in
-        the vector is passed in ovecsize. The first two-thirds of the vector is
+        the  vector is passed in ovecsize, which must be a non-negative number.
-        used to pass back captured substrings, each substring using a  pair  of
+        Note: this argument is NOT the size of ovector in bytes.
-        integers.  The  remaining  third  of the vector is used as workspace by
-        pcre_exec() while matching capturing subpatterns, and is not  available
+        The first two-thirds of the vector is used to pass back  captured  sub-
-        for  passing  back  information.  The  length passed in ovecsize should
+        strings,  each  substring using a pair of integers. The remaining third
-        always be a multiple of three. If it is not, it is rounded down.
+        of the vector is used as workspace by pcre_exec() while  matching  cap-
+        turing  subpatterns, and is not available for passing back information.
-        When a match has been successful, information about captured substrings
+        The length passed in ovecsize should always be a multiple of three.  If
-        is returned in pairs of integers, starting at the beginning of ovector,
+        it is not, it is rounded down.
-        and continuing up to two-thirds of its length at the  most.  The  first
+        When  a  match  is successful, information about captured substrings is
+        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
         element of a pair is set to the offset of the first character in a sub-
-        string, and the second is set to the  offset  of  the  first  character
+        string,  and  the  second  is  set to the offset of the first character
-        after  the  end  of  a  substring. The first pair, ovector[0] and ovec-
+        after the end of a substring. The  first  pair,  ovector[0]  and  ovec-
-        tor[1], identify the portion of  the  subject  string  matched  by  the
+        tor[1],  identify  the  portion  of  the  subject string matched by the
-        entire  pattern.  The next pair is used for the first capturing subpat-
+        entire pattern. The next pair is used for the first  capturing  subpat-
-        tern, and so on. The value returned by pcre_exec()  is  the  number  of
+        tern,  and  so  on.  The value returned by pcre_exec() is the number of
-        pairs  that  have  been set. If there are no capturing subpatterns, the
+        pairs that have been set. If there are no  capturing  subpatterns,  the
-        return value from a successful match is 1,  indicating  that  just  the
+        return  value  from  a  successful match is 1, indicating that just the
         first pair of offsets has been set.
-        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  in  the  following
+        substrings  as  separate  strings. These are described in the following
         section.
-        It  is  possible  for  an capturing subpattern number n+1 to match some
+        It is possible for an capturing subpattern number  n+1  to  match  some
-        part of the subject when subpattern n has not been  used  at  all.  For
+        part  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)
-        subpatterns 1 and 3 are matched, but 2 is not. When this happens,  both
+        subpatterns  1 and 3 are matched, but 2 is not. When this happens, both
         offset values corresponding to the unused subpattern are set to -1.
         If a capturing subpattern is matched repeatedly, it is the last portion
-        of the string that it matched that gets returned.
+        of the string that it matched that is returned.
-        If the vector is too small to hold all the captured substrings,  it  is
+        If  the vector is too small to hold all the captured substring offsets,
-        used as far as possible (up to two-thirds of its length), and the func-
+        it is used as far as possible (up to two-thirds of its length), and the
-        tion returns a value of zero. In particular, if the  substring  offsets
+        function  returns a value of zero. In particular, if the substring off-
-        are  not  of interest, pcre_exec() may be called with ovector passed as
+        sets are not of interest, pcre_exec() may be called with ovector passed
-        NULL and ovecsize as zero. However, if the pattern contains back refer-
+        as  NULL  and  ovecsize  as zero. However, if the pattern contains back
-        ences  and  the  ovector  isn't big enough to remember the related sub-
+        references and the ovector is not big enough to  remember  the  related
-        strings, PCRE has to get additional memory  for  use  during  matching.
+        substrings,  PCRE has to get additional memory for use during matching.
         Thus it is usually advisable to supply an ovector.
-        Note  that  pcre_info() can be used to find out how many capturing sub-
+        Note that pcre_info() can be used to find out how many  capturing  sub-
         patterns there are in a compiled pattern. The smallest size for ovector
-        that  will  allow for n captured substrings, in addition to the offsets
+        that will allow for n captured substrings, in addition to  the  offsets
         of the substring matched by the whole pattern, is (n+1)*3.
-        If pcre_exec() fails, it returns a negative number. The  following  are
+    Return values from pcre_exec()
+        If  pcre_exec()  fails, it returns a negative number. The following are
         defined in the header file:
           PCRE_ERROR_NOMATCH        (-1)
-Line 1186 
 MATCHING A PATTERN
+Line 1676 
 MATCHING A PATTERN
           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.
           PCRE_ERROR_BADOPTION      (-3)
-Line 1195 
 MATCHING A PATTERN
+Line 1685 
 MATCHING A PATTERN
           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. This is the error
+        to catch the case when it is passed a junk pointer and to detect when a
-        it gives when the magic number isn't present.
+        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
+        gives when the magic number is not present.
           PCRE_ERROR_UNKNOWN_NODE   (-5)
         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.
           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,
-        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 freed at the end of matching.
+        memory is automatically freed at the end of matching.
           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
         returned by pcre_exec().
           PCRE_ERROR_MATCHLIMIT     (-8)
-        The recursion and backtracking limit, as specified by  the  match_limit
+        The  recursion  and backtracking limit, as specified by the match_limit
-        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.
           PCRE_ERROR_CALLOUT        (-9)
         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.
           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.
           PCRE_ERROR_BADUTF8_OFFSET (-11)
         The UTF-8 byte sequence that was passed as a subject was valid, 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.
+          PCRE_ERROR_PARTIAL        (-12)
+        The subject string did not match, but it did match partially.  See  the
+        pcrepartial documentation for details of partial matching.
+          PCRE_ERROR_BADPARTIAL     (-13)
+        The  PCRE_PARTIAL  option  was  used with a compiled pattern containing
+        items that are not supported for partial matching. See the  pcrepartial
+        documentation for details of partial matching.
+          PCRE_ERROR_INTERNAL       (-14)
+        An  unexpected  internal error has occurred. This error could be caused
+        by a bug in PCRE or by overwriting of the compiled pattern.
+          PCRE_ERROR_BADCOUNT       (-15)
+        This error is given if the value of the ovecsize argument is  negative.
  EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
-Line 1267 
 EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
+Line 1779 
 EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
         not, of course, a C string.
         The  first  three  arguments  are the same for all three of these func-
-        tions: subject is the subject string which 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
         passed to pcre_exec(), and stringcount is the number of substrings that
         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 ran out of space in ovector, the value passed as stringcount  should
-        be the size of 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
         single substring, whose number is given as  stringnumber.  A  value  of
-        zero  extracts  the  substring  that  matched the entire pattern, while
+        zero  extracts  the  substring that matched the entire pattern, whereas
         higher values  extract  the  captured  substrings.  For  pcre_copy_sub-
         string(),  the  string  is  placed  in buffer, whose length is given by
         buffersize, while for pcre_get_substring() a new  block  of  memory  is
-Line 1297 
 EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
+Line 1809 
 EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
         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
-        single block of memory which is obtained via pcre_malloc.  The  address
+        single block of memory that is obtained via pcre_malloc. The address of
-        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
         pointer. The yield of the function is zero if all went well, or
-Line 1313 
 EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
+Line 1825 
 EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
         string  by inspecting the appropriate offset in ovector, which is nega-
         tive for unset substrings.
-        The    two    convenience    functions    pcre_free_substring()     and
+        The two convenience functions pcre_free_substring() and  pcre_free_sub-
-        pcre_free_substring_list() can be used to free the memory returned by a
+        string_list()  can  be  used  to free the memory returned by a previous
-        previous call  of  pcre_get_substring()  or  pcre_get_substring_list(),
+        call  of  pcre_get_substring()  or  pcre_get_substring_list(),  respec-
-        respectively. 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.
         However,  PCRE is used in some situations where it is linked via a spe-
         cial  interface  to  another  programming  language  which  cannot  use
-Line 1326 
 EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
+Line 1838 
 EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
  EXTRACTING CAPTURED SUBSTRINGS BY NAME
+        int pcre_get_stringnumber(const pcre *code,
+             const char *name);
         int pcre_copy_named_substring(const pcre *code,
              const char *subject, int *ovector,
              int stringcount, const char *stringname,
              char *buffer, int buffersize);
-        int pcre_get_stringnumber(const pcre *code,
-             const char *name);
         int pcre_get_named_substring(const pcre *code,
              const char *subject, int *ovector,
              int stringcount, const char *stringname,
              const char **stringptr);
         To extract a substring by name, you first have to find associated  num-
-        ber.  This  can  be  done by calling pcre_get_stringnumber(). The first
+        ber.  For example, for this pattern
-        argument is the compiled pattern, and the second is the name. For exam-
-        ple, for this pattern
+          (a+)b(?P<xxx>\d+)...
-          ab(?<xxx>\d+)...
+        the number of the subpattern called "xxx" is 2. You can find the number
+        from the name by calling pcre_get_stringnumber(). The first argument is
-        the  number  of the subpattern called "xxx" is 1. Given the number, you
+        the  compiled  pattern,  and  the  second is the name. The yield of the
-        can then extract the substring directly, or use one  of  the  functions
+        function is the subpattern number, or  PCRE_ERROR_NOSUBSTRING  (-7)  if
-        described  in the previous section. For convenience, there are also two
+        there is no subpattern of that name.
-        functions that do the whole job.
+        Given the number, you can extract the substring directly, or use one of
-        Most   of   the   arguments    of    pcre_copy_named_substring()    and
+        the functions described in the previous section. For convenience, there
-        pcre_get_named_substring() are the same as those for the functions that
+        are also two functions that do the whole job.
-        extract by number, and so are not re-described here. There are just two
-        differences.
+        Most    of    the    arguments   of   pcre_copy_named_substring()   and
+        pcre_get_named_substring() are the same  as  those  for  the  similarly
+        named  functions  that extract by number. As these are described in the
+        previous section, they are not re-described here. There  are  just  two
+        differences:
         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
-Line 1365 
 EXTRACTING CAPTURED SUBSTRINGS BY NAME
+Line 1881 
 EXTRACTING CAPTURED SUBSTRINGS BY NAME
         then  call  pcre_copy_substring() or pcre_get_substring(), as appropri-
         ate.
- Last updated: 09 December 2003
- Copyright (c) 1997-2003 University of Cambridge.
- -----------------------------------------------------------------------------
- PCRE(3)                                                                PCRE(3)
+ FINDING ALL POSSIBLE MATCHES
+        The traditional matching function uses a  similar  algorithm  to  Perl,
+        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
+        possible  match,  consider using the alternative matching function (see
+        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
+        of the callout facility, which is described in the pcrecallout documen-
+        tation.
+        What you have to do is to insert a callout right at the end of the pat-
+        tern.  When your callout function is called, extract and save the  cur-
+        rent  matched  substring.  Then  return  1, which forces pcre_exec() to
+        backtrack and try other alternatives. Ultimately, when it runs  out  of
+        matches, pcre_exec() will yield PCRE_ERROR_NOMATCH.
+ MATCHING A PATTERN: THE ALTERNATIVE FUNCTION
+        int pcre_dfa_exec(const pcre *code, const pcre_extra *extra,
+             const char *subject, int length, int startoffset,
+             int options, int *ovector, int ovecsize,
+             int *workspace, int wscount);
+        The  function  pcre_dfa_exec()  is  called  to  match  a subject string
+        against a compiled pattern, using a "DFA" matching algorithm. This  has
+        different  characteristics to the normal algorithm, and is not compati-
+        ble with Perl. Some of the features of PCRE patterns are not supported.
+        Nevertheless, there are times when this kind of matching can be useful.
+        For a discussion of the two matching algorithms, see  the  pcrematching
+        documentation.
+        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-
+        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
+        repeated here.
+        The  two  additional  arguments provide workspace for the function. The
+        workspace vector should contain at least 20 elements. It  is  used  for
+        keeping  track  of  multiple  paths  through  the  pattern  tree.  More
+        workspace will be needed for patterns and subjects where  there  are  a
+        lot of possible matches.
+        Here is an example of a simple call to pcre_exec():
+          int rc;
+          int ovector[10];
+          int wspace[20];
+          rc = pcre_exec(
+            re,             /* result of pcre_compile() */
+            NULL,           /* we didn't study the pattern */
+            "some string",  /* the subject string */
+,             /* the length of the subject string */
+,              /* start at offset 0 in the subject */
+,              /* default options */
+            ovector,        /* vector of integers for substring information */
+,             /* number of elements (NOT size in bytes) */
+            wspace,         /* working space vector */
+);            /* number of elements (NOT size in bytes) */
+    Option bits for pcre_dfa_exec()
+        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_NOTBOL,
+        PCRE_NOTEOL,     PCRE_NOTEMPTY,    PCRE_NO_UTF8_CHECK,    PCRE_PARTIAL,
+        PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART. All  but  the  last  three  of
+        these  are  the  same  as  for pcre_exec(), so their description is not
+        repeated here.
+          PCRE_PARTIAL
+        This has the same general effect as it does for  pcre_exec(),  but  the
+        details   are   slightly   different.  When  PCRE_PARTIAL  is  set  for
+        pcre_dfa_exec(), the return 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 there is still at least one matching pos-
+        sibility.  The portion of the string that provided the partial match is
+        set as the first matching string.
+          PCRE_DFA_SHORTEST
+        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 DFA
+        algorithm works, this is necessarily the shortest possible match at the
+        first possible matching point in the subject string.
+          PCRE_DFA_RESTART
+        When  pcre_dfa_exec()  is  called  with  the  PCRE_PARTIAL  option, and
+        returns a partial match, it is possible to call it  again,  with  addi-
+        tional  subject  characters,  and have it continue with the same match.
+        The PCRE_DFA_RESTART option requests this action; when it is  set,  the
+        workspace  and wscount options must reference the same vector as before
+        because data about the match so far is left in  them  after  a  partial
+        match.  There  is  more  discussion of this facility in the pcrepartial
+        documentation.
+    Successful returns from pcre_dfa_exec()
+        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
+        of the function start at the same point in  the  subject.  The  shorter
+        matches  are all initial substrings of the longer matches. For example,
+        if the pattern
+          <.*>
+        is matched against the string
+          This is <something> <something else> <something further> no more
+        the three matched strings are
+          <something>
+          <something> <something else>
+          <something> <something else> <something further>
+        On success, the yield of the function is a number  greater  than  zero,
+        which  is  the  number of matched substrings. The substrings themselves
+        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. 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 compatibility
+        with the way pcre_exec() returns data, even though the meaning  of  the
+        strings is different.)
+        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
+        fit  into ovector, the yield of the function is zero, and the vector is
+        filled with the longest matches.
+    Error returns from pcre_dfa_exec()
+        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
+        described above.  There are in addition the following errors  that  are
+        specific to pcre_dfa_exec():
+          PCRE_ERROR_DFA_UITEM      (-16)
+        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
+        reference.
+          PCRE_ERROR_DFA_UCOND      (-17)
+        This  return is given if pcre_dfa_exec() encounters a condition item in
+        a pattern that uses a back reference for the  condition.  This  is  not
+        supported.
+          PCRE_ERROR_DFA_UMLIMIT    (-18)
+        This  return  is given if pcre_dfa_exec() is called with an extra block
+        that contains a setting of the match_limit field. This is not supported
+        (it is meaningless).
+          PCRE_ERROR_DFA_WSSIZE     (-19)
+        This  return  is  given  if  pcre_dfa_exec()  runs  out of space in the
+        workspace vector.
+          PCRE_ERROR_DFA_RECURSE    (-20)
+        When a recursive subpattern is processed, the matching  function  calls
+        itself  recursively,  using  private vectors for ovector and workspace.
+        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.
+ Last updated: 16 May 2005
+ Copyright (c) 1997-2005 University of Cambridge.
+ ------------------------------------------------------------------------------
+ PCRECALLOUT(3)                                                  PCRECALLOUT(3)
  NAME
         PCRE - Perl-compatible regular expressions
  PCRE CALLOUTS
         int (*pcre_callout)(pcre_callout_block *);
-Line 1392 
 PCRE CALLOUTS
+Line 2080 
 PCRE CALLOUTS
         default value is zero.  For  example,  this  pattern  has  two  callout
         points:
-          (?C1)abc(?C2)def
+          (?C1)eabc(?C2)def
-        During matching, when PCRE reaches a callout point (and pcre_callout is
+        If  the  PCRE_AUTO_CALLOUT  option  bit  is  set when pcre_compile() is
-        set), the external function is called. Its only argument is  a  pointer
+        called, PCRE automatically  inserts  callouts,  all  with  number  255,
-        to a pcre_callout block. This contains the following variables:
+        before  each  item in the pattern. For example, if PCRE_AUTO_CALLOUT is
+        used with the pattern
+          A(\d{2}|--)
+        it is processed as if it were
+        (?C255)A(?C255)((?C255)\d{2}(?C255)|(?C255)-(?C255)-(?C255))(?C255)
+        Notice that there is a callout before and after  each  parenthesis  and
+        alternation  bar.  Automatic  callouts  can  be  used  for tracking the
+        progress of pattern matching. The pcretest command has an  option  that
+        sets  automatic callouts; when it is used, the output indicates how the
+        pattern is matched. This is useful information when you are  trying  to
+        optimize the performance of a particular pattern.
+ MISSING CALLOUTS
+        You  should  be  aware  that,  because of optimizations in the way PCRE
+        matches patterns, callouts sometimes do not happen. For example, if the
+        pattern is
+          ab(?C4)cd
+        PCRE knows that any matching string must contain the letter "d". If the
+        subject string is "abyz", the lack of "d" means that  matching  doesn't
+        ever  start,  and  the  callout is never reached. However, with "abyd",
+        though the result is still no match, the callout is obeyed.
+ THE CALLOUT INTERFACE
+        During matching, when PCRE reaches a callout point, the external  func-
+        tion  defined by pcre_callout is called (if it is set). This applies to
+        both the pcre_exec() and the pcre_dfa_exec()  matching  functions.  The
+        only  argument  to  the callout function is a pointer to a pcre_callout
+        block. This structure contains the following fields:
           int          version;
           int          callout_number;
-Line 1408 
 PCRE CALLOUTS
+Line 2133 
 PCRE CALLOUTS
           int          capture_top;
           int          capture_last;
           void        *callout_data;
+          int          pattern_position;
+          int          next_item_length;
-        The  version  field  is an integer containing the version number of the
+        The version field is an integer containing the version  number  of  the
-        block format. The current version  is  zero.  The  version  number  may
+        block  format. The initial version was 0; the current version is 1. The
-        change  in  future if additional fields are added, but the intention is
+        version number will change again in future  if  additional  fields  are
-        never to remove any of the existing fields.
+        added, but the intention is never to remove any of the existing fields.
         The callout_number field contains the number of the  callout,  as  com-
-        piled into the pattern (that is, the number after ?C).
+        piled  into  the pattern (that is, the number after ?C for manual call-
+        outs, and 255 for automatically generated callouts).
-        The  offset_vector field is a pointer to the vector of offsets that was
+        The offset_vector field is a pointer to the vector of offsets that  was
-        passed by the caller to pcre_exec(). The contents can be  inspected  in
+        passed   by   the   caller  to  pcre_exec()  or  pcre_dfa_exec().  When
-        order  to extract substrings that have been matched so far, in the same
+        pcre_exec() is used, the contents can be inspected in order to  extract
-        way as for extracting substrings after a match has completed.
+        substrings  that  have  been  matched  so  far,  in the same way as for
+        extracting substrings after a match has completed. For  pcre_dfa_exec()
+        this field is not useful.
-        The subject and subject_length fields contain copies  the  values  that
+        The subject and subject_length fields contain copies of the values that
         were passed to pcre_exec().
-        The  start_match  field contains the offset within the subject at which
+        The start_match field contains the offset within the subject  at  which
-        the current match attempt started. If the pattern is not anchored,  the
+        the  current match attempt started. If the pattern is not anchored, the
-        callout  function  may  be  called several times for different starting
+        callout function may be called several times from the same point in the
-        points.
+        pattern for different starting points in the subject.
-        The current_position field contains the offset within  the  subject  of
+        The  current_position  field  contains the offset within the subject of
         the current match pointer.
-        The  capture_top field contains one more than the number of the highest
+        When the pcre_exec() function is used, the capture_top  field  contains
-        numbered  captured  substring  so  far.  If  no  substrings  have  been
+        one  more than the number of the highest numbered captured substring so
-        captured, the value of capture_top is one.
+        far. If no substrings have been captured, the value of  capture_top  is
+        one.  This  is always the case when pcre_dfa_exec() is used, because it
-        The  capture_last  field  contains the number of the most recently cap-
+        does not support captured substrings.
-        tured substring.
+        The capture_last field contains the number of the  most  recently  cap-
+        tured  substring. If no substrings have been captured, its value is -1.
+        This is always the case when pcre_dfa_exec() is used.
         The callout_data field contains a value that is passed  to  pcre_exec()
-        by  the  caller specifically so that it can be passed back in callouts.
+        or  pcre_dfa_exec() specifically so that it can be passed back in call-
-        It is passed in the pcre_callout field of the  pcre_extra  data  struc-
+        outs. It is passed in the pcre_callout field  of  the  pcre_extra  data
-        ture.  If  no  such  data  was  passed,  the value of callout_data in a
+        structure.  If  no such data was passed, the value of callout_data in a
         pcre_callout block is NULL. There is a description  of  the  pcre_extra
         structure in the pcreapi documentation.
+        The  pattern_position field is present from version 1 of the pcre_call-
+        out structure. It contains the offset to the next item to be matched in
+        the pattern string.
+        The  next_item_length field is present from version 1 of the pcre_call-
+        out structure. It contains the length of the next item to be matched in
+        the  pattern  string. When the callout immediately precedes an alterna-
+        tion bar, a closing parenthesis, or the end of the pattern, the  length
+        is  zero.  When the callout precedes an opening parenthesis, the length
+        is that of the entire subpattern.
+        The pattern_position and next_item_length fields are intended  to  help
+        in  distinguishing between different automatic callouts, which all have
+        the same callout number. However, they are set for all callouts.
  RETURN VALUES
-        The callout function returns an integer. If the value is zero, matching
+        The external callout function returns an integer to PCRE. If the  value
-        proceeds as normal. If the value is greater than zero,  matching  fails
+        is  zero,  matching  proceeds  as  normal. If the value is greater than
-        at the current point, but backtracking to test other possibilities goes
+        zero, matching fails at the current point, but  the  testing  of  other
-        ahead, just as if a lookahead assertion had failed.  If  the  value  is
+        matching possibilities goes ahead, just as if a lookahead assertion had
-        less  than  zero,  the  match is abandoned, and pcre_exec() returns the
+        failed. If the value is less than zero, the  match  is  abandoned,  and
-        value.
+        pcre_exec() (or pcre_dfa_exec()) returns the negative value.
-        Negative  values  should  normally  be   chosen   from   the   set   of
+        Negative   values   should   normally   be   chosen  from  the  set  of
         PCRE_ERROR_xxx values. In particular, PCRE_ERROR_NOMATCH forces a stan-
-        dard "no  match"  failure.   The  error  number  PCRE_ERROR_CALLOUT  is
+        dard  "no  match"  failure.   The  error  number  PCRE_ERROR_CALLOUT is
-        reserved  for  use  by callout functions; it will never be used by PCRE
+        reserved for use by callout functions; it will never be  used  by  PCRE
         itself.
- Last updated: 21 January 2003
+ Last updated: 28 February 2005
- Copyright (c) 1997-2003 University of Cambridge.
+ Copyright (c) 1997-2005 University of Cambridge.
- -----------------------------------------------------------------------------
+ ------------------------------------------------------------------------------
- PCRE(3)                                                                PCRE(3)
+ PCRECOMPAT(3)                                                    PCRECOMPAT(3)
  NAME
         PCRE - Perl-compatible regular expressions
- DIFFERENCES FROM PERL
+ DIFFERENCES BETWEEN PCRE AND PERL
         This  document describes the differences in the ways that PCRE and Perl
         handle regular expressions. The differences  described  here  are  with
-Line 1498 
 DIFFERENCES FROM PERL
+Line 2246 
 DIFFERENCES FROM PERL
 . Though binary zero characters are supported in the  subject  string,
         they are not allowed in a pattern string because it is passed as a nor-
-        mal C string, terminated by zero. The escape sequence "\0" can be  used
+        mal C string, terminated by zero. The escape sequence \0 can be used in
-        in the pattern to represent a binary zero.
+        the pattern to represent a binary zero.
 .  The  following Perl escape sequences are not supported: \l, \u, \L,
-        \U, \P, \p, \N, and \X. In fact these are implemented by Perl's general
+        \U, and \N. In fact these are implemented by Perl's general string-han-
-        string-handling and are not part of its pattern matching engine. If any
+        dling  and are not part of its pattern matching engine. If any of these
-        of these are encountered by PCRE, an error is generated.
+        are encountered by PCRE, an error is generated.
-. PCRE does support the \Q...\E escape for quoting substrings. Charac-
+. The Perl escape sequences \p, \P, and \X are supported only if  PCRE
-        ters  in  between  are  treated as literals. This is slightly different
+        is  built  with Unicode character property support. The properties that
-        from Perl in that $ and @ are  also  handled  as  literals  inside  the
+        can be tested with \p and \P are limited to the general category  prop-
-        quotes.  In Perl, they cause variable interpolation (but of course PCRE
+        erties such as Lu and Nd.
+. PCRE does support the \Q...\E escape for quoting substrings. Charac-
+        ters in between are treated as literals.  This  is  slightly  different
+        from  Perl  in  that  $  and  @ are also handled as literals inside the
+        quotes. In Perl, they cause variable interpolation (but of course  PCRE
         does not have variables). Note the following examples:
             Pattern            PCRE matches      Perl matches
-Line 1519 
 DIFFERENCES FROM PERL
+Line 2272 
 DIFFERENCES FROM PERL
             \Qabc\$xyz\E       abc\$xyz          abc\$xyz
             \Qabc\E\$\Qxyz\E   abc$xyz           abc$xyz
-        The \Q...\E sequence is recognized both inside  and  outside  character
+        The  \Q...\E  sequence  is recognized both inside and outside character
         classes.
 . Fairly obviously, PCRE does not support the (?{code}) and (?p{code})
-        constructions. However, there is some experimental support  for  recur-
+        constructions.  However,  there is support for recursive patterns using
-        sive  patterns  using the non-Perl items (?R), (?number) and (?P>name).
+        the non-Perl items (?R),  (?number),  and  (?P>name).  Also,  the  PCRE
-        Also, the PCRE "callout" feature allows  an  external  function  to  be
+        "callout"  feature allows an external function to be called during pat-
-        called during pattern matching.
+        tern matching. See the pcrecallout documentation for details.
-.  There  are some differences that are concerned with the settings of
+. 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,
-        matching  "aba"  against  the  pattern  /^(a(b)?)+$/  in Perl leaves $2
+        matching "aba" against the  pattern  /^(a(b)?)+$/  in  Perl  leaves  $2
         unset, but in PCRE it is set to "b".
-. PCRE  provides  some  extensions  to  the  Perl  regular  expression
+. PCRE provides some extensions to the Perl regular expression facil-
-        facilities:
+        ities:
-        (a)  Although  lookbehind  assertions  must match fixed length strings,
+        (a) Although lookbehind assertions must  match  fixed  length  strings,
         each alternative branch of a lookbehind assertion can match a different
         length of string. Perl requires them all to have the same length.
-        (b)  If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $
+        (b) If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the  $
         meta-character matches only at the very end of the string.
         (c) If PCRE_EXTRA is set, a backslash followed by a letter with no spe-
         cial meaning is faulted.
-        (d)  If  PCRE_UNGREEDY is set, the greediness of the repetition quanti-
+        (d) If PCRE_UNGREEDY is set, the greediness of the  repetition  quanti-
         fiers is inverted, that is, by default they are not greedy, but if fol-
         lowed by a question mark they are.
-        (e)  PCRE_ANCHORED  can  be used to force a pattern to be tried only at
+        (e) PCRE_ANCHORED can be used at matching time to force a pattern to be
-        the first matching position in the subject string.
+        tried only at the first matching position in the subject string.
-        (f) The PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and  PCRE_NO_AUTO_CAP-
+        (f)  The PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and PCRE_NO_AUTO_CAP-
         TURE options for pcre_exec() have no Perl equivalents.
-        (g)  The (?R), (?number), and (?P>name) constructs allows for recursive
+        (g) The (?R), (?number), and (?P>name) constructs allows for  recursive
-        pattern matching (Perl can do  this  using  the  (?p{code})  construct,
+        pattern  matching  (Perl  can  do  this using the (?p{code}) construct,
         which PCRE cannot support.)
-        (h)  PCRE supports named capturing substrings, using the Python syntax.
+        (h) PCRE supports named capturing substrings, using the Python  syntax.
-        (i) PCRE supports the possessive quantifier  "++"  syntax,  taken  from
+        (i)  PCRE  supports  the  possessive quantifier "++" syntax, taken from
         Sun's Java package.
         (j) The (R) condition, for testing recursion, is a PCRE extension.
         (k) The callout facility is PCRE-specific.
- Last updated: 09 December 2003
+        (l) The partial matching facility is PCRE-specific.
- Copyright (c) 1997-2003 University of Cambridge.
- -----------------------------------------------------------------------------
- PCRE(3)                                                                PCRE(3)
+        (m) Patterns compiled by PCRE can be saved and re-used at a later time,
+        even on different hosts that have the other endianness.
+        (n)  The  alternative  matching function (pcre_dfa_exec()) matches in a
+        different way and is not Perl-compatible.
+ Last updated: 28 February 2005
+ Copyright (c) 1997-2005 University of Cambridge.
+ ------------------------------------------------------------------------------
+ PCREPATTERN(3)                                                  PCREPATTERN(3)
  NAME
         PCRE - Perl-compatible regular expressions
  PCRE REGULAR EXPRESSION DETAILS
         The  syntax  and semantics of the regular expressions supported by PCRE
         are described below. Regular expressions are also described in the Perl
-        documentation  and in a number of other books, some of which have copi-
+        documentation  and  in  a  number  of books, some of which have copious
-        ous examples. Jeffrey Friedl's "Mastering  Regular  Expressions",  pub-
+        examples.  Jeffrey Friedl's "Mastering Regular Expressions",  published
-        lished  by  O'Reilly, covers them in great detail. The description here
+        by  O'Reilly, covers regular expressions in great detail. This descrip-
-        is intended as reference documentation.
+        tion of PCRE's regular expressions is intended as reference material.
-        The basic operation of PCRE is on strings of bytes. However,  there  is
+        The original operation of PCRE was on strings of  one-byte  characters.
-        also  support for UTF-8 character strings. To use this support you must
+        However,  there is now also support for UTF-8 character strings. To use
-        build PCRE to include UTF-8 support, and then call pcre_compile()  with
+        this, you must build PCRE to  include  UTF-8  support,  and  then  call
-        the  PCRE_UTF8  option.  How  this affects the pattern matching is men-
+        pcre_compile()  with  the  PCRE_UTF8  option.  How this affects pattern
-        tioned in several places below. There is also a summary of  UTF-8  fea-
+        matching is mentioned in several places below. There is also a  summary
-        tures in the section on UTF-8 support in the main pcre page.
+        of  UTF-8  features  in  the  section on UTF-8 support in the main pcre
+        page.
-        A  regular  expression  is  a pattern that is matched against a subject
-        string from left to right. Most characters stand for  themselves  in  a
+        The remainder of this document discusses the  patterns  that  are  sup-
-        pattern,  and  match  the corresponding characters in the subject. As a
+        ported  by  PCRE when its main matching function, pcre_exec(), is used.
+        From  release  6.0,   PCRE   offers   a   second   matching   function,
+        pcre_dfa_exec(),  which matches using a different algorithm that is not
+        Perl-compatible. The advantages and disadvantages  of  the  alternative
+        function, and how it differs from the normal function, are discussed in
+        the pcrematching page.
+        A regular expression is a pattern that is  matched  against  a  subject
+        string  from  left  to right. Most characters stand for themselves in a
+        pattern, and match the corresponding characters in the  subject.  As  a
         trivial example, the pattern
           The quick brown fox
-        matches a portion of a subject string that is identical to itself.  The
+        matches a portion of a subject string that is identical to itself. When
-        power of regular expressions comes from the ability to include alterna-
+        caseless matching is specified (the PCRE_CASELESS option), letters  are
-        tives and repetitions in the pattern. These are encoded in the  pattern
+        matched  independently  of case. In UTF-8 mode, PCRE always understands
-        by  the  use  of meta-characters, which do not stand for themselves but
+        the concept of case for characters whose values are less than  128,  so
-        instead are interpreted in some special way.
+        caseless  matching  is always possible. For characters with higher val-
+        ues, the concept of case is supported if PCRE is compiled with  Unicode
+        property  support,  but  not  otherwise.   If  you want to use caseless
+        matching for characters 128 and above, you must  ensure  that  PCRE  is
+        compiled with Unicode property support as well as with UTF-8 support.
+        The  power  of  regular  expressions  comes from the ability to include
+        alternatives and repetitions in the pattern. These are encoded  in  the
+        pattern by the use of metacharacters, which do not stand for themselves
+        but instead are interpreted in some special way.
-        There are two different sets of meta-characters: those that are  recog-
+        There are two different sets of metacharacters: those that  are  recog-
         nized  anywhere in the pattern except within square brackets, and those
         that are recognized in square brackets. Outside  square  brackets,  the
-        meta-characters are as follows:
+        metacharacters are as follows:
           \      general escape character with several uses
           ^      assert start of string (or line, in multiline mode)
-Line 1631 
 PCRE REGULAR EXPRESSION DETAILS
+Line 2411 
 PCRE REGULAR EXPRESSION DETAILS
           {      start min/max quantifier
         Part  of  a  pattern  that is in square brackets is called a "character
-        class". In a character class the only meta-characters are:
+        class". In a character class the only metacharacters are:
           \      general escape character
           ^      negate the class, but only if the first character
-Line 1640 
 PCRE REGULAR EXPRESSION DETAILS
+Line 2420 
 PCRE REGULAR EXPRESSION DETAILS
                    syntax)
           ]      terminates the character class
-        The following sections describe the use of each of the meta-characters.
+        The following sections describe the use of each of the  metacharacters.
  BACKSLASH
         The backslash character has several uses. Firstly, if it is followed by
-        a non-alphameric character, it takes  away  any  special  meaning  that
+        a non-alphanumeric character, it takes away any  special  meaning  that
         character  may  have.  This  use  of  backslash  as an escape character
         applies both inside and outside character classes.
         For example, if you want to match a * character, you write  \*  in  the
         pattern.   This  escaping  action  applies whether or not the following
-        character would otherwise be interpreted as a meta-character, so it  is
+        character would otherwise be interpreted as a metacharacter, so  it  is
-        always  safe to precede a non-alphameric with backslash to specify that
+        always  safe  to  precede  a non-alphanumeric with backslash to specify
-        it stands for itself. In particular, if you want to match a  backslash,
+        that it stands for itself. In particular, if you want to match a  back-
-        you write \\.
+        slash, you write \\.
         If  a  pattern is compiled with the PCRE_EXTENDED option, whitespace in
         the pattern (other than in a character class) and characters between  a
-Line 1679 
 BACKSLASH
+Line 2459 
 BACKSLASH
         The  \Q...\E  sequence  is recognized both inside and outside character
         classes.
+    Non-printing characters
         A second use of backslash provides a way of encoding non-printing char-
         acters  in patterns in a visible manner. There is no restriction on the
         appearance of non-printing characters, apart from the binary zero  that
-Line 1708 
 BACKSLASH
+Line 2490 
 BACKSLASH
         must  be  less  than  2**31  (that is, the maximum hexadecimal value is
 FFFFFFF). If characters other than hexadecimal digits  appear  between
         \x{  and }, or if there is no terminating }, this form of escape is not
-        recognized. Instead, the initial \x will be interpreted as a basic hex-
+        recognized. Instead, the initial \x will  be  interpreted  as  a  basic
-        adecimal escape, with no following digits, giving a byte whose value is
+        hexadecimal  escape, with no following digits, giving a character whose
-        zero.
+        value is zero.
         Characters whose value is less than 256 can be defined by either of the
         two  syntaxes for \x when PCRE is in UTF-8 mode. There is no difference
-Line 1721 
 BACKSLASH
+Line 2503 
 BACKSLASH
         there are fewer than two digits, just those that are present are  used.
         Thus  the sequence \0\x\07 specifies two binary zeros followed by a BEL
         character (code value 7). Make sure you supply  two  digits  after  the
-        initial zero if the character that follows is itself an octal digit.
+        initial  zero  if the pattern character that follows is itself an octal
+        digit.
         The handling of a backslash followed by a digit other than 0 is compli-
         cated.  Outside a character class, PCRE reads it and any following dig-
-        its  as  a  decimal  number. If the number is less than 10, or if there
+        its as a decimal number. If the number is less than  10,  or  if  there
         have been at least that many previous capturing left parentheses in the
-        expression,  the  entire  sequence  is  taken  as  a  back reference. A
+        expression, the entire  sequence  is  taken  as  a  back  reference.  A
-        description of how this works is given later, following the  discussion
+        description  of how this works is given later, following the discussion
         of parenthesized subpatterns.
-        Inside  a  character  class, or if the decimal number is greater than 9
+        Inside a character class, or if the decimal number is  greater  than  9
-        and there have not been that many capturing subpatterns, PCRE  re-reads
+        and  there have not been that many capturing subpatterns, PCRE re-reads
-        up  to three octal digits following the backslash, and generates a sin-
+        up to three octal digits following the backslash, and generates a  sin-
         gle byte from the least significant 8 bits of the value. Any subsequent
         digits stand for themselves.  For example:
-Line 1752 
 BACKSLASH
+Line 2535 
 BACKSLASH
           \81    is either a back reference, or a binary zero
                     followed by the two characters "8" and "1"
-        Note  that  octal  values of 100 or greater must not be introduced by a
+        Note that octal values of 100 or greater must not be  introduced  by  a
         leading zero, because no more than three octal digits are ever read.
-        All the sequences that define a single byte value  or  a  single  UTF-8
+        All  the  sequences  that  define a single byte value or a single UTF-8
         character (in UTF-8 mode) can be used both inside and outside character
-        classes. In addition, inside a character  class,  the  sequence  \b  is
+        classes.  In  addition,  inside  a  character class, the sequence \b is
-        interpreted  as  the  backspace character (hex 08). Outside a character
+        interpreted as the backspace character (hex 08), and the sequence \X is
-        class it has a different meaning (see below).
+        interpreted  as  the  character  "X".  Outside a character class, these
+        sequences have different meanings (see below).
-        The third use of backslash is for specifying generic character types:
+    Generic character types
+        The third use of backslash is for specifying generic  character  types.
+        The following are always recognized:
           \d     any decimal digit
           \D     any character that is not a decimal digit
-Line 1771 
 BACKSLASH
+Line 2558 
 BACKSLASH
           \W     any "non-word" character
         Each pair of escape sequences partitions the complete set of characters
-        into  two disjoint sets. Any given character matches one, and only one,
+        into two disjoint sets. Any given character matches one, and only  one,
         of each pair.
-        In UTF-8 mode, characters with values greater than 255 never match  \d,
-        \s, or \w, and always match \D, \S, and \W.
-        For  compatibility  with Perl, \s does not match the VT character (code
-).  This makes it different from the the POSIX "space" class. The  \s
-        characters are HT (9), LF (10), FF (12), CR (13), and space (32).
-        A  "word" character is any letter or digit or the underscore character,
-        that is, any character which can be part of a Perl "word". The  defini-
-        tion  of  letters  and digits is controlled by PCRE's character tables,
-        and may vary if locale- specific matching is taking place (see  "Locale
-        support"  in  the  pcreapi  page).  For  example,  in the "fr" (French)
-        locale, some character codes greater than 128  are  used  for  accented
-        letters, and these are matched by \w.
         These character type sequences can appear both inside and outside char-
         acter classes. They each match one character of the  appropriate  type.
         If  the current matching point is at the end of the subject string, all
         of them fail, since there is no character to match.
+        For compatibility with Perl, \s does not match the VT  character  (code
+).   This makes it different from the the POSIX "space" class. The \s
+        characters are HT (9), LF (10), FF (12), CR (13), and space (32).
+        A "word" character is an underscore or any character less than 256 that
+        is  a  letter  or  digit.  The definition of letters and digits is con-
+        trolled by PCRE's low-valued character tables, and may vary if  locale-
+        specific  matching is taking place (see "Locale support" in the pcreapi
+        page). For example, in the  "fr_FR"  (French)  locale,  some  character
+        codes  greater  than  128  are used for accented letters, and these are
+        matched by \w.
+        In UTF-8 mode, characters with values greater than 128 never match  \d,
+        \s, or \w, and always match \D, \S, and \W. This is true even when Uni-
+        code character property support is available.
+    Unicode character properties
+        When PCRE is built with Unicode character property support, three addi-
+        tional  escape sequences to match generic character types are available
+        when UTF-8 mode is selected. They are:
+         \p{xx}   a character with the xx property
+         \P{xx}   a character without the xx property
+         \X       an extended Unicode sequence
+        The property names represented by xx above are limited to  the  Unicode
+        general  category properties. Each character has exactly one such prop-
+        erty, specified by a two-letter abbreviation.  For  compatibility  with
+        Perl,  negation  can be specified by including a circumflex between the
+        opening brace and the property name. For example, \p{^Lu} is  the  same
+        as \P{Lu}.
+        If  only  one  letter  is  specified with \p or \P, it includes all the
+        properties that start with that letter. In this case, in the absence of
+        negation, the curly brackets in the escape sequence are optional; these
+        two examples have the same effect:
+          \p{L}
+          \pL
+        The following property codes are supported:
+          C     Other
+          Cc    Control
+          Cf    Format
+          Cn    Unassigned
+          Co    Private use
+          Cs    Surrogate
+          L     Letter
+          Ll    Lower case letter
+          Lm    Modifier letter
+          Lo    Other letter
+          Lt    Title case letter
+          Lu    Upper case letter
+          M     Mark
+          Mc    Spacing mark
+          Me    Enclosing mark
+          Mn    Non-spacing mark
+          N     Number
+          Nd    Decimal number
+          Nl    Letter number
+          No    Other number
+          P     Punctuation
+          Pc    Connector punctuation
+          Pd    Dash punctuation
+          Pe    Close punctuation
+          Pf    Final punctuation
+          Pi    Initial punctuation
+          Po    Other punctuation
+          Ps    Open punctuation
+          S     Symbol
+          Sc    Currency symbol
+          Sk    Modifier symbol
+          Sm    Mathematical symbol
+          So    Other symbol
+          Z     Separator
+          Zl    Line separator
+          Zp    Paragraph separator
+          Zs    Space separator
+        Extended properties such as "Greek" or "InMusicalSymbols" are not  sup-
+        ported by PCRE.
+        Specifying  caseless  matching  does not affect these escape sequences.
+        For example, \p{Lu} always matches only upper case letters.
+        The \X escape matches any number of Unicode  characters  that  form  an
+        extended Unicode sequence. \X is equivalent to
+          (?>\PM\pM*)
+        That  is,  it matches a character without the "mark" property, followed
+        by zero or more characters with the "mark"  property,  and  treats  the
+        sequence  as  an  atomic group (see below).  Characters with the "mark"
+        property are typically accents that affect the preceding character.
+        Matching characters by Unicode property is not fast, because  PCRE  has
+        to  search  a  structure  that  contains data for over fifteen thousand
+        characters. That is why the traditional escape sequences such as \d and
+        \w do not use Unicode properties in PCRE.
+    Simple assertions
         The fourth use of backslash is for certain simple assertions. An asser-
-        tion  specifies a condition that has to be met at a particular point in
+        tion specifies a condition that has to be met at a particular point  in
-        a match, without consuming any characters from the subject string.  The
+        a  match, without consuming any characters from the subject string. The
-        use  of subpatterns for more complicated assertions is described below.
+        use of subpatterns for more complicated assertions is described  below.
-        The backslashed assertions are
+        The backslashed assertions are:
           \b     matches at a word boundary
           \B     matches when not at a word boundary
-Line 1807 
 BACKSLASH
+Line 2689 
 BACKSLASH
           \z     matches at end of subject
           \G     matches at first matching position in subject
-        These assertions may not appear in character classes (but note that  \b
+        These  assertions may not appear in character classes (but note that \b
         has a different meaning, namely the backspace character, inside a char-
         acter class).
-        A word boundary is a position in the subject string where  the  current
+        A  word  boundary is a position in the subject string where the current
-        character  and  the previous character do not both match \w or \W (i.e.
+        character and the previous character do not both match \w or  \W  (i.e.
-        one matches \w and the other matches \W), or the start or  end  of  the
+        one  matches  \w  and the other matches \W), or the start or end of the
         string if the first or last character matches \w, respectively.
-        The  \A,  \Z,  and \z assertions differ from the traditional circumflex
+        The \A, \Z, and \z assertions differ from  the  traditional  circumflex
-        and dollar (described below) in that they only ever match at  the  very
+        and dollar (described in the next section) in that they only ever match
-        start  and  end  of the subject string, whatever options are set. Thus,
+        at the very start and end of the subject string, whatever  options  are
-        they are independent of multiline mode.
+        set.  Thus,  they are independent of multiline mode. These three asser-
+        tions are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options, which
-        They are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options. If the
+        affect  only the behaviour of the circumflex and dollar metacharacters.
-        startoffset argument of pcre_exec() is non-zero, indicating that match-
+        However, if the startoffset argument of pcre_exec() is non-zero,  indi-
-        ing is to start at a point other than the beginning of the subject,  \A
+        cating that matching is to start at a point other than the beginning of
-        can  never  match.  The difference between \Z and \z is that \Z matches
+        the subject, \A can never match. The difference between \Z  and  \z  is
-        before a newline that is the last character of the string as well as at
+        that  \Z  matches  before  a  newline that is the last character of the
-        the end of the string, whereas \z matches only at the end.
+        string as well as at the end of the string, whereas \z matches only  at
+        the end.
         The  \G assertion is true only when the current matching position is at
         the start point of the match, as specified by the startoffset  argument
-Line 1849 
 BACKSLASH
+Line 2732 
 BACKSLASH
  CIRCUMFLEX AND DOLLAR
         Outside a character class, in the default matching mode, the circumflex
-        character  is  an  assertion which is true only if the current matching
+        character  is  an  assertion  that is true only if the current matching
         point is at the start of the subject string. If the  startoffset  argu-
         ment  of  pcre_exec()  is  non-zero,  circumflex can never match if the
         PCRE_MULTILINE option is unset. Inside a  character  class,  circumflex
-Line 1863 
 CIRCUMFLEX AND DOLLAR
+Line 2746 
 CIRCUMFLEX AND DOLLAR
         ject, it is said to be an "anchored" pattern.  (There  are  also  other
         constructs that can cause a pattern to be anchored.)
-        A  dollar  character  is an assertion which is true only if the current
+        A  dollar  character  is  an assertion that is true only if the current
         matching point is at the end of  the  subject  string,  or  immediately
         before a newline character that is the last character in the string (by
         default). Dollar need not be the last character of  the  pattern  if  a
-Line 1880 
 CIRCUMFLEX AND DOLLAR
+Line 2763 
 CIRCUMFLEX AND DOLLAR
         ately  after  and  immediately  before  an  internal newline character,
         respectively, in addition to matching at the start and end of the  sub-
         ject  string.  For  example,  the  pattern  /^abc$/ matches the subject
-        string "def\nabc" in multiline mode, but not  otherwise.  Consequently,
+        string "def\nabc" (where \n represents a newline character)  in  multi-
-        patterns  that  are  anchored  in single line mode because all branches
+        line mode, but not otherwise.  Consequently, patterns that are anchored
-        start with ^ are not anchored in multiline mode, and a match  for  cir-
+        in single line mode because all branches start with ^ are not  anchored
-        cumflex  is  possible  when  the startoffset argument of pcre_exec() is
+        in  multiline  mode,  and  a  match for circumflex is possible when the
-        non-zero. The PCRE_DOLLAR_ENDONLY option is ignored  if  PCRE_MULTILINE
+        startoffset  argument  of  pcre_exec()  is  non-zero.   The   PCRE_DOL-
-        is set.
+        LAR_ENDONLY option is ignored if PCRE_MULTILINE is set.
         Note  that  the sequences \A, \Z, and \z can be used to match the start
         and end of the subject in both modes, and if all branches of a  pattern
-Line 1898 
 FULL STOP (PERIOD, DOT)
+Line 2781 
 FULL STOP (PERIOD, DOT)
         Outside a character class, a dot in the pattern matches any one charac-
         ter  in  the  subject,  including a non-printing character, but not (by
         default) newline.  In UTF-8 mode, a dot matches  any  UTF-8  character,
-        which  might  be  more than one byte long, except (by default) for new-
+        which might be more than one byte long, except (by default) newline. If
-        line. If the PCRE_DOTALL option is set, dots match  newlines  as  well.
+        the PCRE_DOTALL option is set, dots match newlines as  well.  The  han-
-        The  handling of dot is entirely independent of the handling of circum-
+        dling  of dot is entirely independent of the handling of circumflex and
-        flex and dollar, the only relationship being  that  they  both  involve
+        dollar, the only relationship being  that  they  both  involve  newline
-        newline characters. Dot has no special meaning in a character class.
+        characters. Dot has no special meaning in a character class.
  MATCHING A SINGLE BYTE
         Outside a character class, the escape sequence \C matches any one byte,
-        both in and out of UTF-8 mode. Unlike a dot, it always matches  a  new-
+        both in and out of UTF-8 mode. Unlike a dot, it can  match  a  newline.
-        line.  The  feature  is  provided  in Perl in order to match individual
+        The  feature  is provided in Perl in order to match individual bytes in
-        bytes in UTF-8 mode.  Because it breaks up UTF-8 characters into  indi-
+        UTF-8 mode. Because it  breaks  up  UTF-8  characters  into  individual
-        vidual  bytes,  what  remains  in  the  string may be a malformed UTF-8
+        bytes,  what remains in the string may be a malformed UTF-8 string. For
-        string. For this reason it is best avoided.
+        this reason, the \C escape sequence is best avoided.
-        PCRE does not allow \C to appear in lookbehind assertions (see  below),
+        PCRE does not allow \C to appear in  lookbehind  assertions  (described
-        because in UTF-8 mode it makes it impossible to calculate the length of
+        below),  because  in UTF-8 mode this would make it impossible to calcu-
-        the lookbehind.
+        late the length of the lookbehind.
- SQUARE BRACKETS
+ SQUARE BRACKETS AND CHARACTER CLASSES
         An opening square bracket introduces a character class, terminated by a
         closing square bracket. A closing square bracket on its own is not spe-
-Line 1938 
 SQUARE BRACKETS
+Line 2821 
 SQUARE BRACKETS
         For example, the character class [aeiou] matches any 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
-        characters which are in the class by enumerating those that are not. It
+        characters  that  are in the class by enumerating those that are not. A
-        is not an assertion: it still consumes a  character  from  the  subject
+        class that starts with a circumflex is not an assertion: it still  con-
-        string, and fails if the current pointer is at the end of the string.
+        sumes  a  character  from the subject string, and therefore it fails if
+        the current pointer is at the end of the string.
-        In  UTF-8 mode, characters with values greater than 255 can be included
+        In UTF-8 mode, characters with values greater than 255 can be  included
-        in a class as a literal string of bytes, or by using the  \x{  escaping
+        in  a  class as a literal string of bytes, 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. PCRE does not  support  the
+        match  "A", whereas a caseful version would. In UTF-8 mode, PCRE always
-        concept of case for characters with values greater than 255.
+        understands the concept of case for characters whose  values  are  less
+        than  128, so caseless matching is always possible. For characters with
+        higher values, the concept of case is supported  if  PCRE  is  compiled
+        with  Unicode  property support, but not otherwise.  If you want to use
+        caseless matching for characters 128 and above, you  must  ensure  that
+        PCRE  is  compiled  with Unicode property support as well as with UTF-8
+        support.
-        The  newline character is never treated in any special way in character
+        The newline character is never treated in any special way in  character
-        classes, whatever the setting  of  the  PCRE_DOTALL  or  PCRE_MULTILINE
+        classes,  whatever  the  setting  of  the PCRE_DOTALL or PCRE_MULTILINE
         options is. A class such as [^a] will always match a newline.
-        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.
         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  single class containing a range followed by two separate
+        preted as a class containing a range followed by two other  characters.
-        characters. The octal or hexadecimal representation of "]" can also  be
+        The  octal or hexadecimal representation of "]" can also be used to end
-        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].  In UTF-8 mode, ranges can include characters whose values
+        [\000-\037]. In UTF-8 mode, ranges can include characters whose  values
         are greater than 255, for example [\x{100}-\x{2ff}].
         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
-        to [][\^_`wxyzabc], matched caselessly, and if character tables for the
+        to  [][\\^_`wxyzabc],  matched  caselessly,  and  in non-UTF-8 mode, if
-        "fr"  locale  are  in use, [\xc8-\xcb] matches accented E characters in
+        character tables for the "fr_FR" locale are in use, [\xc8-\xcb] matches
-        both cases.
+        accented  E  characters in both cases. In UTF-8 mode, PCRE supports the
+        concept of case for characters with values greater than 128  only  when
-        The character types \d, \D, \s, \S, \w, and \W may  also  appear  in  a
+        it is compiled with Unicode property support.
-        character  class,  and add the characters that they match to the class.
-        For example, [\dABCDEF] matches any hexadecimal digit. A circumflex can
+        The  character types \d, \D, \p, \P, \s, \S, \w, and \W may also appear
-        conveniently  be  used with the upper case character types to specify a
+        in a character class, and add the characters that  they  match  to  the
-        more restricted set of characters than the matching  lower  case  type.
+        class. For example, [\dABCDEF] matches any hexadecimal digit. A circum-
-        For  example,  the  class  [^\W_]  matches any letter or digit, but not
+        flex can conveniently be used with the upper case  character  types  to
-        underscore.
+        specify  a  more  restricted  set of characters than the matching lower
+        case type. For example, the class [^\W_] matches any letter  or  digit,
-        All non-alphameric characters other than \, -, ^ (at the start) and the
+        but not underscore.
-        terminating ] are non-special in character classes, but it does no harm
-        if they are escaped.
+        The  only  metacharacters  that are recognized in character classes are
+        backslash, hyphen (only where it can be  interpreted  as  specifying  a
+        range),  circumflex  (only  at the start), opening square bracket (only
+        when it can be interpreted as introducing a POSIX class name - see  the
+        next  section),  and  the  terminating closing square bracket. However,
+        escaping other non-alphanumeric characters does no harm.
  POSIX CHARACTER CLASSES
-        Perl supports the POSIX notation  for  character  classes,  which  uses
+        Perl supports the POSIX notation for character classes. This uses names
-        names  enclosed by [: and :] within the enclosing square brackets. PCRE
+        enclosed  by  [: and :] within the enclosing square brackets. PCRE also
-        also supports this notation. For example,
+        supports this notation. For example,
           [01[:alpha:]%]
-Line 2037 
 POSIX CHARACTER CLASSES
+Line 2932 
 POSIX CHARACTER CLASSES
         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.
-        In UTF-8 mode, characters with values greater than 255 do not match any
+        In UTF-8 mode, characters with values greater than 128 do not match any
         of the POSIX character classes.
-Line 2104 
 INTERNAL OPTION SETTING
+Line 2999 
 INTERNAL OPTION SETTING
         in the same way as the Perl-compatible options by using the  characters
         U  and X respectively. The (?X) flag setting is special in that it must
         always occur earlier in the pattern than any of the additional features
-        it turns on, even when it is at top level. It is best put at the start.
+        it  turns on, even when it is at top level. It is best to put it at the
+        start.
  SUBPATTERNS
         Subpatterns are delimited by parentheses (round brackets), which can be
-        nested.  Marking part of a pattern as a subpattern does two things:
+        nested.  Turning part of a pattern into a subpattern does two things:
 . It localizes a set of alternatives. For example, the pattern
-Line 2120 
 SUBPATTERNS
+Line 3016 
 SUBPATTERNS
         the parentheses, it would match "cataract",  "erpillar"  or  the  empty
         string.
-.  It  sets  up  the  subpattern as a capturing subpattern (as defined
+.  It  sets  up  the  subpattern as a capturing subpattern. This means
-        above).  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
         ovector argument of pcre_exec(). Opening parentheses are  counted  from
-        left  to right (starting from 1) to obtain the numbers of the capturing
+        left  to  right  (starting  from 1) to obtain numbers for the capturing
         subpatterns.
         For example, if the string "the red king" is matched against  the  pat-
-Line 2169 
 NAMED SUBPATTERNS
+Line 3065 
 NAMED SUBPATTERNS
         Identifying  capturing  parentheses  by number is simple, but it can be
         very hard to keep track of the numbers in complicated  regular  expres-
         sions.  Furthermore,  if  an  expression  is  modified, the numbers may
-        change. To help with the difficulty, PCRE supports the naming  of  sub-
+        change. To help with this difficulty, PCRE supports the naming of  sub-
         patterns,  something  that  Perl  does  not  provide. The Python syntax
         (?P<name>...) is used. Names consist  of  alphanumeric  characters  and
         underscores, and must be unique within a pattern.
         Named  capturing  parentheses  are  still  allocated numbers as well as
         names. The PCRE API provides function calls for extracting the name-to-
-        number  translation  table from a compiled pattern. For further details
+        number  translation table from a compiled pattern. There is also a con-
-        see the pcreapi documentation.
+        venience function for extracting a captured substring by name. For fur-
+        ther details see the pcreapi documentation.
  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:
           a literal data character
           the . metacharacter
           the \C escape sequence
-          escapes such as \d that match single characters
+          the \X escape sequence (in UTF-8 mode with Unicode properties)
+          an escape such as \d that matches a single character
           a character class
           a back reference (see next section)
           a parenthesized subpattern (unless it is an assertion)
-        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:
           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
           [aeiou]{3,}
-Line 2212 
 REPETITION
+Line 3110 
 REPETITION
           \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.
-        In UTF-8 mode, quantifiers apply to UTF-8  characters  rather  than  to
+        In  UTF-8  mode,  quantifiers  apply to UTF-8 characters rather than to
         individual bytes. Thus, for example, \x{100}{2} matches two UTF-8 char-
-        acters, each of which is represented by a two-byte sequence.
+        acters, each of which is represented by a two-byte sequence. Similarly,
+        when Unicode property support is available, \X{3} matches three Unicode
+        extended  sequences,  each of which may be several bytes long (and they
+        may be of different lengths).
         The quantifier {0} is permitted, causing the expression to behave as if
         the previous item and the quantifier were not present.
-Line 2247 
 REPETITION
+Line 3148 
 REPETITION
         as  possible  (up  to  the  maximum number of permitted times), without
         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
-        appear between the sequences /* and */ and within the  sequence,  indi-
+        appear between /* and */ and within the comment,  individual  *  and  /
-        vidual * and / characters may appear. An attempt to match C comments by
+        characters  may  appear. An attempt to match C comments by applying the
-        applying the pattern
+        pattern
           /\*.*\*/
         to the string
-          /* first command */  not comment  /* second comment */
+          /* first comment */  not comment  /* second comment */
         fails, because it matches the entire string owing to the greediness  of
         the .*  item.
-Line 2283 
 REPETITION
+Line 3184 
 REPETITION
         words, it inverts the default behaviour.
         When  a  parenthesized  subpattern  is quantified with a minimum repeat
-        count that is greater than 1 or with a limited maximum, more  store  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
         minimum or maximum.
-Line 2374 
 ATOMIC GROUPING AND POSSESSIVE QUANTIFIE
+Line 3275 
 ATOMIC GROUPING AND POSSESSIVE QUANTIFIE
         consists  of  an  additional  + character following a quantifier. Using
         this notation, the previous example can be rewritten as
-          \d++bar
+          \d++foo
         Possessive  quantifiers  are  always  greedy;  the   setting   of   the
         PCRE_UNGREEDY option is ignored. They are a convenient notation for the
-Line 2399 
 ATOMIC GROUPING AND POSSESSIVE QUANTIFIE
+Line 3300 
 ATOMIC GROUPING AND POSSESSIVE QUANTIFIE
           aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
         it takes a long time before reporting  failure.  This  is  because  the
-        string  can  be  divided  between  the two repeats in a large number of
+        string  can be divided between the internal \D+ repeat and the external
-        ways, and all have to be tried. (The example used [!?]  rather  than  a
+        * repeat in a large number of ways, and all  have  to  be  tried.  (The
-        single  character  at the end, because both PCRE and Perl have an opti-
+        example  uses  [!?]  rather than a single character at the end, because
-        mization that allows for fast failure when a single character is  used.
+        both PCRE and Perl have an optimization that allows  for  fast  failure
-        They  remember  the last single character that is required for a match,
+        when  a single character is used. They remember the last single charac-
-        and fail early if it is not present in the string.)  If the pattern  is
+        ter that is required for a match, and fail early if it is  not  present
-        changed to
+        in  the  string.)  If  the pattern is changed so that it uses an atomic
+        group, like this:
           ((?>\D+)|<\d+>)*[!?]
-        sequences  of non-digits cannot be broken, and failure happens quickly.
+        sequences of non-digits cannot be broken, and failure happens  quickly.
  BACK REFERENCES
         Outside a character class, a backslash followed by a digit greater than
 (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.
         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. See the section
+        to the left of the reference for numbers less than 10. See the  subsec-
-        entitled "Backslash" above for further details of the handling of  dig-
+        tion  entitled  "Non-printing  characters" above for further details of
-        its following a backslash.
+        the handling of digits following a backslash.
-        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
         of doing that). So the pattern
           (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,
           ((?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.
-        Back references to named subpatterns use the Python  syntax  (?P=name).
+        Back  references  to named subpatterns use the Python syntax (?P=name).
         We could rewrite the above example as follows:
           (?<p1>(?i)rah)\s+(?P=p1)
-        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. For example, the pattern
           (a|(bc))\2
-        always  fails if it starts to match "a" rather than "bc". Because there
+        always fails if it starts to match "a" rather than "bc". Because  there
-        may be many capturing parentheses in a pattern,  all  digits  following
+        may  be  many  capturing parentheses in a pattern, all digits following
-        the  backslash  are taken as part of a potential back reference number.
+        the backslash are taken as part of a potential back  reference  number.
         If the pattern continues with a digit character, some delimiter must be
-        used  to  terminate  the back reference. If the PCRE_EXTENDED option is
+        used to terminate the back reference. If the  PCRE_EXTENDED  option  is
-        set, this can be whitespace.  Otherwise an empty comment can be used.
+        set,  this  can  be  whitespace.  Otherwise an empty comment (see "Com-
+        ments" below) can be used.
         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
-Line 2482 
 ASSERTIONS
+Line 3385 
 ASSERTIONS
         An assertion is a test on the characters  following  or  preceding  the
         current  matching  point that does not actually consume any characters.
         The simple assertions coded as \b, \B, \A, \G, \Z,  \z,  ^  and  $  are
-        described above.  More complicated assertions are coded as subpatterns.
+        described above.
-        There are two kinds: those that look ahead of the current  position  in
-        the subject string, and those that look behind it.
+        More  complicated  assertions  are  coded as subpatterns. There are two
+        kinds: those that look ahead of the current  position  in  the  subject
-        An  assertion  subpattern  is matched in the normal way, except that it
+        string,  and  those  that  look  behind  it. An assertion subpattern is
-        does not cause the current matching position to be  changed.  Lookahead
+        matched in the normal way, except that it does not  cause  the  current
-        assertions  start with (?= for positive assertions and (?! for negative
+        matching position to be changed.
-        assertions. For example,
+        Assertion  subpatterns  are  not  capturing subpatterns, and may not be
+        repeated, because it makes no sense to assert the  same  thing  several
+        times.  If  any kind of assertion contains capturing subpatterns within
+        it, these are counted for the purposes of numbering the capturing  sub-
+        patterns in the whole pattern.  However, substring capturing is carried
+        out only for positive assertions, because it does not  make  sense  for
+        negative assertions.
+    Lookahead assertions
+        Lookahead assertions start with (?= for positive assertions and (?! for
+        negative assertions. For example,
           \w+(?=;)
-Line 2506 
 ASSERTIONS
+Line 3421 
 ASSERTIONS
         does not find an occurrence of "bar"  that  is  preceded  by  something
         other  than "foo"; it finds any occurrence of "bar" whatsoever, because
         the assertion (?!foo) is always true when the next three characters are
-        "bar". A lookbehind assertion is needed to achieve this 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
         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
         string must always fail.
+    Lookbehind assertions
         Lookbehind assertions start with (?<= for positive assertions and  (?<!
         for negative assertions. For example,
-Line 2551 
 ASSERTIONS
+Line 3468 
 ASSERTIONS
         PCRE does not allow the \C escape (which matches a single byte in UTF-8
         mode)  to appear in lookbehind assertions, because it makes it impossi-
-        ble to calculate the length of the lookbehind.
+        ble to calculate the length of the lookbehind. The \X escape, which can
+        match different numbers of bytes, is also not permitted.
-        Atomic groups can be used in conjunction with lookbehind assertions  to
+        Atomic  groups can be used in conjunction with lookbehind assertions to
         specify efficient matching at the end of the subject string. Consider a
         simple pattern such as
           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
-        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
           ^.*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
-        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
           ^(?>.*)(?<=abcd)
-        or, equivalently,
+        or, equivalently, using the possessive quantifier syntax,
           ^.*+(?<=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.
+    Using multiple assertions
         Several assertions (of any sort) may occur in succession. For example,
           (?<=\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-
-        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
           (?<=\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
         checks that the preceding three characters are not "999".
-Line 2607 
 ASSERTIONS
+Line 3527 
 ASSERTIONS
           (?<=(?<!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
           (?<=\d{3}(?!999)...)foo
-        is another pattern which 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".
-        Assertion subpatterns are not capturing subpatterns,  and  may  not  be
-        repeated,  because  it  makes no sense to assert the same thing several
-        times. If any kind of assertion contains capturing  subpatterns  within
-        it,  these are counted for the purposes of numbering the capturing sub-
-        patterns in the whole pattern.  However, substring capturing is carried
-        out  only  for  positive assertions, because it does not make sense for
-        negative assertions.
  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  previous  capturing
+        on  the result of an assertion, or whether a previous capturing subpat-
-        subpattern  matched  or not. The two possible forms of conditional sub-
+        tern matched or not. The two possible forms of  conditional  subpattern
-        pattern are
+        are
           (?(condition)yes-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.
         There are three kinds of condition. If the text between the parentheses
-        consists  of  a  sequence  of digits, the condition is satisfied if the
+        consists of a sequence of digits, the condition  is  satisfied  if  the
-        capturing subpattern of that number has previously matched. The  number
+        capturing  subpattern of that number has previously matched. The number
-        must  be  greater than zero. Consider the following pattern, which con-
+        must be greater than zero. Consider the following pattern,  which  con-
-        tains non-significant white space to make it more readable (assume  the
+        tains  non-significant white space to make it more readable (assume the
-        PCRE_EXTENDED  option)  and  to  divide it into three parts for ease of
+        PCRE_EXTENDED option) and to divide it into three  parts  for  ease  of
         discussion:
           ( \( )?    [^()]+    (?(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-
-        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 the first set
         of parentheses matched or not. If they did, that is, if subject started
         with an opening parenthesis, the condition is true, and so the yes-pat-
-        tern is executed and a  closing  parenthesis  is  required.  Otherwise,
+        tern  is  executed  and  a  closing parenthesis is required. Otherwise,
-        since  no-pattern  is  not  present, the subpattern matches nothing. In
+        since no-pattern is not present, the  subpattern  matches  nothing.  In
-        other words,  this  pattern  matches  a  sequence  of  non-parentheses,
+        other  words,  this  pattern  matches  a  sequence  of non-parentheses,
         optionally enclosed in parentheses.
         If the condition is the string (R), it is satisfied if a recursive call
-        to the pattern or subpattern has been made. At "top level", the  condi-
+        to  the pattern or subpattern has been made. At "top level", the condi-
-        tion  is  false.   This  is  a  PCRE  extension. Recursive patterns are
+        tion is false.  This  is  a  PCRE  extension.  Recursive  patterns  are
         described in the next section.