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

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

Parent Directory | Revision Log | View Patch Patch

-revision 51 by nigel,
Sat Feb 24 21:39:37 2007 UTC
+revision 416 by ph10,
Sat Apr 11 14:34:02 2009 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
+ synopses of each function in the library have not been included. There are
+ separate text files for the pcregrep and pcretest commands.
+ -----------------------------------------------------------------------------
+ PCRE(3)                                                                PCRE(3)
+ NAME
+        PCRE - Perl-compatible regular expressions
+ 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. Certain features that appeared in Python and
+        PCRE before they appeared in Perl are also available using  the  Python
+        syntax.  There is also some support for certain .NET and Oniguruma syn-
+        tax items, and there is an option for  requesting  some  minor  changes
+        that give better JavaScript compatibility.
+        The  current  implementation of PCRE (release 7.x) corresponds approxi-
+        mately with Perl 5.10, including support for UTF-8 encoded strings  and
+        Unicode general category properties. However, UTF-8 and Unicode support
+        has to be explicitly enabled; it is not the default. The Unicode tables
+        correspond to Unicode release 5.1.
+        In  addition to the Perl-compatible matching function, PCRE contains an
+        alternative matching function that matches the same  compiled  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
+        Details of exactly which Perl regular expression features are  and  are
+        not supported by PCRE are given in separate documents. See the pcrepat-
+        tern and pcrecompat pages. There is a syntax summary in the  pcresyntax
+        page.
+        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. The features them-
+        selves are described in the pcrebuild page. Documentation about  build-
+        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 comprises a number  of  different  sec-
+        tions.  In the "man" format, each of these is a separate "man page". In
+        the HTML format, each is a separate page, linked from the  index  page.
+        In  the  plain text format, all the sections are concatenated, for ease
+        of searching. The sections are as follows:
+          pcre              this document
+          pcre-config       show PCRE installation configuration information
+          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
+          pcresyntax        quick syntax reference
+          pcreperform       discussion of performance issues
+          pcreposix         the POSIX-compatible C API
+          pcreprecompile    details of saving and re-using precompiled patterns
+          pcresample        discussion of the sample program
+          pcrestack         discussion of stack usage
+          pcretest          description of the pcretest testing command
+        In addition, in the "man" and HTML formats, there is a short  page  for
+        each C library function, listing its arguments and results.
+ LIMITATIONS
+        There  are some size limitations in PCRE but it is hoped that they will
+        never in practice be relevant.
+        The maximum length of a compiled pattern is 65539 (sic) bytes  if  PCRE
+        is compiled with the default internal linkage size of 2. If you want to
+        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).
+        In  these  cases the limit is substantially larger.  However, the speed
+        of execution is slower.
+        All values in repeating quantifiers must be less than 65536.
+        There is no limit to the number of parenthesized subpatterns, but there
+        can be no more than 65535 capturing subpatterns.
+        The maximum length of name for a named subpattern is 32 characters, and
+        the maximum number of named subpatterns is 10000.
+        The maximum length of a subject string is the largest  positive  number
+        that  an integer variable can hold. However, when using the traditional
+        matching function, PCRE uses recursion to handle subpatterns and indef-
+        inite  repetition.  This means that the available stack space may limit
+        the size of a subject string that can be processed by certain patterns.
+        For a discussion of stack issues, see the pcrestack documentation.
+ UTF-8 AND UNICODE PROPERTY SUPPORT
+        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()
+        with the PCRE_UTF8 option flag, or the  pattern  must  start  with  the
+        sequence  (*UTF8).  When  either of these is the case, both the pattern
+        and any subject strings that are matched  against  it  are  treated  as
+        UTF-8 strings instead of just strings of bytes.
+        If  you compile PCRE with UTF-8 support, but do not use it at run time,
+        the library will be a bit bigger, but the additional run time  overhead
+        is limited to testing the PCRE_UTF8 flag occasionally, so should not be
+        very big.
+        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, the Unicode script names such as Arabic  or  Han,
+        and  the  derived  properties  Any  and L&. A full list is given in the
+        pcrepattern documentation. Only the short names for properties are sup-
+        ported.  For example, \p{L} matches a letter. Its Perl synonym, \p{Let-
+        ter}, is not supported.  Furthermore,  in  Perl,  many  properties  may
+        optionally  be  prefixed by "Is", for compatibility with Perl 5.6. PCRE
+        does not support this.
+    Validity of UTF-8 strings
+        When you set the PCRE_UTF8 flag, the strings  passed  as  patterns  and
+        subjects are (by default) checked for validity on entry to the relevant
+        functions. From release 7.3 of PCRE, the check is according  the  rules
+        of  RFC  3629, which are themselves derived from the Unicode specifica-
+        tion. Earlier releases of PCRE followed the rules of  RFC  2279,  which
+        allows  the  full range of 31-bit values (0 to 0x7FFFFFFF). The current
+        check allows only values in the range U+0 to U+10FFFF, excluding U+D800
+        to U+DFFF.
+        The  excluded  code  points are the "Low Surrogate Area" of Unicode, of
+        which the Unicode Standard says this: "The Low Surrogate Area does  not
+        contain  any  character  assignments,  consequently  no  character code
+        charts or namelists are provided for this area. Surrogates are reserved
+        for  use  with  UTF-16 and then must be used in pairs." The code points
+        that are encoded by UTF-16 pairs  are  available  as  independent  code
+        points  in  the  UTF-8  encoding.  (In other words, the whole surrogate
+        thing is a fudge for UTF-16 which unfortunately messes up UTF-8.)
+        If an  invalid  UTF-8  string  is  passed  to  PCRE,  an  error  return
+        (PCRE_ERROR_BADUTF8) is given. In some situations, you may already know
+        that your strings are valid, and therefore want to skip these checks in
+        order to improve performance. If you set the PCRE_NO_UTF8_CHECK flag at
+        compile time or at run time, PCRE assumes that the pattern  or  subject
+        it  is  given  (respectively)  contains only valid UTF-8 codes. In this
+        case, it does not diagnose an invalid UTF-8 string.
+        If you pass an invalid UTF-8 string  when  PCRE_NO_UTF8_CHECK  is  set,
+        what  happens  depends on why the string is invalid. If the string con-
+        forms to the "old" definition of UTF-8 (RFC 2279), it is processed as a
+        string  of  characters  in  the  range 0 to 0x7FFFFFFF. In other words,
+        apart from the initial validity test, PCRE (when in UTF-8 mode) handles
+        strings  according  to  the more liberal rules of RFC 2279. However, if
+        the string does not even conform to RFC 2279, the result is  undefined.
+        Your program may crash.
+        If  you  want  to  process  strings  of  values  in the full range 0 to
+x7FFFFFFF, encoded in a UTF-8-like manner as per the old RFC, you  can
+        set PCRE_NO_UTF8_CHECK to bypass the more restrictive test. However, in
+        this situation, you will have to apply your own validity check.
+    General comments about UTF-8 mode
+. An unbraced hexadecimal escape sequence (such  as  \xb3)  matches  a
+        two-byte UTF-8 character if the value is greater than 127.
+.  Octal  numbers  up to \777 are recognized, and match two-byte UTF-8
+        characters for values greater than \177.
+. 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 sin-
+        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. 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. 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}.  Note  that  this  also applies to \b, because it is defined in
+        terms of \w and \W.
+. Similarly, characters that match the POSIX named  character  classes
+        are all low-valued characters.
+.  However,  the Perl 5.10 horizontal and vertical whitespace matching
+        escapes (\h, \H, \v, and \V) do match all the appropriate Unicode char-
+        acters.
+.  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. Even when Unicode property
+        support is available, PCRE supports case-insensitive matching only when
+        there is a one-to-one mapping between a letter's  cases.  There  are  a
+        small  number  of  many-to-one  mappings in Unicode; these are not sup-
+        ported by PCRE.
+ AUTHOR
+        Philip Hazel
+        University Computing Service
+        Cambridge CB2 3QH, England.
+        Putting an actual email address here seems to have been a spam  magnet,
+        so  I've  taken  it away. If you want to email me, use my two initials,
+        followed by the two digits 10, at the domain cam.ac.uk.
+ REVISION
+        Last updated: 11 April 2009
+        Copyright (c) 1997-2009 University of Cambridge.
+ ------------------------------------------------------------------------------
+ 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. It assumes use of the  configure
+        script,  where the optional features are selected or deselected by pro-
+        viding options to configure before running the make  command.  However,
+        the  same  options  can be selected in both Unix-like and non-Unix-like
+        environments using the GUI facility of  CMakeSetup  if  you  are  using
+        CMake instead of configure to build PCRE.
+        The complete list of options for configure (which includes the standard
+        ones such as the  selection  of  the  installation  directory)  can  be
+        obtained by running
+          ./configure --help
+        The  following  sections  include  descriptions  of options whose names
+        begin with --enable or --disable. These settings specify changes to the
+        defaults  for  the configure command. Because of the way that configure
+        works, --enable and --disable always come in pairs, so  the  complemen-
+        tary  option always exists as well, but as it specifies the default, it
+        is 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 Unicode character strings, add
+          --enable-utf8
+        to the configure command. Of itself, this  does  not  make  PCRE  treat
+        strings  as UTF-8. As well as compiling PCRE with this option, you also
+        have have to set the PCRE_UTF8 option when you call the  pcre_compile()
+        function.
+        If  you set --enable-utf8 when compiling in an EBCDIC environment, PCRE
+        expects its input to be either ASCII or UTF-8 (depending on the runtime
+        option).  It  is not possible to support both EBCDIC and UTF-8 codes in
+        the same  version  of  the  library.  Consequently,  --enable-utf8  and
+        --enable-ebcdic are mutually exclusive.
+ 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 30K  of  tables  to  the
+        PCRE  library.  Only  the general category properties such as Lu and Nd
+        are supported. Details are given in the pcrepattern documentation.
+ CODE VALUE OF NEWLINE
+        By default, PCRE interprets the linefeed (LF) character  as  indicating
+        the  end  of  a line. This is the normal newline character on Unix-like
+        systems. You can compile PCRE to use carriage return (CR)  instead,  by
+        adding
+          --enable-newline-is-cr
+        to  the  configure  command.  There  is  also  a --enable-newline-is-lf
+        option, which explicitly specifies linefeed as the newline character.
+        Alternatively, you can specify that line endings are to be indicated by
+        the two character sequence CRLF. If you want this, add
+          --enable-newline-is-crlf
+        to the configure command. There is a fourth option, specified by
+          --enable-newline-is-anycrlf
+        which  causes  PCRE  to recognize any of the three sequences CR, LF, or
+        CRLF as indicating a line ending. Finally, a fifth option, specified by
+          --enable-newline-is-any
+        causes PCRE to recognize any Unicode newline sequence.
+        Whatever line ending convention is selected when PCRE is built  can  be
+        overridden  when  the library functions are called. At build time it is
+        conventional to use the standard for your operating system.
+ WHAT \R MATCHES
+        By default, the sequence \R in a pattern matches  any  Unicode  newline
+        sequence,  whatever  has  been selected as the line ending sequence. If
+        you specify
+          --enable-bsr-anycrlf
+        the default is changed so that \R matches only CR, LF, or  CRLF.  What-
+        ever  is selected when PCRE is built can be overridden when the library
+        functions are called.
+ BUILDING SHARED AND STATIC LIBRARIES
+        The PCRE building process uses libtool to build both shared and  static
+        Unix  libraries by default. You can suppress one of these by adding one
+        of
+          --disable-shared
+          --disable-static
+        to the configure command, as required.
+ POSIX MALLOC USAGE
+        When PCRE is called through the POSIX interface (see the pcreposix doc-
+        umentation),  additional  working  storage  is required for holding the
+        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.
+        The default threshold above which the stack is no longer used is 10; it
+        can be changed by adding a setting such as
+          --with-posix-malloc-threshold=20
+        to the configure command.
+ 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
+        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
+        is  possible  to compile PCRE to use three-byte or four-byte offsets by
+        adding a setting such as
+          --with-link-size=3
+        to the configure command. The value given must be 2,  3,  or  4.  Using
+        longer  offsets slows down the operation of PCRE because it has to load
+        additional bytes when handling them.
+ AVOIDING EXCESSIVE STACK USAGE
+        When matching with the pcre_exec() function, PCRE implements backtrack-
+        ing  by  making recursive calls to an internal function called match().
+        In environments where the size of the stack is limited,  this  can  se-
+        verely  limit  PCRE's operation. (The Unix environment does not usually
+        suffer from this problem, but it may sometimes be necessary to increase
+        the  maximum  stack size.  There is a discussion in the pcrestack docu-
+        mentation.) An alternative approach to recursion that uses memory  from
+        the  heap  to remember data, instead of using recursive function calls,
+        has been implemented to work round the problem of limited  stack  size.
+        If you want to build a version of PCRE that works this way, add
+          --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  manage-
+        ment  functions. By default these point to malloc() and free(), but you
+        can replace the pointers so that your own functions are used.
+        Separate functions are  provided  rather  than  using  pcre_malloc  and
+        pcre_free  because  the  usage  is  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  malloc()  and  free().  PCRE  runs
+        noticeably more 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.
+ LIMITING PCRE RESOURCE USAGE
+        Internally,  PCRE has a function called match(), which it calls repeat-
+        edly  (sometimes  recursively)  when  matching  a  pattern   with   the
+        pcre_exec()  function.  By controlling the maximum number of times this
+        function may be called during a single matching operation, a limit  can
+        be  placed  on  the resources used by a single call to pcre_exec(). The
+        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.  This  setting  has  no  effect   on   the
+        pcre_dfa_exec() matching function.
+        In  some  environments  it is desirable to limit the depth of recursive
+        calls of match() more strictly than the total number of calls, in order
+        to  restrict  the maximum amount of stack (or heap, if --disable-stack-
+        for-recursion is specified) that is used. A second limit controls this;
+        it  defaults  to  the  value  that is set for --with-match-limit, which
+        imposes no additional constraints. However, you can set a  lower  limit
+        by adding, for example,
+          --with-match-limit-recursion=10000
+        to  the  configure  command.  This  value can also be overridden at run
+        time.
+ CREATING CHARACTER TABLES AT BUILD TIME
+        PCRE uses fixed tables for processing characters whose code values  are
+        less  than 256. By default, PCRE is built with a set of tables that are
+        distributed in the file pcre_chartables.c.dist. These  tables  are  for
+        ASCII codes only. If you add
+          --enable-rebuild-chartables
+        to  the  configure  command, the distributed tables are no longer used.
+        Instead, a program called dftables is compiled and  run.  This  outputs
+        the source for new set of tables, created in the default locale of your
+        C runtime system. (This method of replacing the tables does not work if
+        you  are cross compiling, because dftables is run on the local host. If
+        you need to create alternative tables when cross  compiling,  you  will
+        have to do so "by hand".)
+ USING EBCDIC CODE
+        PCRE  assumes  by  default that it will run in an environment where the
+        character code is ASCII (or Unicode, which is  a  superset  of  ASCII).
+        This  is  the  case for most computer operating systems. PCRE can, how-
+        ever, be compiled to run in an EBCDIC environment by adding
+          --enable-ebcdic
+        to the configure command. This setting implies --enable-rebuild-charta-
+        bles.  You  should  only  use  it if you know that you are in an EBCDIC
+        environment (for example,  an  IBM  mainframe  operating  system).  The
+        --enable-ebcdic option is incompatible with --enable-utf8.
+ PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT
+        By default, pcregrep reads all files as plain text. You can build it so
+        that it recognizes files whose names end in .gz or .bz2, and reads them
+        with libz or libbz2, respectively, by adding one or both of
+          --enable-pcregrep-libz
+          --enable-pcregrep-libbz2
+        to the configure command. These options naturally require that the rel-
+        evant libraries are installed on your system. Configuration  will  fail
+        if they are not.
+ PCRETEST OPTION FOR LIBREADLINE SUPPORT
+        If you add
+          --enable-pcretest-libreadline
+        to  the  configure  command,  pcretest  is  linked with the libreadline
+        library, and when its input is from a terminal, it reads it  using  the
+        readline() function. This provides line-editing and history facilities.
+        Note that libreadline is GPL-licenced, so if you distribute a binary of
+        pcretest linked in this way, there may be licensing issues.
+        Setting  this  option  causes  the -lreadline option to be added to the
+        pcretest build. In many operating environments with  a  sytem-installed
+        libreadline this is sufficient. However, in some environments (e.g.  if
+        an unmodified distribution version of readline is in use),  some  extra
+        configuration  may  be necessary. The INSTALL file for libreadline says
+        this:
+          "Readline uses the termcap functions, but does not link with the
+          termcap or curses library itself, allowing applications which link
+          with readline the to choose an appropriate library."
+        If your environment has not been set up so that an appropriate  library
+        is automatically included, you may need to add something like
+          LIBS="-ncurses"
+        immediately before the configure command.
+ SEE ALSO
+        pcreapi(3), pcre_config(3).
+ AUTHOR
+        Philip Hazel
+        University Computing Service
+        Cambridge CB2 3QH, England.
+ REVISION
+        Last updated: 17 March 2009
+        Copyright (c) 1997-2009 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 alternative 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  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.
+ THE ALTERNATIVE MATCHING ALGORITHM
+        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, character by character, and as it does
+        this,  it remembers all the paths through the tree that represent valid
+        matches. In Friedl's terminology, this is a kind  of  "DFA  algorithm",
+        though  it is not implemented as a traditional finite state machine (it
+        keeps multiple states active simultaneously).
+        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 alternative 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. However, pos-
+        sessive quantifiers can make a difference when what follows could  also
+        match what is quantified, for example in a pattern like this:
+          ^a++\w!
+        This  pattern matches "aaab!" but not "aaa!", which would be matched by
+        a non-possessive quantifier. Similarly, if an atomic group is  present,
+        it  is matched as if it were a standalone pattern at the current point,
+        and the longest match is then "locked in" for the rest of  the  overall
+        pattern.
+. 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 or test for a specific group recursion are not
+        supported.
+. Because many paths through the tree may be  active,  the  \K  escape
+        sequence, which resets the start of the match when encountered (but may
+        be on some paths and not on others), is not  supported.  It  causes  an
+        error if encountered.
+.  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 alterna-
+        tive algorithm moves through the subject  string  one  character  at  a
+        time, for all active paths through the tree.
+.  Except for (*FAIL), the backtracking control verbs such as (*PRUNE)
+        are not supported. (*FAIL) is supported, and  behaves  like  a  failing
+        negative assertion.
+ ADVANTAGES OF THE ALTERNATIVE ALGORITHM
+        Using  the alternative matching algorithm provides the following advan-
+        tages:
+. 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 alternative algorithm.
+        For non-anchored patterns, the starting position of a partial match  is
+        available.
+.  Because  the  alternative  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 partial matching each time.
+ DISADVANTAGES OF THE ALTERNATIVE ALGORITHM
+        The alternative 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.
+. Although atomic groups are supported, their use does not provide the
+        performance advantage that it does for the standard algorithm.
+ AUTHOR
+        Philip Hazel
+        University Computing Service
+        Cambridge CB2 3QH, England.
+ REVISION
+        Last updated: 19 April 2008
+        Copyright (c) 1997-2008 University of Cambridge.
+ ------------------------------------------------------------------------------
+ PCREAPI(3)                                                          PCREAPI(3)
+ NAME
+        PCRE - Perl-compatible regular expressions
+ PCRE NATIVE API
+        #include <pcre.h>
+        pcre *pcre_compile(const char *pattern, int options,
+             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);
+        int pcre_exec(const pcre *code, const pcre_extra *extra,
+             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,
+             char *buffer, int buffersize);
+        int pcre_copy_substring(const char *subject, int *ovector,
+             int stringcount, int stringnumber, char *buffer,
+             int buffersize);
+        int pcre_get_named_substring(const pcre *code,
+             const char *subject, int *ovector,
+             int stringcount, const char *stringname,
+             const char **stringptr);
+        int pcre_get_stringnumber(const pcre *code,
+             const char *name);
+        int pcre_get_stringtable_entries(const pcre *code,
+             const char *name, char **first, char **last);
+        int pcre_get_substring(const char *subject, int *ovector,
+             int stringcount, int stringnumber,
+             const char **stringptr);
+        int pcre_get_substring_list(const char *subject,
+             int *ovector, int stringcount, const char ***listptr);
+        void pcre_free_substring(const char *stringptr);
+        void pcre_free_substring_list(const char **stringptr);
+        const unsigned char *pcre_maketables(void);
+        int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
+             int what, void *where);
+        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);
+        void *(*pcre_malloc)(size_t);
+        void (*pcre_free)(void *);
+        void *(*pcre_stack_malloc)(size_t);
+        void (*pcre_stack_free)(void *);
+        int (*pcre_callout)(pcre_callout_block *);
+ PCRE API OVERVIEW
+        PCRE has its own native API, which is described in this document. There
+        are also some wrapper functions that correspond to  the  POSIX  regular
+        expression  API.  These  are  described in the pcreposix documentation.
+        Both of these APIs define a set of C function calls. A C++  wrapper  is
+        distributed with PCRE. It is documented in the pcrecpp page.
+        The  native  API  C  function prototypes are defined in the header file
+        pcre.h, and on Unix systems the library itself is called  libpcre.   It
+        can normally be accessed by adding -lpcre to the command for linking an
+        application  that  uses  PCRE.  The  header  file  defines  the  macros
+        PCRE_MAJOR  and  PCRE_MINOR to contain the major and minor release num-
+        bers for the library.  Applications can use these  to  include  support
+        for different releases of PCRE.
+        The   functions   pcre_compile(),  pcre_compile2(),  pcre_study(),  and
+        pcre_exec() are used for compiling and matching regular expressions  in
+        a  Perl-compatible  manner. A sample program that demonstrates the sim-
+        plest way of using them is provided in the file  called  pcredemo.c  in
+        the  source distribution. The pcresample documentation describes how to
+        compile and 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. The alternative algorithm finds all possible matches (at  a  given
+        point  in  the subject), and scans the subject just once. 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 documentation.
+        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_get_stringtable_entries()
+        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  to build a set of character
+        tables  in  the  current  locale   for   passing   to   pcre_compile(),
+        pcre_exec(),  or  pcre_dfa_exec(). This is an optional facility that is
+        provided for specialist use.  Most  commonly,  no  special  tables  are
+        passed,  in  which case internal tables that are generated when PCRE is
+        built are used.
+        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 function pcre_refcount() maintains a  reference  count  in  a  data
+        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
+        calls. This should be done before calling any PCRE functions.
+        The global variables pcre_stack_malloc  and  pcre_stack_free  are  also
+        indirections  to  memory  management functions. These special functions
+        are used only when PCRE is compiled to use  the  heap  for  remembering
+        data, instead of recursive function calls, when running the pcre_exec()
+        function. See the pcrebuild documentation for  details  of  how  to  do
+        this.  It  is  a non-standard way of building PCRE, for use in environ-
+        ments that have limited stacks. Because of the greater  use  of  memory
+        management,  it  runs  more  slowly. Separate functions are provided so
+        that special-purpose external code can be  used  for  this  case.  When
+        used,  these  functions  are always called in a stack-like manner (last
+        obtained, first freed), and always for memory blocks of the same  size.
+        There  is  a discussion about PCRE's stack usage in the pcrestack docu-
+        mentation.
+        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
+        specified points during a matching operation. Details are given in  the
+        pcrecallout documentation.
+ NEWLINES
+        PCRE  supports five different conventions for indicating line breaks in
+        strings: a single CR (carriage return) character, a  single  LF  (line-
+        feed) character, the two-character sequence CRLF, any of the three pre-
+        ceding, or any Unicode newline sequence. The Unicode newline  sequences
+        are  the  three just mentioned, plus the single characters VT (vertical
+        tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS  (line
+        separator, U+2028), and PS (paragraph separator, U+2029).
+        Each  of  the first three conventions is used by at least one operating
+        system as its standard newline sequence. When PCRE is built, a  default
+        can  be  specified.  The default default is LF, which is the Unix stan-
+        dard. When PCRE is run, the default can be overridden,  either  when  a
+        pattern is compiled, or when it is matched.
+        At compile time, the newline convention can be specified by the options
+        argument of pcre_compile(), or it can be specified by special  text  at
+        the start of the pattern itself; this overrides any other settings. See
+        the pcrepattern page for details of the special character sequences.
+        In the PCRE documentation the word "newline" is used to mean "the char-
+        acter  or pair of characters that indicate a line break". The choice of
+        newline convention affects the handling of  the  dot,  circumflex,  and
+        dollar metacharacters, the handling of #-comments in /x mode, and, when
+        CRLF is a recognized line ending sequence, the match position  advance-
+        ment for a non-anchored pattern. There is more detail about this in the
+        section on pcre_exec() options below.
+        The choice of newline convention does not affect the interpretation  of
+        the  \n  or  \r  escape  sequences, nor does it affect what \R matches,
+        which is controlled in a similar way, but by separate options.
+ MULTITHREADING
+        The PCRE functions can be used in  multi-threading  applications,  with
+        the  proviso  that  the  memory  management  functions  pointed  to  by
+        pcre_malloc, pcre_free, pcre_stack_malloc, and pcre_stack_free, and the
+        callout function pointed to by pcre_callout, are shared by all threads.
+        The  compiled form of a regular expression is not altered during match-
+        ing, so the same compiled pattern can safely be used by several threads
+        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. However, compiling a  regular  expression
+        with  one version of PCRE for use with a different version is not guar-
+        anteed to work and may cause crashes.
+ CHECKING BUILD-TIME OPTIONS
+        int pcre_config(int what, void *where);
+        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-
+        tures.
+        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
+        available:
+          PCRE_CONFIG_UTF8
+        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 whose value specifies  the  default  character
+        sequence  that is recognized as meaning "newline". The four values that
+        are supported are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF,
+        and  -1  for  ANY.  Though they are derived from ASCII, the same values
+        are returned in EBCDIC environments. The default should normally corre-
+        spond to the standard sequence for your operating system.
+          PCRE_CONFIG_BSR
+        The output is an integer whose value indicates what character sequences
+        the \R escape sequence matches by default. A value of 0 means  that  \R
+        matches  any  Unicode  line ending sequence; a value of 1 means that \R
+        matches only CR, LF, or CRLF. The default can be overridden when a pat-
+        tern is compiled or matched.
+          PCRE_CONFIG_LINK_SIZE
+        The  output  is  an  integer that contains the number of bytes used for
+        internal linkage in compiled regular expressions. The value is 2, 3, or
+.  Larger  values  allow larger regular expressions to be compiled, at
+        the expense of slower matching. The default value of  2  is  sufficient
+        for  all  but  the  most massive patterns, since it allows the compiled
+        pattern to be up to 64K in size.
+          PCRE_CONFIG_POSIX_MALLOC_THRESHOLD
+        The output is an integer that contains the threshold  above  which  the
+        POSIX  interface  uses malloc() for output vectors. Further details are
+        given in the pcreposix documentation.
+          PCRE_CONFIG_MATCH_LIMIT
+        The output is a long integer that gives the default limit for the  num-
+        ber  of  internal  matching  function calls in a pcre_exec() execution.
+        Further details are given with pcre_exec() below.
+          PCRE_CONFIG_MATCH_LIMIT_RECURSION
+        The output is a long integer that gives the default limit for the depth
+        of   recursion  when  calling  the  internal  matching  function  in  a
+        pcre_exec() execution.  Further  details  are  given  with  pcre_exec()
+        below.
+          PCRE_CONFIG_STACKRECURSE
+        The  output is an integer that is set to one if internal recursion when
+        running pcre_exec() is implemented by recursive function calls that use
+        the  stack  to remember their state. This is the usual way that PCRE is
+        compiled. The output is zero if PCRE was compiled to use blocks of data
+        on  the  heap  instead  of  recursive  function  calls.  In  this case,
+        pcre_stack_malloc and  pcre_stack_free  are  called  to  manage  memory
+        blocks on the heap, thus avoiding the use of the stack.
+ COMPILING A PATTERN
+        pcre *pcre_compile(const char *pattern, int options,
+             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);
+        Either of the functions pcre_compile() or pcre_compile2() can be called
+        to compile a pattern into an internal form. The only difference between
+        the  two interfaces is that pcre_compile2() has an additional argument,
+        errorcodeptr, via which a numerical error code can be returned.
+        The pattern is a C string terminated by a binary zero, and is passed in
+        the  pattern  argument.  A  pointer to a single block of memory that is
+        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 (via pcre_free) 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 may contain a copy of the tableptr  argu-
+        ment, which is an address (see below).
+        The options argument contains various bit settings that affect the com-
+        pilation. It should be zero if no options are required.  The  available
+        options  are  described  below. Some of them (in particular, those that
+        are compatible with Perl, but also some others) can  also  be  set  and
+        unset  from  within  the  pattern  (see the detailed description in the
+        pcrepattern documentation). For those options that can be different  in
+        different  parts  of  the pattern, the contents of the options argument
+        specifies their initial settings at the start of compilation and execu-
+        tion.  The PCRE_ANCHORED and PCRE_NEWLINE_xxx options 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
+        sets the variable pointed to by errptr to point to a textual error mes-
+        sage. This is a static string that is part of the library. You must not
+        try to free it. The offset from the start of the pattern to the charac-
+        ter where 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
+        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  that  are  built  when  PCRE  is compiled, using the
+        default C locale. Otherwise, tableptr must be an address  that  is  the
+        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-
+        pile():
+          pcre *re;
+          const char *error;
+          int erroffset;
+          re = pcre_compile(
+            "^A.*Z",          /* the pattern */
+,                /* default options */
+            &error,           /* for error message */
+            &erroffset,       /* for error offset */
+            NULL);            /* use default character tables */
+        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
+        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_BSR_ANYCRLF
+          PCRE_BSR_UNICODE
+        These options (which are mutually exclusive) control what the \R escape
+        sequence  matches.  The choice is either to match only CR, LF, or CRLF,
+        or to match any Unicode newline sequence. The default is specified when
+        PCRE is built. It can be overridden from within the pattern, or by set-
+        ting an option when a compiled pattern is matched.
+          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. 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
+        at the end of the subject string. Without this option,  a  dollar  also
+        matches  immediately before a newline at the end of the string (but not
+        before any other newlines). The 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  those that indicate newline. Without it, a dot does
+        not match when the current position is at a  newline.  This  option  is
+        equivalent  to Perl's /s option, and it can be changed within a pattern
+        by a (?s) option setting. A negative class such as [^a] always  matches
+        newline characters, independent of the setting of this option.
+          PCRE_DUPNAMES
+        If  this  bit is set, names used to identify capturing subpatterns need
+        not be unique. This can be helpful for certain types of pattern when it
+        is  known  that  only  one instance of the named subpattern can ever be
+        matched. There are more details of named subpatterns  below;  see  also
+        the pcrepattern documentation.
+          PCRE_EXTENDED
+        If  this  bit  is  set,  whitespace  data characters in the pattern are
+        totally ignored except when escaped or inside a character class. White-
+        space does not include the VT character (code 11). In addition, charac-
+        ters between an unescaped # outside a character class and the next new-
+        line,  inclusive,  are  also  ignored.  This is equivalent to Perl's /x
+        option, and it can be changed within a pattern by a  (?x)  option  set-
+        ting.
+        This  option  makes  it possible to include comments inside complicated
+        patterns.  Note, however, that this applies only  to  data  characters.
+        Whitespace   characters  may  never  appear  within  special  character
+        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
+        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
+        letter that has no special meaning  causes  an  error,  thus  reserving
+        these  combinations  for  future  expansion.  By default, as in Perl, a
+        backslash followed by a letter with no special meaning is treated as  a
+        literal.  (Perl can, however, be persuaded to give a warning for this.)
+        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  in  the  subject  string,  though  the
+        matched text may continue over the newline.
+          PCRE_JAVASCRIPT_COMPAT
+        If this option is set, PCRE's behaviour is changed in some ways so that
+        it is compatible with JavaScript rather than Perl. The changes  are  as
+        follows:
+        (1)  A  lone  closing square bracket in a pattern causes a compile-time
+        error, because this is illegal in JavaScript (by default it is  treated
+        as a data character). Thus, the pattern AB]CD becomes illegal when this
+        option is set.
+        (2) At run time, a back reference to an unset subpattern group  matches
+        an  empty  string (by default this causes the current matching alterna-
+        tive to fail). A pattern such as (\1)(a) succeeds when this  option  is
+        set  (assuming  it can find an "a" in the subject), whereas it fails by
+        default, for Perl compatibility.
+          PCRE_MULTILINE
+        By default, PCRE treats the subject string as consisting  of  a  single
+        line  of characters (even if it actually contains newlines). The "start
+        of line" metacharacter (^) matches only at the  start  of  the  string,
+        while  the  "end  of line" metacharacter ($) matches only at the end of
+        the string, or before a terminating newline (unless PCRE_DOLLAR_ENDONLY
+        is set). This is the same as Perl.
+        When  PCRE_MULTILINE  it  is set, the "start of line" and "end of line"
+        constructs match immediately following or immediately  before  internal
+        newlines  in  the  subject string, respectively, as well as at the very
+        start and end. This is equivalent to Perl's /m option, and  it  can  be
+        changed within a pattern by a (?m) option setting. If there are no new-
+        lines in a subject string, or no occurrences of ^ or $  in  a  pattern,
+        setting PCRE_MULTILINE has no effect.
+          PCRE_NEWLINE_CR
+          PCRE_NEWLINE_LF
+          PCRE_NEWLINE_CRLF
+          PCRE_NEWLINE_ANYCRLF
+          PCRE_NEWLINE_ANY
+        These  options  override the default newline definition that was chosen
+        when PCRE was built. Setting the first or the second specifies  that  a
+        newline  is  indicated  by a single character (CR or LF, respectively).
+        Setting PCRE_NEWLINE_CRLF specifies that a newline is indicated by  the
+        two-character  CRLF  sequence.  Setting  PCRE_NEWLINE_ANYCRLF specifies
+        that any of the three preceding sequences should be recognized. Setting
+        PCRE_NEWLINE_ANY  specifies that any Unicode newline sequence should be
+        recognized. The Unicode newline sequences are the three just mentioned,
+        plus  the  single  characters  VT (vertical tab, U+000B), FF (formfeed,
+        U+000C), NEL (next line, U+0085), LS (line separator, U+2028),  and  PS
+        (paragraph  separator,  U+2029).  The  last  two are recognized only in
+        UTF-8 mode.
+        The newline setting in the  options  word  uses  three  bits  that  are
+        treated as a number, giving eight possibilities. Currently only six are
+        used (default plus the five values above). This means that if  you  set
+        more  than one newline option, the combination may or may not be sensi-
+        ble. For example, PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to
+        PCRE_NEWLINE_CRLF,  but other combinations may yield unused numbers and
+        cause an error.
+        The only time that a line break is specially recognized when  compiling
+        a  pattern  is  if  PCRE_EXTENDED  is set, and an unescaped # outside a
+        character class is encountered. This indicates  a  comment  that  lasts
+        until  after the next line break sequence. In other circumstances, line
+        break  sequences  are  treated  as  literal  data,   except   that   in
+        PCRE_EXTENDED mode, both CR and LF are treated as whitespace characters
+        and are therefore ignored.
+        The newline option that is set at compile time becomes the default that
+        is used for pcre_exec() and pcre_dfa_exec(), but it can be overridden.
+          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
+        ?  behaves as if it were followed by ?: but named parentheses can still
+        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
+        are not greedy by default, but become greedy if followed by "?". It  is
+        not  compatible  with Perl. It can also be set by a (?U) option setting
+        within the pattern.
+          PCRE_UTF8
+        This option causes PCRE to regard both the pattern and the  subject  as
+        strings  of  UTF-8 characters instead of single-byte character strings.
+        However, it is available only when PCRE is built to include UTF-8  sup-
+        port.  If not, the use of this option provokes an error. Details of how
+        this option changes the behaviour of PCRE are given in the  section  on
+        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. There is a  discussion  about  the  validity  of
+        UTF-8  strings  in  the main pcre page. If an invalid UTF-8 sequence of
+        bytes is found, pcre_compile() returns an error. If  you  already  know
+        that your pattern is valid, and you want to skip this check for perfor-
+        mance reasons, you 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  this  option
+        can  also be passed to pcre_exec() and pcre_dfa_exec(), to suppress the
+        UTF-8 validity checking 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. As PCRE has developed, some error codes  have
+        fallen out of use. To avoid confusion, they have not been re-used.
+ 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
+ [this code is not in use]
+ internal error: unexpected repeat
+ unrecognized character after (? or (?-
+ 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
+ [this code is not in use]
+ regular expression is too large
+ failed to get memory
+ unmatched parentheses
+ internal error: code overflow
+ unrecognized character after (?<
+ lookbehind assertion is not fixed length
+ malformed number or name 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
+ [this code is not in use]
+ 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 in subpattern name (missing terminator)
+ two named subpatterns 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
+ subpattern name is too long (maximum 32 characters)
+ too many named subpatterns (maximum 10000)
+ [this code is not in use]
+ octal value is greater than \377 (not in UTF-8 mode)
+ internal error: overran compiling workspace
+  internal  error:  previously-checked  referenced  subpattern not
+        found
+ DEFINE group contains more than one branch
+ repeating a DEFINE group is not allowed
+ inconsistent NEWLINE options
+ \g is not followed by a braced, angle-bracketed, or quoted
+                name/number or by a plain number
+ a numbered reference must not be zero
+ (*VERB) with an argument is not supported
+ (*VERB) not recognized
+ number is too big
+ subpattern name expected
+ digit expected after (?+
+ ] is an invalid data character in JavaScript compatibility mode
+        The numbers 32 and 10000 in errors 48 and 49  are  defaults;  different
+        values may be used if the limits were changed when PCRE was built.
+ STUDYING A PATTERN
+        pcre_extra *pcre_study(const pcre *code, int options
+             const char **errptr);
+        If  a  compiled  pattern is going to be used several times, it is worth
+        spending more time analyzing it in order to speed up the time taken for
+        matching.  The function pcre_study() takes a pointer to a compiled pat-
+        tern as its first argument. If studying the pattern produces additional
+        information  that  will  help speed up matching, pcre_study() returns a
+        pointer to a pcre_extra block, in which the study_data field points  to
+        the results of the study.
+        The  returned  value  from  pcre_study()  can  be  passed  directly  to
+        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 in the section on matching a pattern.
+        If studying the pattern does not  produce  any  additional  information
+        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
+        points to is set to NULL. Otherwise it is set to  point  to  a  textual
+        error message. This is a static string that is part of the library. You
+        must not try to free it. You should test the  error  pointer  for  NULL
+        after calling pcre_study(), to be sure that it has run successfully.
+        This is a typical call to pcre_study():
+          pcre_extra *pe;
+          pe = pcre_study(
+            re,             /* result of pcre_compile() */
+,              /* no options exist */
+            &error);        /* set to NULL or points to a message */
+        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 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,  indexed
+        by  character  value.  When running in UTF-8 mode, this applies only to
+        characters with codes less than 128. Higher-valued  codes  never  match
+        escapes  such  as  \w or \d, but can be tested with \p if PCRE is built
+        with Unicode character property support. The use of locales  with  Uni-
+        code  is discouraged. If you are handling characters with codes greater
+        than 128, you should either use UTF-8 and Unicode, or use locales,  but
+        not try to mix the two.
+        PCRE  contains  an  internal set of tables that are used when the final
+        argument of pcre_compile() is  NULL.  These  are  sufficient  for  many
+        applications.  Normally, the internal tables recognize only ASCII char-
+        acters. However, when PCRE is built, it is possible to cause the inter-
+        nal tables to be rebuilt in the default "C" locale of the local system,
+        which may cause them to be different.
+        The internal tables can always be overridden by tables supplied by  the
+        application that calls PCRE. These may be created in a different locale
+        from the default. As more and more applications change  to  using  Uni-
+        code, the need for this locale support is expected to die away.
+        External  tables  are  built by calling the 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_FR");
+          tables = pcre_maketables();
+          re = pcre_compile(..., tables);
+        The locale name "fr_FR" is used on Linux and other  Unix-like  systems;
+        if you are using Windows, the name for the French locale is "french".
+        When  pcre_maketables()  runs,  the  tables are built in memory that is
+        obtained via pcre_malloc. It is the caller's responsibility  to  ensure
+        that  the memory containing the tables remains available for as long as
+        it is needed.
+        The pointer that is passed to pcre_compile() is saved with the compiled
+        pattern,  and the same tables are used via this pointer by pcre_study()
+        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
+        int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
+             int what, void *where);
+        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
+        pattern.  The second argument is the result of pcre_study(), or NULL if
+        the pattern was not studied. The third argument specifies  which  piece
+        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
+        success, or one of the following negative numbers:
+          PCRE_ERROR_NULL       the argument code was NULL
+                                the argument where was NULL
+          PCRE_ERROR_BADMAGIC   the "magic number" was not found
+          PCRE_ERROR_BADOPTION  the value of what was invalid
+        The  "magic  number" is placed at the start of each compiled pattern as
+        an simple check against passing an arbitrary memory pointer. Here is  a
+        typical  call  of pcre_fullinfo(), to obtain the length of the compiled
+        pattern:
+          int rc;
+          size_t length;
+          rc = pcre_fullinfo(
+            re,               /* result of pcre_compile() */
+            pe,               /* result of pcre_study(), or NULL */
+            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
+        are as follows:
+          PCRE_INFO_BACKREFMAX
+        Return  the  number  of  the highest back reference in the pattern. The
+        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
+        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
+        non-anchored  pattern. The fourth argument should point to an int vari-
+        able. (This option used to be called PCRE_INFO_FIRSTCHAR; the old  name
+        is still recognized for backwards compatibility.)
+        If  there  is  a  fixed first byte, for example, from a pattern such as
+        (cat|cow|coyote), its value is returned. Otherwise, if either
+        (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
+        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
+-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
+        returned.  The fourth argument should point to an unsigned char * vari-
+        able.
+          PCRE_INFO_HASCRORLF
+        Return 1 if the pattern contains any explicit  matches  for  CR  or  LF
+        characters,  otherwise  0.  The  fourth argument should point to an int
+        variable. An explicit match is either a literal CR or LF character,  or
+        \r or \n.
+          PCRE_INFO_JCHANGED
+        Return  1  if  the (?J) or (?-J) option setting is used in the pattern,
+        otherwise 0. The fourth argument should point to an int variable.  (?J)
+        and (?-J) set and unset the local PCRE_DUPNAMES option, respectively.
+          PCRE_INFO_LASTLITERAL
+        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
+        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
+        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.
+          PCRE_INFO_NAMECOUNT
+          PCRE_INFO_NAMEENTRYSIZE
+          PCRE_INFO_NAMETABLE
+        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, which still acquire numbers. Several convenience functions such as
+        pcre_get_named_substring() are provided for  extracting  captured  sub-
+        strings  by  name. It is also possible to extract the data directly, by
+        first converting the name to a number in order to  access  the  correct
+        pointers in the output vector (described with 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
+        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
+        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-
+        sponding name, zero terminated. The names are  in  alphabetical  order.
+        When PCRE_DUPNAMES is set, duplicate names are in order of their paren-
+        theses numbers. For example, consider  the  following  pattern  (assume
+        PCRE_EXTENDED  is  set,  so  white  space  -  including  newlines  - is
+        ignored):
+          (?<date> (?<year>(\d\d)?\d\d) -
+          (?<month>\d\d) - (?<day>\d\d) )
+        There are four named subpatterns, so the table has  four  entries,  and
+        each  entry  in the table is eight bytes long. The table is as follows,
+        with non-printing bytes shows in hexadecimal, and undefined bytes shown
+        as ??:
+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 using the
+        name-to-number map, remember that the length of the entries  is  likely
+        to be different for each compiled pattern.
+          PCRE_INFO_OKPARTIAL
+        Return  1 if the pattern can be used for partial matching, otherwise 0.
+        The fourth argument should point to an int  variable.  The  pcrepartial
+        documentation  lists  the restrictions that apply to patterns when par-
+        tial matching is used.
+          PCRE_INFO_OPTIONS
+        Return a copy of the options with which the pattern was  compiled.  The
+        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 at the start of the pattern itself. In
+        other words, they are the options that will be in force  when  matching
+        starts.  For  example, if the pattern /(?im)abc(?-i)d/ is compiled with
+        the PCRE_EXTENDED option, the result is PCRE_CASELESS,  PCRE_MULTILINE,
+        and PCRE_EXTENDED.
+        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
+          \A    always
+          \G    always
+          .*    if PCRE_DOTALL is set and there are no back
+                  references to the subpattern in which .* appears
+        For such patterns, the PCRE_ANCHORED bit is set in the options returned
+        by pcre_fullinfo().
+          PCRE_INFO_SIZE
+        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
+        Return the size of the data block pointed to by the study_data field in
+        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
+        variable.
+ OBSOLETE INFO FUNCTION
+        int pcre_info(const pcre *code, int *optptr, int *firstcharptr);
+        The pcre_info() function is now obsolete because its interface  is  too
+        restrictive  to return all the available data about a compiled pattern.
+        New  programs  should  use  pcre_fullinfo()  instead.  The   yield   of
+        pcre_info()  is the number of capturing subpatterns, or one of the fol-
+        lowing negative numbers:
+          PCRE_ERROR_NULL       the argument code was NULL
+          PCRE_ERROR_BADMAGIC   the "magic number" was not found
+        If the optptr argument is not NULL, a copy of the  options  with  which
+        the  pattern  was  compiled  is placed in the integer it points to (see
+        PCRE_INFO_OPTIONS above).
+        If the pattern is not anchored and the  firstcharptr  argument  is  not
+        NULL,  it is used to pass back information about the first character of
+        any matched string (see PCRE_INFO_FIRSTBYTE above).
+ REFERENCE COUNTS
+        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
+        compiled pattern, which is passed in the code argument. If the  pattern
+        has been studied, the result of the study should be passed in the extra
+        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():
+          int rc;
+          int ovector[30];
+          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) */
+    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 pcre_extra block contains  the  following
+        fields (not necessarily in this order):
+          unsigned long int flags;
+          void *study_data;
+          unsigned long int match_limit;
+          unsigned long int match_limit_recursion;
+          void *callout_data;
+          const unsigned char *tables;
+        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_MATCH_LIMIT_RECURSION
+          PCRE_EXTRA_CALLOUT_DATA
+          PCRE_EXTRA_TABLES
+        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 appropriate flag bit. You should not set this yourself, but you may
+        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  repeat-
+        edly  (sometimes  recursively). The limit set by match_limit is imposed
+        on the number of times this function is called during  a  match,  which
+        has  the  effect  of  limiting the amount of backtracking that can take
+        place. For patterns that are not anchored, the count restarts from zero
+        for each position in the subject string.
+        The  default  value  for  the  limit can be set when PCRE is built; the
+        default default is 10 million, which handles all but the  most  extreme
+        cases.  You  can  override  the  default by suppling pcre_exec() with a
+        pcre_extra    block    in    which    match_limit    is    set,     and
+        PCRE_EXTRA_MATCH_LIMIT  is  set  in  the  flags  field. If the limit is
+        exceeded, pcre_exec() returns PCRE_ERROR_MATCHLIMIT.
+        The match_limit_recursion field is similar to match_limit, but  instead
+        of limiting the total number of times that match() is called, it limits
+        the depth of recursion. The recursion depth is a  smaller  number  than
+        the  total number of calls, because not all calls to match() are recur-
+        sive.  This limit is of use only if it is set smaller than match_limit.
+        Limiting the recursion depth limits the amount of  stack  that  can  be
+        used, or, when PCRE has been compiled to use memory on the heap instead
+        of the stack, the amount of heap memory that can be used.
+        The default value for match_limit_recursion can be  set  when  PCRE  is
+        built;  the  default  default  is  the  same  value  as the default for
+        match_limit. You can override the default by suppling pcre_exec()  with
+        a   pcre_extra   block  in  which  match_limit_recursion  is  set,  and
+        PCRE_EXTRA_MATCH_LIMIT_RECURSION is set in  the  flags  field.  If  the
+        limit is exceeded, pcre_exec() returns PCRE_ERROR_RECURSIONLIMIT.
+        The  pcre_callout  field is used in conjunction with the "callout" fea-
+        ture, which is described in the pcrecallout documentation.
+        The tables field  is  used  to  pass  a  character  tables  pointer  to
+        pcre_exec();  this overrides the value that is stored with the compiled
+        pattern. A non-NULL value is stored with the compiled pattern  only  if
+        custom  tables  were  supplied to pcre_compile() via its tableptr argu-
+        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-
+        using patterns that have been saved after compiling  with  an  external
+        set  of  tables,  because  the  external tables might be at a different
+        address when pcre_exec() is called. See the  pcreprecompile  documenta-
+        tion for a discussion of saving compiled patterns for later use.
+    Option bits for pcre_exec()
+        The  unused  bits of the options argument for pcre_exec() must be zero.
+        The only bits that may  be  set  are  PCRE_ANCHORED,  PCRE_NEWLINE_xxx,
+        PCRE_NOTBOL,    PCRE_NOTEOL,   PCRE_NOTEMPTY,   PCRE_NO_START_OPTIMIZE,
+        PCRE_NO_UTF8_CHECK and PCRE_PARTIAL.
+          PCRE_ANCHORED
+        The PCRE_ANCHORED option limits pcre_exec() to matching  at  the  first
+        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_BSR_ANYCRLF
+          PCRE_BSR_UNICODE
+        These options (which are mutually exclusive) control what the \R escape
+        sequence matches. The choice is either to match only CR, LF,  or  CRLF,
+        or  to  match  any Unicode newline sequence. These options override the
+        choice that was made or defaulted when the pattern was compiled.
+          PCRE_NEWLINE_CR
+          PCRE_NEWLINE_LF
+          PCRE_NEWLINE_CRLF
+          PCRE_NEWLINE_ANYCRLF
+          PCRE_NEWLINE_ANY
+        These options override  the  newline  definition  that  was  chosen  or
+        defaulted  when the pattern was compiled. For details, see the descrip-
+        tion of pcre_compile()  above.  During  matching,  the  newline  choice
+        affects  the  behaviour  of the dot, circumflex, and dollar metacharac-
+        ters. It may also alter the way the match position is advanced after  a
+        match failure for an unanchored pattern.
+        When  PCRE_NEWLINE_CRLF,  PCRE_NEWLINE_ANYCRLF,  or PCRE_NEWLINE_ANY is
+        set, and a match attempt for an unanchored pattern fails when the  cur-
+        rent  position  is  at  a  CRLF  sequence,  and the pattern contains no
+        explicit matches for  CR  or  LF  characters,  the  match  position  is
+        advanced by two characters instead of one, in other words, to after the
+        CRLF.
+        The above rule is a compromise that makes the most common cases work as
+        expected.  For  example,  if  the  pattern  is .+A (and the PCRE_DOTALL
+        option is not set), it does not match the string "\r\nA" because, after
+        failing  at the start, it skips both the CR and the LF before retrying.
+        However, the pattern [\r\n]A does match that string,  because  it  con-
+        tains an explicit CR or LF reference, and so advances only by one char-
+        acter after the first failure.
+        An explicit match for CR of LF is either a literal appearance of one of
+        those  characters,  or  one  of the \r or \n escape sequences. Implicit
+        matches such as [^X] do not count, nor does \s (which includes  CR  and
+        LF in the characters that it matches).
+        Notwithstanding  the above, anomalous effects may still occur when CRLF
+        is a valid newline sequence and explicit \r or \n escapes appear in the
+        pattern.
+          PCRE_NOTBOL
+        This option specifies that first character of the subject string is not
+        the beginning of a line, so the  circumflex  metacharacter  should  not
+        match  before it. Setting this without PCRE_MULTILINE (at compile time)
+        causes circumflex never to match. This option affects only  the  behav-
+        iour of the circumflex metacharacter. It does not affect \A.
+          PCRE_NOTEOL
+        This option specifies that the end of the subject string is not the end
+        of a line, so the dollar metacharacter should not match it nor  (except
+        in  multiline mode) a newline immediately before it. Setting this with-
+        out 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
+        An empty string is not considered to be a valid match if this option is
+        set.  If  there are alternatives in the pattern, they are tried. If all
+        the alternatives match the empty string, the entire  match  fails.  For
+        example, if the pattern
+          a?b?
+        is  applied  to  a string not beginning with "a" or "b", it matches the
+        empty string at the start of the subject. With PCRE_NOTEMPTY set,  this
+        match is not valid, so PCRE searches further into the string for occur-
+        rences of "a" or "b".
+        Perl has no direct equivalent of PCRE_NOTEMPTY, but it does make a spe-
+        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 and PCRE_ANCHORED, and then
+        if  that  fails by advancing the starting offset (see below) and trying
+        an ordinary match again. There is some code that demonstrates how to do
+        this in the pcredemo.c sample program.
+          PCRE_NO_START_OPTIMIZE
+        There  are a number of optimizations that pcre_exec() uses at the start
+        of a match, in order to speed up the process. For  example,  if  it  is
+        known  that  a  match must start with a specific character, it searches
+        the subject for that character, and fails immediately if it cannot find
+        it,  without actually running the main matching function. When callouts
+        are in use, these optimizations can cause  them  to  be  skipped.  This
+        option  disables  the  "start-up" optimizations, causing performance to
+        suffer, but ensuring that the callouts do occur.
+          PCRE_NO_UTF8_CHECK
+        When PCRE_UTF8 is set at compile time, the validity of the subject as a
+        UTF-8  string is automatically checked when pcre_exec() is subsequently
+        called.  The value of startoffset is also checked  to  ensure  that  it
+        points  to  the start of a UTF-8 character. There is a discussion about
+        the validity of UTF-8 strings in the section on UTF-8  support  in  the
+        main  pcre  page.  If  an  invalid  UTF-8  sequence  of bytes is found,
+        pcre_exec() returns the error PCRE_ERROR_BADUTF8. If  startoffset  con-
+        tains an invalid value, PCRE_ERROR_BADUTF8_OFFSET is returned.
+        If  you  already  know that your subject is valid, and you want to skip
+        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 bytes) 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 char-
+        acter. 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-
+        cess.   Setting  startoffset differs from just passing over a shortened
+        string and setting PCRE_NOTBOL in the case of  a  pattern  that  begins
+        with any kind of lookbehind. For example, consider the pattern
+          \Biss\B
+        which  finds  occurrences  of "iss" in the middle of words. (\B matches
+        only if the current position in the subject is not  a  word  boundary.)
+        When  applied  to the string "Mississipi" the first call to pcre_exec()
+        finds the first occurrence. If pcre_exec() is called  again  with  just
+        the  remainder  of  the  subject,  namely  "issipi", it does not match,
+        because \B is always false at the start of the subject, which is deemed
+        to  be  a  word  boundary. However, if pcre_exec() is passed the entire
+        string again, but with startoffset set to 4, it finds the second occur-
+        rence  of "iss" because it is able to look behind the starting point to
+        discover that it is preceded by a letter.
+        If a non-zero starting offset is passed when the pattern  is  anchored,
+        one attempt to match at the given offset is made. This can only succeed
+        if the pattern does not require the match to be at  the  start  of  the
+        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
+        parts  of  the  pattern.  Following the usage in Jeffrey Friedl's book,
+        this is called "capturing" in what follows, and the  phrase  "capturing
+        subpattern"  is  used for a fragment of a pattern that picks out a sub-
+        string. PCRE supports several other kinds of  parenthesized  subpattern
+        that do not cause substrings to be captured.
+        Captured substrings are returned to the caller via a vector of integers
+        whose address is passed in ovector. The number of elements in the  vec-
+        tor  is  passed in ovecsize, which must be a non-negative number. Note:
+        this argument is NOT the size of ovector in bytes.
+        The first two-thirds of the vector is used to pass back  captured  sub-
+        strings,  each  substring using a pair of integers. The remaining third
+        of the vector is used as workspace by pcre_exec() while  matching  cap-
+        turing  subpatterns, and is not available for passing back information.
+        The number passed in ovecsize should always be a multiple of three.  If
+        it is not, it is rounded down.
+        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 each pair is set to the byte offset of the  first  character
+        in  a  substring, and the second is set to the byte offset of the first
+        character after the end of a substring. Note: these values  are  always
+        byte offsets, even in UTF-8 mode. They are not character counts.
+        The  first  pair  of  integers, ovector[0] and ovector[1], identify the
+        portion of the subject string matched by the entire pattern.  The  next
+        pair  is  used for the first capturing subpattern, and so on. The value
+        returned by pcre_exec() is one more than the highest numbered pair that
+        has  been  set.  For example, if two substrings have been captured, the
+        returned value is 3. If there are no capturing subpatterns, the  return
+        value from a successful match is 1, indicating that just the first pair
+        of offsets has been set.
+        If a capturing subpattern is matched repeatedly, it is the last portion
+        of the string that it matched that is returned.
+        If  the vector is too small to hold all the captured substring offsets,
+        it is used as far as possible (up to two-thirds of its length), and the
+        function  returns  a value of zero. If the substring offsets are not of
+        interest, pcre_exec() may be called with ovector  passed  as  NULL  and
+        ovecsize  as zero. However, if the pattern contains back references and
+        the ovector is not big enough to remember the related substrings,  PCRE
+        has  to  get additional memory for use during matching. Thus it is usu-
+        ally advisable to supply an ovector.
+        The pcre_info() function can be used to find  out  how  many  capturing
+        subpatterns  there  are  in  a  compiled pattern. The smallest size for
+        ovector that will allow for n captured substrings, in addition  to  the
+        offsets of the substring matched by the whole pattern, is (n+1)*3.
+        It  is  possible for capturing subpattern number n+1 to match some 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) the
+        return from the function is 4, and subpatterns 1 and 3 are matched, but
+ is  not.  When  this happens, both values in the offset pairs corre-
+        sponding to unused subpatterns are set to -1.
+        Offset values that correspond to unused subpatterns at the end  of  the
+        expression  are  also  set  to  -1. For example, if the string "abc" is
+        matched against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are  not
+        matched.  The  return  from the function is 2, because the highest used
+        capturing subpattern number is 1. However, you can refer to the offsets
+        for  the  second  and third capturing subpatterns if you wish (assuming
+        the vector is large enough, of course).
+        Some convenience functions are provided  for  extracting  the  captured
+        substrings as separate strings. These are described below.
+    Error 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)
+        The subject string did not match the pattern.
+          PCRE_ERROR_NULL           (-2)
+        Either code or subject was passed as NULL,  or  ovector  was  NULL  and
+        ovecsize was not zero.
+          PCRE_ERROR_BADOPTION      (-3)
+        An unrecognized bit was set in the options argument.
+          PCRE_ERROR_BADMAGIC       (-4)
+        PCRE  stores a 4-byte "magic number" at the start of the compiled code,
+        to catch the case when it is passed a junk pointer and to detect when a
+        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_OPCODE (-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
+        overwriting of the compiled pattern.
+          PCRE_ERROR_NOMEMORY       (-6)
+        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
+        purpose. If the call via pcre_malloc() fails, this error is given.  The
+        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(),
+        and  pcre_get_substring_list()  functions  (see  below).  It  is  never
+        returned by pcre_exec().
+          PCRE_ERROR_MATCHLIMIT     (-8)
+        The  backtracking  limit,  as  specified  by the match_limit 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.
+        See the pcrecallout documentation for details.
+          PCRE_ERROR_BADUTF8        (-10)
+        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-
+        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.
+          PCRE_ERROR_RECURSIONLIMIT (-21)
+        The internal recursion limit, as specified by the match_limit_recursion
+        field  in  a  pcre_extra  structure (or defaulted) was reached. See the
+        description above.
+          PCRE_ERROR_BADNEWLINE     (-23)
+        An invalid combination of PCRE_NEWLINE_xxx options was given.
+        Error numbers -16 to -20 and -22 are not used by pcre_exec().
+ EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
+        int pcre_copy_substring(const char *subject, int *ovector,
+             int stringcount, int stringnumber, char *buffer,
+             int buffersize);
+        int pcre_get_substring(const char *subject, int *ovector,
+             int stringcount, int stringnumber,
+             const char **stringptr);
+        int pcre_get_substring_list(const char *subject,
+             int *ovector, int stringcount, const char ***listptr);
+        Captured substrings can be  accessed  directly  by  using  the  offsets
+        returned  by  pcre_exec()  in  ovector.  For convenience, the functions
+        pcre_copy_substring(),    pcre_get_substring(),    and    pcre_get_sub-
+        string_list()  are  provided for extracting captured substrings as new,
+        separate, zero-terminated strings. These functions identify  substrings
+        by  number.  The  next section describes functions for extracting named
+        substrings.
+        A substring that contains a binary zero is correctly extracted and  has
+        a  further zero added on the end, but the result is not, of course, a C
+        string.  However, you can process such a string  by  referring  to  the
+        length  that  is  returned  by  pcre_copy_substring() and pcre_get_sub-
+        string().  Unfortunately, the interface to pcre_get_substring_list() is
+        not  adequate for handling strings containing binary zeros, because the
+        end of the final string is not independently indicated.
+        The first three arguments are the same for all  three  of  these  func-
+        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
+        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 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,  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
+        obtained via pcre_malloc, and its address is  returned  via  stringptr.
+        The  yield  of  the function is the length of the string, not including
+        the terminating zero, or one of these error codes:
+          PCRE_ERROR_NOMEMORY       (-6)
+        The buffer was too small for pcre_copy_substring(), or the  attempt  to
+        get memory failed for pcre_get_substring().
+          PCRE_ERROR_NOSUBSTRING    (-7)
+        There is no substring whose number is stringnumber.
+        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 that is obtained via pcre_malloc. The address of
+        the memory block is returned via listptr, which is also  the  start  of
+        the  list  of  string pointers. The end of the list is marked by a NULL
+        pointer. The yield of the function is zero if all  went  well,  or  the
+        error code
+          PCRE_ERROR_NOMEMORY       (-6)
+        if the attempt to get the memory block failed.
+        When  any of these functions encounter a substring that is unset, which
+        can happen when capturing subpattern number n+1 matches  some  part  of
+        the  subject, but subpattern n has not been used at all, they return an
+        empty string. This can be distinguished from a genuine zero-length sub-
+        string  by inspecting the appropriate offset in ovector, which is nega-
+        tive for unset substrings.
+        The two convenience functions pcre_free_substring() and  pcre_free_sub-
+        string_list()  can  be  used  to free the memory returned by a previous
+        call  of  pcre_get_substring()  or  pcre_get_substring_list(),  respec-
+        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  that  cannot   use
+        pcre_free  directly;  it is for these cases that the functions are pro-
+        vided.
+ 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_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.  For example, for this pattern
+          (a+)b(?<xxx>\d+)...
+        the number of the subpattern called "xxx" is 2. If the name is known to
+        be unique (PCRE_DUPNAMES was not set), you can find the number from the
+        name by calling pcre_get_stringnumber(). The first argument is the com-
+        piled pattern, and the second is the name. The yield of the function is
+        the  subpattern  number,  or PCRE_ERROR_NOSUBSTRING (-7) if there is no
+        subpattern of that name.
+        Given the number, you can extract the substring directly, or use one of
+        the functions described in the previous section. For convenience, there
+        are also two functions that do the whole job.
+        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
+        to the compiled pattern. This is needed in order to gain access to  the
+        name-to-number translation table.
+        These  functions call pcre_get_stringnumber(), and if it succeeds, they
+        then call pcre_copy_substring() or pcre_get_substring(),  as  appropri-
+        ate.  NOTE:  If PCRE_DUPNAMES is set and there are duplicate names, the
+        behaviour may not be what you want (see the next section).
+        Warning: If the pattern uses the "(?|" feature to set up multiple  sub-
+        patterns  with  the  same  number,  you cannot use names to distinguish
+        them, because names are not included in the compiled code. The matching
+        process uses only numbers.
+ DUPLICATE SUBPATTERN NAMES
+        int pcre_get_stringtable_entries(const pcre *code,
+             const char *name, char **first, char **last);
+        When  a  pattern  is  compiled with the PCRE_DUPNAMES option, names for
+        subpatterns are not required to  be  unique.  Normally,  patterns  with
+        duplicate  names  are such that in any one match, only one of the named
+        subpatterns participates. An example is shown in the pcrepattern  docu-
+        mentation.
+        When    duplicates   are   present,   pcre_copy_named_substring()   and
+        pcre_get_named_substring() return the first substring corresponding  to
+        the  given  name  that  is set. If none are set, PCRE_ERROR_NOSUBSTRING
+        (-7) is returned; no  data  is  returned.  The  pcre_get_stringnumber()
+        function  returns one of the numbers that are associated with the name,
+        but it is not defined which it is.
+        If you want to get full details of all captured substrings for a  given
+        name,  you  must  use  the pcre_get_stringtable_entries() function. The
+        first argument is the compiled pattern, and the second is the name. The
+        third  and  fourth  are  pointers to variables which are updated by the
+        function. After it has run, they point to the first and last entries in
+        the  name-to-number  table  for  the  given  name.  The function itself
+        returns the length of each entry,  or  PCRE_ERROR_NOSUBSTRING  (-7)  if
+        there  are none. The format of the table is described above in the sec-
+        tion entitled Information about a  pattern.   Given  all  the  relevant
+        entries  for the name, you can extract each of their numbers, and hence
+        the captured data, if any.
+ 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 matching algorithm that  scans  the
+        subject  string  just  once, and does not backtrack. This has different
+        characteristics to the normal algorithm, and  is  not  compatible  with
+        Perl.  Some  of the features of PCRE patterns are not supported. Never-
+        theless, there are times when this kind of matching can be useful.  For
+        a discussion of the two matching algorithms, see the pcrematching docu-
+        mentation.
+        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 potential matches.
+        Here is an example of a simple call to pcre_dfa_exec():
+          int rc;
+          int ovector[10];
+          int wspace[20];
+          rc = pcre_dfa_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_NEW-
+        LINE_xxx, 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 alterna-
+        tive  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.  In
+        fact,  all  the  strings  have the same start offset. (Space could have
+        been saved by giving this only once, but it was decided to retain  some
+        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
+        that  uses  a back reference for the condition, or a test for recursion
+        in a specific group. These are 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.
+ SEE ALSO
+        pcrebuild(3), pcrecallout(3), pcrecpp(3)(3), pcrematching(3),  pcrepar-
+        tial(3), pcreposix(3), pcreprecompile(3), pcresample(3), pcrestack(3).
+ AUTHOR
+        Philip Hazel
+        University Computing Service
+        Cambridge CB2 3QH, England.
+ REVISION
+        Last updated: 11 April 2009
+        Copyright (c) 1997-2009 University of Cambridge.
+ ------------------------------------------------------------------------------
+ PCRECALLOUT(3)                                                  PCRECALLOUT(3)
+ NAME
+        PCRE - Perl-compatible regular expressions
+ PCRE CALLOUTS
+        int (*pcre_callout)(pcre_callout_block *);
+        PCRE provides a feature called "callout", which is a means of temporar-
+        ily passing control to the caller of PCRE  in  the  middle  of  pattern
+        matching.  The  caller of PCRE provides an external function by putting
+        its entry point in the global variable pcre_callout. By  default,  this
+        variable contains NULL, which disables all calling out.
+        Within  a  regular  expression,  (?C) indicates the points at which the
+        external function is to be called.  Different  callout  points  can  be
+        identified  by  putting  a number less than 256 after the letter C. The
+        default value is zero.  For  example,  this  pattern  has  two  callout
+        points:
+          (?C1)abc(?C2)def
+        If  the  PCRE_AUTO_CALLOUT  option  bit  is  set when pcre_compile() is
+        called, PCRE automatically  inserts  callouts,  all  with  number  255,
+        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 by default, 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.
+        You can disable these optimizations by passing the  PCRE_NO_START_OPTI-
+        MIZE  option  to  pcre_exec()  or  pcre_dfa_exec(). This slows down the
+        matching process, but does ensure that callouts  such  as  the  example
+        above are 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;
+          int         *offset_vector;
+          const char  *subject;
+          int          subject_length;
+          int          start_match;
+          int          current_position;
+          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
+        block format. The initial version was 0; the current version is 1.  The
+        version  number  will  change  again in future if additional fields are
+        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 for manual call-
+        outs, and 255 for automatically generated callouts).
+        The offset_vector field is a pointer to the vector of offsets that  was
+        passed   by   the   caller  to  pcre_exec()  or  pcre_dfa_exec().  When
+        pcre_exec() is used, the contents can be inspected in order to  extract
+        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 of the values that
+        were passed to pcre_exec().
+        The start_match field normally contains the offset within  the  subject
+        at  which  the  current  match  attempt started. However, if the escape
+        sequence \K has been encountered, this value is changed to reflect  the
+        modified  starting  point.  If the pattern is not anchored, the callout
+        function may be called several times from the same point in the pattern
+        for different starting points in the subject.
+        The  current_position  field  contains the offset within the subject of
+        the current match pointer.
+        When the pcre_exec() function is used, the capture_top  field  contains
+        one  more than the number of the highest numbered captured substring so
+        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
+        does not support captured substrings.
+        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()
+        or  pcre_dfa_exec() specifically so that it can be passed back in call-
+        outs. It is passed in the pcre_callout field  of  the  pcre_extra  data
+        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 external callout function returns an integer to PCRE. If the  value
+        is  zero,  matching  proceeds  as  normal. If the value is greater than
+        zero, matching fails at the current point, but  the  testing  of  other
+        matching possibilities goes ahead, just as if a lookahead assertion had
+        failed. If the value is less than zero, the  match  is  abandoned,  and
+        pcre_exec() (or pcre_dfa_exec()) returns the negative value.
+        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
+        reserved for use by callout functions; it will never be  used  by  PCRE
+        itself.
+ AUTHOR
+        Philip Hazel
+        University Computing Service
+        Cambridge CB2 3QH, England.
+ REVISION
+        Last updated: 15 March 2009
+        Copyright (c) 1997-2009 University of Cambridge.
+ ------------------------------------------------------------------------------
+ PCRECOMPAT(3)                                                    PCRECOMPAT(3)
+ NAME
+        PCRE - Perl-compatible regular expressions
+ 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  mainly
+        with  respect  to  Perl 5.8, though PCRE versions 7.0 and later contain
+        some features that are expected to be in the forthcoming Perl 5.10.
+. PCRE has only a subset of Perl's UTF-8 and Unicode support.  Details
+        of  what  it does have are given in the section on UTF-8 support in the
+        main pcre page.
+. PCRE does not allow repeat quantifiers on lookahead assertions. Perl
+        permits  them,  but they do not mean what you might think. For example,
+        (?!a){3} does not assert that the next three characters are not "a". It
+        just asserts that the next character is not "a" three times.
+.  Capturing  subpatterns  that occur inside negative lookahead asser-
+        tions are counted, but their entries in the offsets  vector  are  never
+        set.  Perl sets its numerical variables from any such patterns that are
+        matched before the assertion fails to match something (thereby succeed-
+        ing),  but  only  if the negative lookahead assertion contains just one
+        branch.
+. 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 in
+        the pattern to represent a binary zero.
+.  The  following Perl escape sequences are not supported: \l, \u, \L,
+        \U, and \N. In fact these are implemented by Perl's general string-han-
+        dling  and are not part of its pattern matching engine. If any of these
+        are encountered by PCRE, an error is generated.
+. The Perl escape sequences \p, \P, and \X are supported only if  PCRE
+        is  built  with Unicode character property support. The properties that
+        can be tested with \p and \P are limited to the general category  prop-
+        erties  such  as  Lu and Nd, script names such as Greek or Han, and the
+        derived properties Any and L&.
+. 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
+            \Qabc$xyz\E        abc$xyz           abc followed by the
+                                                   contents of $xyz
+            \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
+        classes.
+. Fairly obviously, PCRE does not support the (?{code}) and (??{code})
+        constructions. However, there is support for recursive  patterns.  This
+        is  not available in Perl 5.8, but will be in Perl 5.10. Also, the PCRE
+        "callout" feature allows an external function to be called during  pat-
+        tern matching. See the pcrecallout documentation for details.
+.  Subpatterns  that  are  called  recursively or as "subroutines" are
+        always treated as atomic groups in  PCRE.  This  is  like  Python,  but
+        unlike Perl.
+.  There are some differences that are concerned with the settings of
+        captured strings when part of  a  pattern  is  repeated.  For  example,
+        matching  "aba"  against  the  pattern  /^(a(b)?)+$/  in Perl leaves $2
+        unset, but in PCRE it is set to "b".
+.  PCRE  does  support  Perl  5.10's  backtracking  verbs  (*ACCEPT),
+        (*FAIL),  (*F),  (*COMMIT), (*PRUNE), (*SKIP), and (*THEN), but only in
+        the forms without an  argument.  PCRE  does  not  support  (*MARK).  If
+        (*ACCEPT)  is within capturing parentheses, PCRE does not set that cap-
+        ture group; this is different to Perl.
+. PCRE provides some extensions to the Perl regular expression facil-
+        ities.   Perl  5.10  will  include new features that are not in earlier
+        versions, some of which (such as named parentheses) have been  in  PCRE
+        for some time. This list is with respect to Perl 5.10:
+        (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 $
+        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. Otherwise, like Perl, the backslash is quietly
+        ignored.  (Perl can be made to issue a warning.)
+        (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 at matching time to force a pattern to be
+        tried only at the first matching position in the subject string.
+        (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 escape sequence can be restricted to match only CR,  LF,  or
+        CRLF by the PCRE_BSR_ANYCRLF option.
+        (h) The callout facility is PCRE-specific.
+        (i) The partial matching facility is PCRE-specific.
+        (j) Patterns compiled by PCRE can be saved and re-used at a later time,
+        even on different hosts that have the other endianness.
+        (k) The alternative matching function (pcre_dfa_exec())  matches  in  a
+        different way and is not Perl-compatible.
+        (l)  PCRE  recognizes some special sequences such as (*CR) at the start
+        of a pattern that set overall options that cannot be changed within the
+        pattern.
+ AUTHOR
+        Philip Hazel
+        University Computing Service
+        Cambridge CB2 3QH, England.
+ REVISION
+        Last updated: 11 September 2007
+        Copyright (c) 1997-2007 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 that are supported
+        by PCRE are described in detail below. There is a quick-reference  syn-
+        tax summary in the pcresyntax page. PCRE tries to match Perl syntax and
+        semantics as closely as it can. PCRE  also  supports  some  alternative
+        regular  expression  syntax (which does not conflict with the Perl syn-
+        tax) in order to provide some compatibility with regular expressions in
+        Python, .NET, and Oniguruma.
+        Perl's  regular expressions are described in its own documentation, and
+        regular expressions in general are covered in a number of  books,  some
+        of  which  have  copious  examples. Jeffrey Friedl's "Mastering Regular
+        Expressions", published by  O'Reilly,  covers  regular  expressions  in
+        great  detail.  This  description  of  PCRE's  regular  expressions  is
+        intended as reference material.
+        The original operation of PCRE was on strings of  one-byte  characters.
+        However,  there is now also support for UTF-8 character strings. To use
+        this, you must build PCRE to  include  UTF-8  support,  and  then  call
+        pcre_compile()  with  the  PCRE_UTF8  option.  There  is also a special
+        sequence that can be given at the start of a pattern:
+          (*UTF8)
+        Starting a pattern with this sequence  is  equivalent  to  setting  the
+        PCRE_UTF8  option.  This  feature  is  not Perl-compatible. How setting
+        UTF-8 mode affects pattern matching  is  mentioned  in  several  places
+        below.  There  is  also  a  summary of UTF-8 features in the section on
+        UTF-8 support in the main pcre page.
+        The remainder of this document discusses the  patterns  that  are  sup-
+        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. Some of the features discussed below are not available
+        when  pcre_dfa_exec()  is used. The advantages and disadvantages of the
+        alternative function, and how it differs from the normal function,  are
+        discussed in the pcrematching page.
+ NEWLINE CONVENTIONS
+        PCRE  supports five different conventions for indicating line breaks in
+        strings: a single CR (carriage return) character, a  single  LF  (line-
+        feed) character, the two-character sequence CRLF, any of the three pre-
+        ceding, or any Unicode newline sequence. The pcreapi page  has  further
+        discussion  about newlines, and shows how to set the newline convention
+        in the options arguments for the compiling and matching functions.
+        It is also possible to specify a newline convention by starting a  pat-
+        tern string with one of the following five sequences:
+          (*CR)        carriage return
+          (*LF)        linefeed
+          (*CRLF)      carriage return, followed by linefeed
+          (*ANYCRLF)   any of the three above
+          (*ANY)       all Unicode newline sequences
+        These override the default and the options given to pcre_compile(). For
+        example, on a Unix system where LF is the default newline sequence, the
+        pattern
+          (*CR)a.b
+        changes the convention to CR. That pattern matches "a\nb" because LF is
+        no longer a newline. Note that these special settings,  which  are  not
+        Perl-compatible,  are  recognized  only at the very start of a pattern,
+        and that they must be in upper case.  If  more  than  one  of  them  is
+        present, the last one is used.
+        The  newline  convention  does  not  affect what the \R escape sequence
+        matches. By default, this is any Unicode  newline  sequence,  for  Perl
+        compatibility.  However, this can be changed; see the description of \R
+        in the section entitled "Newline sequences" below. A change of \R  set-
+        ting can be combined with a change of newline convention.
+ CHARACTERS AND METACHARACTERS
+        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. When
+        caseless  matching is specified (the PCRE_CASELESS option), letters are
+        matched independently of case. 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  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 metacharacters: those that are recog-
+        nized anywhere in the pattern except within square brackets, and  those
+        that  are  recognized  within square brackets. Outside square brackets,
+        the metacharacters are as follows:
+          \      general escape character with several uses
+          ^      assert start of string (or line, in multiline mode)
+          $      assert end of string (or line, in multiline mode)
+          .      match any character except newline (by default)
+          [      start character class definition
+          |      start of alternative branch
+          (      start subpattern
+          )      end subpattern
+          ?      extends the meaning of (
+                 also 0 or 1 quantifier
+                 also quantifier minimizer
+          *      0 or more quantifier
+          +      1 or more quantifier
+                 also "possessive quantifier"
+          {      start min/max quantifier
+        Part of a pattern that is in square brackets  is  called  a  "character
+        class". In a character class the only metacharacters are:
+          \      general escape character
+          ^      negate the class, but only if the first character
+          -      indicates character range
+          [      POSIX character class (only if followed by POSIX
+                   syntax)
+          ]      terminates the character class
+        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-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 metacharacter, so  it  is
+        always  safe  to  precede  a non-alphanumeric with backslash to specify
+        that it stands for itself. In particular, if you want to match a  back-
+        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
+        # outside a character class and the next newline are ignored. An escap-
+        ing backslash can be used to include a whitespace  or  #  character  as
+        part of the pattern.
+        If  you  want  to remove the special meaning from a sequence of charac-
+        ters, you can do so by putting them between \Q and \E. This is  differ-
+        ent  from  Perl  in  that  $  and  @ are handled as literals in \Q...\E
+        sequences in PCRE, whereas in Perl, $ and @ cause  variable  interpola-
+        tion. Note the following examples:
+          Pattern            PCRE matches   Perl matches
+          \Qabc$xyz\E        abc$xyz        abc followed by the
+                                              contents of $xyz
+          \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
+        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
+        terminates  a  pattern,  but  when  a pattern is being prepared by text
+        editing, it is usually easier  to  use  one  of  the  following  escape
+        sequences than the binary character it represents:
+          \a        alarm, that is, the BEL character (hex 07)
+          \cx       "control-x", where x is any character
+          \e        escape (hex 1B)
+          \f        formfeed (hex 0C)
+          \n        linefeed (hex 0A)
+          \r        carriage return (hex 0D)
+          \t        tab (hex 09)
+          \ddd      character with octal code ddd, or backreference
+          \xhh      character with hex code hh
+          \x{hhh..} character with hex code hhh..
+        The  precise  effect of \cx is as follows: if x is a lower case letter,
+        it is converted to upper case. Then bit 6 of the character (hex 40)  is
+        inverted.   Thus  \cz becomes hex 1A, but \c{ becomes hex 3B, while \c;
+        becomes hex 7B.
+        After \x, from zero to two hexadecimal digits are read (letters can  be
+        in  upper  or  lower case). Any number of hexadecimal digits may appear
+        between \x{ and }, but the value of the character  code  must  be  less
+        than 256 in non-UTF-8 mode, and less than 2**31 in UTF-8 mode. That is,
+        the maximum value in hexadecimal is 7FFFFFFF. Note that this is  bigger
+        than the largest Unicode code point, which is 10FFFF.
+        If  characters  other than hexadecimal digits appear between \x{ and },
+        or if there is no terminating }, this form of escape is not recognized.
+        Instead,  the  initial  \x  will  be interpreted as a basic hexadecimal
+        escape, with no following digits, giving a  character  whose  value  is
+        zero.
+        Characters whose value is less than 256 can be defined by either of the
+        two syntaxes for \x. There is no difference in the way  they  are  han-
+        dled. For example, \xdc is exactly the same as \x{dc}.
+        After  \0  up  to two further octal digits are read. If there are fewer
+        than two digits, just  those  that  are  present  are  used.  Thus  the
+        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 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
+        have been at least that many previous capturing left parentheses in the
+        expression,  the  entire  sequence  is  taken  as  a  back reference. A
+        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
+        and there have not been that many capturing subpatterns, PCRE  re-reads
+        up to three octal digits following the backslash, and uses them to gen-
+        erate a data character. Any subsequent digits stand for themselves.  In
+        non-UTF-8  mode,  the  value  of a character specified in octal must be
+        less than \400. In UTF-8 mode, values up to  \777  are  permitted.  For
+        example:
+          \040   is another way of writing a space
+          \40    is the same, provided there are fewer than 40
+                    previous capturing subpatterns
+          \7     is always a back reference
+          \11    might be a back reference, or another way of
+                    writing a tab
+          \011   is always a tab
+          \0113  is a tab followed by the character "3"
+          \113   might be a back reference, otherwise the
+                    character with octal code 113
+          \377   might be a back reference, otherwise
+                    the byte consisting entirely of 1 bits
+          \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
+        leading zero, because no more than three octal digits are ever read.
+        All the sequences that define a single character value can be used both
+        inside  and  outside character classes. In addition, inside a character
+        class, the sequence \b is interpreted as the backspace  character  (hex
+),  and the sequences \R and \X are interpreted as the characters "R"
+        and "X", respectively. Outside a character class, these sequences  have
+        different meanings (see below).
+    Absolute and relative back references
+        The  sequence  \g followed by an unsigned or a negative number, option-
+        ally enclosed in braces, is an absolute or relative back  reference.  A
+        named back reference can be coded as \g{name}. Back references are dis-
+        cussed later, following the discussion of parenthesized subpatterns.
+    Absolute and relative subroutine calls
+        For compatibility with Oniguruma, the non-Perl syntax \g followed by  a
+        name or a number enclosed either in angle brackets or single quotes, is
+        an alternative syntax for referencing a subpattern as  a  "subroutine".
+        Details  are  discussed  later.   Note  that  \g{...} (Perl syntax) and
+        \g<...> (Oniguruma syntax) are not synonymous. The  former  is  a  back
+        reference; the latter is a subroutine call.
+    Generic character types
+        Another 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
+          \h     any horizontal whitespace character
+          \H     any character that is not a horizontal whitespace character
+          \s     any whitespace character
+          \S     any character that is not a whitespace character
+          \v     any vertical whitespace character
+          \V     any character that is not a vertical whitespace character
+          \w     any "word" character
+          \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,
+        of each pair.
+        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). If
+        "use locale;" is included in a Perl script, \s may match the VT charac-
+        ter. In PCRE, it never does.
+        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. These sequences retain
+        their original meanings from before UTF-8 support was available, mainly
+        for  efficiency  reasons. Note that this also affects \b, because it is
+        defined in terms of \w and \W.
+        The sequences \h, \H, \v, and \V are Perl 5.10 features. In contrast to
+        the  other  sequences, these do match certain high-valued codepoints in
+        UTF-8 mode.  The horizontal space characters are:
+          U+0009     Horizontal tab
+          U+0020     Space
+          U+00A0     Non-break space
+          U+1680     Ogham space mark
+          U+180E     Mongolian vowel separator
+          U+2000     En quad
+          U+2001     Em quad
+          U+2002     En space
+          U+2003     Em space
+          U+2004     Three-per-em space
+          U+2005     Four-per-em space
+          U+2006     Six-per-em space
+          U+2007     Figure space
+          U+2008     Punctuation space
+          U+2009     Thin space
+          U+200A     Hair space
+          U+202F     Narrow no-break space
+          U+205F     Medium mathematical space
+          U+3000     Ideographic space
+        The vertical space characters are:
+          U+000A     Linefeed
+          U+000B     Vertical tab
+          U+000C     Formfeed
+          U+000D     Carriage return
+          U+0085     Next line
+          U+2028     Line separator
+          U+2029     Paragraph separator
+        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 a French locale such  as  "fr_FR"  in  Unix-like
+        systems,  or "french" in Windows, some character codes greater than 128
+        are used for accented letters, and these are matched by \w. The use  of
+        locales with Unicode is discouraged.
+    Newline sequences
+        Outside  a  character class, by default, the escape sequence \R matches
+        any Unicode newline sequence. This is a Perl 5.10 feature. In non-UTF-8
+        mode \R is equivalent to the following:
+          (?>\r\n|\n|\x0b|\f|\r|\x85)
+        This  is  an  example  of an "atomic group", details of which are given
+        below.  This particular group matches either the two-character sequence
+        CR  followed  by  LF,  or  one  of  the single characters LF (linefeed,
+        U+000A), VT (vertical tab, U+000B), FF (formfeed, U+000C), CR (carriage
+        return, U+000D), or NEL (next line, U+0085). The two-character sequence
+        is treated as a single unit that cannot be split.
+        In UTF-8 mode, two additional characters whose codepoints  are  greater
+        than 255 are added: LS (line separator, U+2028) and PS (paragraph sepa-
+        rator, U+2029).  Unicode character property support is not  needed  for
+        these characters to be recognized.
+        It is possible to restrict \R to match only CR, LF, or CRLF (instead of
+        the complete set  of  Unicode  line  endings)  by  setting  the  option
+        PCRE_BSR_ANYCRLF either at compile time or when the pattern is matched.
+        (BSR is an abbrevation for "backslash R".) This can be made the default
+        when  PCRE  is  built;  if this is the case, the other behaviour can be
+        requested via the PCRE_BSR_UNICODE option.   It  is  also  possible  to
+        specify  these  settings  by  starting a pattern string with one of the
+        following sequences:
+          (*BSR_ANYCRLF)   CR, LF, or CRLF only
+          (*BSR_UNICODE)   any Unicode newline sequence
+        These override the default and the options given to pcre_compile(), but
+        they can be overridden by options given to pcre_exec(). Note that these
+        special settings, which are not Perl-compatible, are recognized only at
+        the  very  start  of a pattern, and that they must be in upper case. If
+        more than one of them is present, the last one is  used.  They  can  be
+        combined  with  a  change of newline convention, for example, a pattern
+        can start with:
+          (*ANY)(*BSR_ANYCRLF)
+        Inside a character class, \R matches the letter "R".