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

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

Parent Directory | Revision Log | View Patch Patch

-revision 63 by nigel,
Sat Feb 24 21:40:03 2007 UTC
+revision 79 by nigel,
Sat Feb 24 21:40:52 2007 UTC
 Line 1
+ -----------------------------------------------------------------------------
  This file contains a concatenation of the PCRE man pages, converted to plain
  text format for ease of searching with a text editor, or for use on systems
  that do not have a man page processor. The small individual files that give
-Line 5 
 synopses of each function in the library
+Line 6 
 synopses of each function in the library
  separate text files for the pcregrep and pcretest commands.
  -----------------------------------------------------------------------------
+ PCRE(3)                                                                PCRE(3)
  NAME
-      PCRE - Perl-compatible regular expressions
+        PCRE - Perl-compatible regular expressions
- DESCRIPTION
+ INTRODUCTION
-      The PCRE library is a set of functions that implement  regu-
+        The  PCRE  library is a set of functions that implement regular expres-
-      lar  expression  pattern  matching using the same syntax and
+        sion pattern matching using the same syntax and semantics as Perl, with
-      semantics as Perl, with just a few differences. The  current
+        just  a  few  differences.  The current implementation of PCRE (release
-      implementation  of  PCRE  (release 4.x) corresponds approxi-
+.x) corresponds approximately with Perl  5.8,  including  support  for
-      mately with Perl 5.8, including support  for  UTF-8  encoded
+        UTF-8 encoded strings and Unicode general category properties. However,
-      strings.    However,  this  support  has  to  be  explicitly
+        this support has to be explicitly enabled; it is not the default.
-      enabled; it is not the default.
+        In addition to the Perl-compatible matching function,  PCRE  also  con-
-      PCRE is written in C and released as a C library. However, a
+        tains  an  alternative matching function that matches the same compiled
-      number  of  people  have  written wrappers and interfaces of
+        patterns in a different way. In certain circumstances, the  alternative
-      various kinds. A C++ class is included  in  these  contribu-
+        function  has  some  advantages.  For  a discussion of the two matching
-      tions,  which  can  be found in the Contrib directory at the
+        algorithms, see the pcrematching page.
-      primary FTP site, which is:
+        PCRE is written in C and released as a C library. A  number  of  people
-      ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre
+        have  written  wrappers and interfaces of various kinds. In particular,
+        Google Inc.  have provided a comprehensive C++  wrapper.  This  is  now
-      Details of exactly which Perl  regular  expression  features
+        included as part of the PCRE distribution. The pcrecpp page has details
-      are  and  are  not  supported  by PCRE are given in separate
+        of this interface. Other people's contributions can  be  found  in  the
-      documents. See the pcrepattern and pcrecompat pages.
+        Contrib directory at the primary FTP site, which is:
-      Some features of PCRE can be included, excluded, or  changed
+        ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre
-      when  the library is built. The pcre_config() function makes
-      it possible for a client  to  discover  which  features  are
+        Details  of  exactly which Perl regular expression features are and are
-      available.  Documentation  about  building  PCRE for various
+        not supported by PCRE are given in separate documents. See the pcrepat-
-      operating systems can be found in the  README  file  in  the
+        tern and pcrecompat pages.
-      source distribution.
+        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.
  USER DOCUMENTATION
-      The user documentation for PCRE has been  split  up  into  a
+        The user documentation for PCRE comprises a number  of  different  sec-
-      number  of  different sections. In the "man" format, each of
+        tions.  In the "man" format, each of these is a separate "man page". In
-      these is a separate "man page". In the HTML format, each  is
+        the HTML format, each is a separate page, linked from the  index  page.
-      a  separate  page,  linked from the index page. In the plain
+        In  the  plain text format, all the sections are concatenated, for ease
-      text format, all the sections are concatenated, for ease  of
+        of searching. The sections are as follows:
-      searching. The sections are as follows:
+          pcre              this document
-        pcre              this document
+          pcreapi           details of PCRE's native C API
-        pcreapi           details of PCRE's native API
+          pcrebuild         options for building PCRE
-        pcrebuild         options for building PCRE
+          pcrecallout       details of the callout feature
-        pcrecallout       details of the callout feature
+          pcrecompat        discussion of Perl compatibility
-        pcrecompat        discussion of Perl compatibility
+          pcrecpp           details of the C++ wrapper
-        pcregrep          description of the pcregrep command
+          pcregrep          description of the pcregrep command
-        pcrepattern       syntax and semantics of supported
+          pcrematching      discussion of the two matching algorithms
-                            regular expressions
+          pcrepartial       details of the partial matching facility
-        pcreperform       discussion of performance issues
+          pcrepattern       syntax and semantics of supported
-        pcreposix         the POSIX-compatible API
+                              regular expressions
-        pcresample        discussion of the sample program
+          pcreperform       discussion of performance issues
-        pcretest          the pcretest testing command
+          pcreposix         the POSIX-compatible C API
+          pcreprecompile    details of saving and re-using precompiled patterns
-      In addition, in the "man" and HTML formats, there is a short
+          pcresample        discussion of the sample program
-      page  for  each  library function, listing its arguments and
+          pcretest          description of the pcretest testing command
-      results.
+        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
+        There are some size limitations in PCRE but it is hoped that they  will
-      they will never in practice be relevant.
+        never in practice be relevant.
-      The maximum length of a  compiled  pattern  is  65539  (sic)
+        The  maximum  length of a compiled pattern is 65539 (sic) bytes if PCRE
-      bytes  if PCRE is compiled with the default internal linkage
+        is compiled with the default internal linkage size of 2. If you want to
-      size of 2. If you want to process regular  expressions  that
+        process  regular  expressions  that are truly enormous, you can compile
-      are  truly  enormous,  you can compile PCRE with an internal
+        PCRE with an internal linkage size of 3 or 4 (see the  README  file  in
-      linkage size of 3 or 4 (see the README file  in  the  source
+        the  source  distribution and the pcrebuild documentation for details).
-      distribution  and  the pcrebuild documentation for details).
+        In these cases the limit is substantially larger.  However,  the  speed
-      If these cases the limit is substantially larger.   However,
+        of execution will be slower.
-      the speed of execution will be slower.
+        All values in repeating quantifiers must be less than 65536.  The maxi-
-      All values in repeating quantifiers must be less than 65536.
+        mum number of capturing subpatterns is 65535.
-      The maximum number of capturing subpatterns is 65535.
+        There is no limit to the number of non-capturing subpatterns,  but  the
-      There is no limit to the  number  of  non-capturing  subpat-
+        maximum  depth  of  nesting  of  all kinds of parenthesized subpattern,
-      terns,  but  the  maximum  depth  of nesting of all kinds of
+        including capturing subpatterns, assertions, and other types of subpat-
-      parenthesized subpattern, including  capturing  subpatterns,
+        tern, is 200.
-      assertions, and other types of subpattern, is 200.
+        The  maximum  length of a subject string is the largest positive number
-      The maximum length of a subject string is the largest  posi-
+        that an integer variable can hold. However, when using the  traditional
-      tive number that an integer variable can hold. However, PCRE
+        matching function, PCRE uses recursion to handle subpatterns and indef-
-      uses recursion to handle subpatterns and indefinite  repeti-
+        inite repetition.  This means that the available stack space may  limit
-      tion.  This  means  that the available stack space may limit
+        the size of a subject string that can be processed by certain patterns.
-      the size of a subject string that can be processed  by  cer-
-      tain patterns.
+ 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. When you do this, 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 in several places, so should
+        not be very large.
+        If PCRE is built with Unicode character property support (which implies
+        UTF-8  support),  the  escape sequences \p{..}, \P{..}, and \X are sup-
+        ported.  The available properties that can be tested are limited to the
+        general  category  properties such as Lu for an upper case letter or Nd
+        for a decimal number. A full list is given in the pcrepattern  documen-
+        tation. The PCRE library is increased in size by about 90K when Unicode
+        property support is included.
+        The following comments apply when PCRE is running in UTF-8 mode:
+. When you set the PCRE_UTF8 flag, the strings passed as patterns  and
+        subjects  are  checked for validity on entry to the relevant functions.
+        If an invalid UTF-8 string is passed, an error return 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 to PCRE  when
+        PCRE_NO_UTF8_CHECK  is set, the results are undefined. Your program may
+        crash.
+. In a pattern, the escape sequence \x{...}, where the contents of the
+        braces  is  a  string  of hexadecimal digits, is interpreted as a UTF-8
+        character whose code number is the given hexadecimal number, for  exam-
+        ple:  \x{1234}.  If a non-hexadecimal digit appears between the braces,
+        the item is not recognized.  This escape sequence can be used either as
+        a literal, or within a character class.
+.  The  original hexadecimal escape sequence, \xhh, matches a two-byte
+        UTF-8 character if the value is greater than 127.
+. 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}.
+.  Similarly,  characters that match the POSIX named character classes
+        are all low-valued characters.
+. Case-insensitive matching applies only to  characters  whose  values
+        are  less than 128, unless PCRE is built with Unicode property support.
+        Even when Unicode property support is available, PCRE  still  uses  its
+        own  character  tables when checking the case of low-valued characters,
+        so as not to degrade performance.  The Unicode property information  is
+        used only for characters with higher values.
- UTF-8 SUPPORT
+ AUTHOR
-      Starting at release 3.3, PCRE has had some support for char-
+        Philip Hazel
-      acter  strings  encoded in the UTF-8 format. For release 4.0
+        University Computing Service,
-      this has been greatly extended to cover most common require-
+        Cambridge CB2 3QG, England.
-      ments.
-      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.
-      When  you  do this, 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 addi-
-      tional run time overhead is limited to testing the PCRE_UTF8
-      flag in several places, so should not be very large.
-      The following comments apply when PCRE is running  in  UTF-8
-      mode:
-. PCRE assumes that the strings it is given  contain  valid
-      UTF-8  codes. It does not diagnose invalid UTF-8 strings. If
-      you pass invalid UTF-8 strings  to  PCRE,  the  results  are
-      undefined.
-. In a pattern, the escape sequence \x{...}, where the con-
-      tents  of  the  braces is a string of hexadecimal digits, is
-      interpreted as a UTF-8 character whose code  number  is  the
-      given  hexadecimal  number, for example: \x{1234}. If a non-
-      hexadecimal digit appears between the braces,  the  item  is
-      not  recognized.  This escape sequence can be used either as
-      a literal, or within a character class.
-. The original hexadecimal escape sequence, \xhh, matches a
-      two-byte UTF-8 character if the value is greater than 127.
-. Repeat quantifiers apply to  complete  UTF-8  characters,
-      not to individual bytes, for example: \x{100}{3}.
-. The dot metacharacter matches one UTF-8 character instead
-      of a single 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.
-. The character escapes \b, \B, \d, \D, \s, \S, \w, and  \W
-      correctly test characters of any code value, but the charac-
-      ters that PCRE recognizes as digits, spaces, or word charac-
-      ters  remain  the  same  set as before, all with values less
-      than 256.
-. Case-insensitive  matching  applies  only  to  characters
-      whose  values  are  less than 256. PCRE does not support the
-      notion of "case" for higher-valued characters.
-. PCRE does not support the use of Unicode tables and  pro-
+        Putting  an actual email address here seems to have been a spam magnet,
-      perties or the Perl escapes \p, \P, and \X.
+        so I've taken it away. If you want to email me, use my initial and sur-
+        name, separated by a dot, at the domain ucs.cam.ac.uk.
+ Last updated: 07 March 2005
+ Copyright (c) 1997-2005 University of Cambridge.
+ ------------------------------------------------------------------------------
- AUTHOR
-      Philip Hazel <ph10@cam.ac.uk>
+ PCREBUILD(3)                                                      PCREBUILD(3)
-      University Computing Service,
-      Cambridge CB2 3QG, England.
-      Phone: +44 1223 334714
- Last updated: 04 February 2003
- Copyright (c) 1997-2003 University of Cambridge.
- -----------------------------------------------------------------------------
  NAME
-      PCRE - Perl-compatible regular expressions
+        PCRE - Perl-compatible regular expressions
  PCRE BUILD-TIME OPTIONS
-      This document describes the optional features of  PCRE  that
+        This  document  describes  the  optional  features  of PCRE that can be
-      can  be  selected when the library is compiled. They are all
+        selected when the library is compiled. They are all selected, or  dese-
-      selected, or deselected, by providing options to the config-
+        lected, by providing options to the configure script that is run before
-      ure  script  which  is run before the make command. The com-
+        the make command. The complete list of  options  for  configure  (which
-      plete list of options  for  configure  (which  includes  the
+        includes  the  standard  ones such as the selection of the installation
-      standard  ones  such  as  the  selection of the installation
+        directory) can be obtained by running
-      directory) can be obtained by running
+          ./configure --help
-        ./configure --help
+        The following sections describe certain options whose names begin  with
-      The following sections describe certain options whose  names
+        --enable  or  --disable. These settings specify changes to the defaults
-      begin  with  --enable  or  --disable. These settings specify
+        for the configure command. Because of the  way  that  configure  works,
-      changes to the defaults for the configure  command.  Because
+        --enable  and  --disable  always  come  in  pairs, so the complementary
-      of  the  way  that  configure  works, --enable and --disable
+        option always exists as well, but as it specifies the  default,  it  is
-      always come in pairs, so  the  complementary  option  always
+        not described.
-      exists  as  well, but as it specifies the default, it is not
-      described.
  UTF-8 SUPPORT
-      To build PCRE with support for UTF-8 character strings, add
+        To build PCRE with support for UTF-8 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.
+ UNICODE CHARACTER PROPERTY SUPPORT
-        --enable-utf8
+        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
-      to the configure command. Of itself, this does not make PCRE
+          --enable-unicode-properties
-      treat  strings as UTF-8. As well as compiling PCRE with this
-      option, you also have have to set the PCRE_UTF8 option  when
+        to the configure command. This implies UTF-8 support, even if you  have
-      you call the pcre_compile() function.
+        not explicitly requested it.
+        Including  Unicode  property  support  adds around 90K of tables to the
+        PCRE library, approximately doubling its size. Only the  general  cate-
+        gory  properties  such as Lu and Nd are supported. Details are given in
+        the pcrepattern documentation.
  CODE VALUE OF NEWLINE
-      By default, PCRE treats character 10 (linefeed) as the  new-
+        By default, PCRE treats character 10 (linefeed) as the newline  charac-
-      line  character.  This  is  the  normal newline character on
+        ter. This is the normal newline character on Unix-like systems. You can
-      Unix-like systems. You can compile PCRE to use character  13
+        compile PCRE to use character 13 (carriage return) instead by adding
-      (carriage return) instead by adding
+          --enable-newline-is-cr
-        --enable-newline-is-cr
+        to the configure command. For completeness there is  also  a  --enable-
-      to the configure command. For completeness there is  also  a
+        newline-is-lf  option,  which explicitly specifies linefeed as the new-
-      --enable-newline-is-lf  option,  which  explicitly specifies
+        line character.
-      linefeed as the newline character.
  BUILDING SHARED AND STATIC LIBRARIES
-      The PCRE building process uses libtool to build both  shared
+        The PCRE building process uses libtool to build both shared and  static
-      and  static  Unix libraries by default. You can suppress one
+        Unix  libraries by default. You can suppress one of these by adding one
-      of these by adding one of
+        of
-        --disable-shared
+          --disable-shared
-        --disable-static
+          --disable-static
-      to the configure command, as required.
+        to the configure command, as required.
  POSIX MALLOC USAGE
-      When PCRE is called through the  POSIX  interface  (see  the
+        When PCRE is called through the POSIX interface (see the pcreposix doc-
-      pcreposix  documentation),  additional  working  storage  is
+        umentation),  additional  working  storage  is required for holding the
-      required for holding the pointers  to  capturing  substrings
+        pointers to capturing substrings, because PCRE requires three  integers
-      because  PCRE requires three integers per substring, whereas
+        per  substring,  whereas  the POSIX interface provides only two. If the
-      the POSIX interface provides only  two.  If  the  number  of
+        number of expected substrings is small, the wrapper function uses space
-      expected  substrings  is  small,  the  wrapper function uses
+        on the stack, because this is faster than using malloc() for each call.
-      space on the stack, because this is faster than  using  mal-
+        The default threshold above which the stack is no longer used is 10; it
-      loc()  for  each call. The default threshold above which the
+        can be changed by adding a setting such as
-      stack is no longer used is 10; it can be changed by adding a
-      setting such as
-        --with-posix-malloc-threshold=20
+          --with-posix-malloc-threshold=20
-      to the configure command.
+        to the configure command.
  LIMITING PCRE RESOURCE USAGE
-      Internally, PCRE has a  function  called  match()  which  it
+        Internally,  PCRE has a function called match(), which it calls repeat-
-      calls  repeatedly  (possibly  recursively) when performing a
+        edly  (possibly  recursively)  when  matching  a   pattern   with   the
-      matching operation. By limiting the  number  of  times  this
+        pcre_exec()  function.  By controlling the maximum number of times this
-      function  may  be  called,  a  limit  can  be  placed on the
+        function may be called during a single matching operation, a limit  can
-      resources used by a single call to  pcre_exec().  The  limit
+        be  placed  on  the resources used by a single call to pcre_exec(). The
-      can  be  changed  at  run  time, as described in the pcreapi
+        limit can be changed at run time, as described in the pcreapi  documen-
-      documentation. The default is 10 million, but  this  can  be
+        tation.  The default is 10 million, but this can be changed by adding a
-      changed by adding a setting such as
+        setting such as
-        --with-match-limit=500000
+          --with-match-limit=500000
-      to the configure command.
+        to  the  configure  command.  This  setting  has  no  effect   on   the
+        pcre_dfa_exec() matching function.
  HANDLING VERY LARGE PATTERNS
-      Within a compiled pattern, offset values are used  to  point
+        Within  a  compiled  pattern,  offset values are used to point from one
-      from  one  part  to  another  (for  example, from an opening
+        part to another (for example, from an opening parenthesis to an  alter-
-      parenthesis to an  alternation  metacharacter).  By  default
+        nation  metacharacter).  By default, two-byte values are used for these
-      two-byte  values  are  used  for these offsets, leading to a
+        offsets, leading to a maximum size for a  compiled  pattern  of  around
-      maximum size for a compiled pattern of around 64K.  This  is
+K.  This  is sufficient to handle all but the most gigantic patterns.
-      sufficient  to  handle  all  but the most gigantic patterns.
+        Nevertheless, some people do want to process enormous patterns,  so  it
-      Nevertheless, some people do want to process  enormous  pat-
+        is  possible  to compile PCRE to use three-byte or four-byte offsets by
-      terns,  so  it is possible to compile PCRE to use three-byte
+        adding a setting such as
-      or four-byte offsets by adding a setting such as
+          --with-link-size=3
-        --with-link-size=3
+        to the configure command. The value given must be 2,  3,  or  4.  Using
-      to the configure command. The value given must be 2,  3,  or
+        longer  offsets slows down the operation of PCRE because it has to load
-.  Using  longer  offsets  slows down the operation of PCRE
+        additional bytes when handling them.
-      because it has to load additional bytes when handling them.
+        If you build PCRE with an increased link size, test 2 (and  test  5  if
-      If you build PCRE with an increased link size, test  2  (and
+        you  are using UTF-8) will fail. Part of the output of these tests is a
-      test 5 if you are using UTF-8) will fail. Part of the output
+        representation of the compiled pattern, and this changes with the  link
-      of these tests is a representation of the compiled  pattern,
+        size.
-      and this changes with the link size.
+ 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.)  An alternative approach that uses memory
+        from the heap to remember data, instead  of  using  recursive  function
+        calls,  has been implemented to work round this problem. 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. Separate functions are provided 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 the
+        standard malloc() and  free()  functions.  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.
+ 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).
+        PCRE can, however, be compiled to  run  in  an  EBCDIC  environment  by
+        adding
+          --enable-ebcdic
+        to the configure command.
+ Last updated: 28 February 2005
+ Copyright (c) 1997-2005 University of Cambridge.
+ ------------------------------------------------------------------------------
+ PCREMATCHING(3)                                                PCREMATCHING(3)
- Last updated: 21 January 2003
- Copyright (c) 1997-2003 University of Cambridge.
- -----------------------------------------------------------------------------
  NAME
-      PCRE - Perl-compatible regular expressions
+        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.
- SYNOPSIS OF PCRE API
+        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.
-      #include <pcre.h>
+        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
-      pcre *pcre_compile(const char *pattern, int options,
+          ^<.*>
-           const char **errptr, int *erroffset,
-           const unsigned char *tableptr);
-      pcre_extra *pcre_study(const pcre *code, int options,
+        is matched against the string
-           const char **errptr);
-      int pcre_exec(const pcre *code, const pcre_extra *extra,
+          <something> <something else> <something further>
-           const char *subject, int length, int startoffset,
-           int options, int *ovector, int ovecsize);
-      int pcre_copy_named_substring(const pcre *code,
+        there are three possible answers. The standard algorithm finds only one
-           const char *subject, int *ovector,
+        of them, whereas the DFA algorithm finds all three.
-           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,
+ REGULAR EXPRESSIONS AS TREES
-           const char *subject, int *ovector,
-           int stringcount, const char *stringname,
-           const char **stringptr);
-      int pcre_get_stringnumber(const pcre *code,
+        The set of strings that are matched by a regular expression can be rep-
-           const char *name);
+        resented  as  a  tree structure. An unlimited repetition in the pattern
+        makes the tree of infinite size, but it is still a tree.  Matching  the
+        pattern  to a given subject string (from a given starting point) can be
+        thought of as a search of the tree.  There are  two  standard  ways  to
+        search  a  tree: depth-first and breadth-first, and these correspond to
+        the two matching algorithms provided by PCRE.
-      int pcre_get_substring(const char *subject, int *ovector,
-           int stringcount, int stringnumber,
-           const char **stringptr);
-      int pcre_get_substring_list(const char *subject,
+ THE STANDARD MATCHING ALGORITHM
-           int *ovector, int stringcount, const char ***listptr);
+        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 DFA MATCHING ALGORITHM
+        DFA stands for "deterministic finite automaton", but you do not need to
+        understand the origins of that name. This algorithm conducts a breadth-
+        first search of the tree. Starting from the first matching point in the
+        subject,  it scans the subject string from left to right, once, charac-
+        ter by character, and as it does  this,  it  remembers  all  the  paths
+        through the tree that represent valid matches.
+        The  scan  continues until either the end of the subject is reached, or
+        there are no more unterminated paths. At this point,  terminated  paths
+        represent  the different matching possibilities (if there are none, the
+        match has failed).  Thus, if there is more  than  one  possible  match,
+        this algorithm finds all of them, and in particular, it finds the long-
+        est. In PCRE, there is an option to stop the algorithm after the  first
+        match (which is necessarily the shortest) has been found.
+        Note that all the matches that are found start at the same point in the
+        subject. If the pattern
+          cat(er(pillar)?)
+        is matched against the string "the caterpillar catchment",  the  result
+        will  be the three strings "cat", "cater", and "caterpillar" that start
+        at the fourth character of the subject. The algorithm does not automat-
+        ically move on to find matches that start at later positions.
+        There are a number of features of PCRE regular expressions that are not
+        supported by the DFA matching algorithm. They are as follows:
+. Because the algorithm finds all  possible  matches,  the  greedy  or
+        ungreedy  nature  of repetition quantifiers is not relevant. Greedy and
+        ungreedy quantifiers are treated in exactly the same way.
+. When dealing with multiple paths through the tree simultaneously, it
+        is  not  straightforward  to  keep track of captured substrings for the
+        different matching possibilities, and  PCRE's  implementation  of  this
+        algorithm does not attempt to do this. This means that no captured sub-
+        strings are available.
+. Because no substrings are captured, back references within the  pat-
+        tern are not supported, and cause errors if encountered.
+.  For  the same reason, conditional expressions that use a backrefer-
+        ence as the condition are not supported.
+. Callouts are supported, but the value of the  capture_top  field  is
+        always 1, and the value of the capture_last field is always -1.
+.  The \C escape sequence, which (in the standard algorithm) matches a
+        single byte, even in UTF-8 mode, is not supported because the DFA algo-
+        rithm moves through the subject string one character at a time, for all
+        active paths through the tree.
+ ADVANTAGES OF THE DFA ALGORITHM
+        Using the DFA matching algorithm provides the following advantages:
+. All possible matches (at a single point in the subject) are automat-
+        ically  found,  and  in particular, the longest match is found. To find
+        more than one match using the standard algorithm, you have to do kludgy
+        things with callouts.
+.  There is much better support for partial matching. The restrictions
+        on the content of the pattern that apply when using the standard  algo-
+        rithm  for partial matching do not apply to the DFA algorithm. For non-
+        anchored patterns, the starting position of a partial match  is  avail-
+        able.
+.  Because  the  DFA algorithm scans the subject string just once, and
+        never needs to backtrack, it is possible  to  pass  very  long  subject
+        strings  to  the matching function in several pieces, checking for par-
+        tial matching each time.
+ DISADVANTAGES OF THE DFA ALGORITHM
+        The DFA algorithm suffers from a number of disadvantages:
+. It is substantially slower than  the  standard  algorithm.  This  is
+        partly  because  it has to search for all possible matches, but is also
+        because it is less susceptible to optimization.
+. Capturing parentheses and back references are not supported.
+. The "atomic group" feature of PCRE regular expressions is supported,
+        but  does not provide the advantage that it does for the standard algo-
+        rithm.
+ Last updated: 28 February 2005
+ Copyright (c) 1997-2005 University of Cambridge.
+ ------------------------------------------------------------------------------
+ PCREAPI(3)                                                          PCREAPI(3)
+ NAME
+        PCRE - Perl-compatible regular expressions
-      void pcre_free_substring(const char *stringptr);
-      void pcre_free_substring_list(const char **stringptr);
+ PCRE NATIVE API
-      const unsigned char *pcre_maketables(void);
+        #include <pcre.h>
-      int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
+        pcre *pcre_compile(const char *pattern, int options,
-           int what, void *where);
+             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);
-      int pcre_info(const pcre *code, int *optptr, *firstcharptr);
+        pcre_extra *pcre_study(const pcre *code, int options,
+             const char **errptr);
-      int pcre_config(int what, void *where);
+        int pcre_exec(const pcre *code, const pcre_extra *extra,
+             const char *subject, int length, int startoffset,
+             int options, int *ovector, int ovecsize);
-      char *pcre_version(void);
+        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);
-      void *(*pcre_malloc)(size_t);
+        int pcre_copy_named_substring(const pcre *code,
+             const char *subject, int *ovector,
+             int stringcount, const char *stringname,
+             char *buffer, int buffersize);
-      void (*pcre_free)(void *);
+        int pcre_copy_substring(const char *subject, int *ovector,
+             int stringcount, int stringnumber, char *buffer,
+             int buffersize);
-      int (*pcre_callout)(pcre_callout_block *);
+        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);
- PCRE API
+        int pcre_get_substring(const char *subject, int *ovector,
+             int stringcount, int stringnumber,
+             const char **stringptr);
-      PCRE has its own native API,  which  is  described  in  this
+        int pcre_get_substring_list(const char *subject,
-      document.  There  is  also  a  set of wrapper functions that
+             int *ovector, int stringcount, const char ***listptr);
-      correspond to the POSIX regular expression API.   These  are
-      described in the pcreposix documentation.
-      The native API function prototypes are defined in the header
+        void pcre_free_substring(const char *stringptr);
-      file  pcre.h,  and  on  Unix  systems  the library itself is
-      called libpcre.a, so can be accessed by adding -lpcre to the
-      command  for  linking  an  application  which  calls it. The
-      header file defines the macros PCRE_MAJOR and PCRE_MINOR  to
-      contain the major and minor release numbers for the library.
-      Applications can use these to include support for  different
-      releases.
-      The functions pcre_compile(), pcre_study(), and  pcre_exec()
+        void pcre_free_substring_list(const char **stringptr);
-      are  used  for compiling and matching regular expressions. A
-      sample program that demonstrates the simplest way  of  using
-      them  is  given in the file pcredemo.c. The pcresample docu-
-      mentation describes how to run it.
-      There are convenience functions for extracting captured sub-
+        const unsigned char *pcre_maketables(void);
-      strings from a matched subject string. They are:
-        pcre_copy_substring()
+        int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
-        pcre_copy_named_substring()
+             int what, void *where);
-        pcre_get_substring()
-        pcre_get_named_substring()
-        pcre_get_substring_list()
-      pcre_free_substring()  and  pcre_free_substring_list()   are
+        int pcre_info(const pcre *code, int *optptr, int *firstcharptr);
-      also  provided,  to  free  the  memory  used  for  extracted
-      strings.
-      The function pcre_maketables() is used (optionally) to build
+        int pcre_refcount(pcre *code, int adjust);
-      a  set of character tables in the current locale for passing
-      to pcre_compile().
-      The function pcre_fullinfo() is used to find out information
+        int pcre_config(int what, void *where);
-      about a compiled pattern; pcre_info() is an obsolete version
-      which returns only some of the available information, but is
-      retained   for   backwards   compatibility.    The  function
-      pcre_version() returns a pointer to a string containing  the
-      version of PCRE and its date of release.
-      The global variables  pcre_malloc  and  pcre_free  initially
+        char *pcre_version(void);
-      contain the entry points of the standard malloc() and free()
-      functions respectively. 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 variable pcre_callout initially contains NULL. It
+        void *(*pcre_malloc)(size_t);
-      can be set by the caller to a "callout" function, which PCRE
-      will then call at specified points during a matching  opera-
+        void (*pcre_free)(void *);
-      tion. Details are given in the pcrecallout documentation.
+        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
+        is also a set of 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
+        run it.
+        A second matching function, pcre_dfa_exec(), which is not Perl-compati-
+        ble,  is  also provided. This uses a different algorithm for the match-
+        ing. This allows it to find all possible matches (at a given  point  in
+        the  subject),  not  just  one. However, this algorithm does not return
+        captured substrings. A description of the two matching  algorithms  and
+        their  advantages  and disadvantages is given in the pcrematching docu-
+        mentation.
+        In addition to the main compiling and  matching  functions,  there  are
+        convenience functions for extracting captured substrings from a subject
+        string that is matched by pcre_exec(). They are:
+          pcre_copy_substring()
+          pcre_copy_named_substring()
+          pcre_get_substring()
+          pcre_get_named_substring()
+          pcre_get_substring_list()
+          pcre_get_stringnumber()
+        pcre_free_substring() and pcre_free_substring_list() are also provided,
+        to free the memory used for extracted strings.
+        The  function  pcre_maketables()  is  used  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. This is a non-standard way of building PCRE, for use in envi-
+        ronments 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.
+        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.
  MULTITHREADING
-      The PCRE functions can be used in  multi-threading  applica-
+        The  PCRE  functions  can be used in multi-threading applications, with
-      tions, with the proviso that the memory management functions
+        the  proviso  that  the  memory  management  functions  pointed  to  by
-      pointed to by pcre_malloc and  pcre_free,  and  the  callout
+        pcre_malloc, pcre_free, pcre_stack_malloc, and pcre_stack_free, and the
-      function  pointed  to  by  pcre_callout,  are  shared by all
+        callout function pointed to by pcre_callout, are shared by all threads.
-      threads.
+        The  compiled form of a regular expression is not altered during match-
-      The compiled form of a regular  expression  is  not  altered
+        ing, so the same compiled pattern can safely be used by several threads
-      during  matching, so the same compiled pattern can safely be
+        at once.
-      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.
  CHECKING BUILD-TIME OPTIONS
-      int pcre_config(int what, void *where);
+        int pcre_config(int what, void *where);
+        The function pcre_config() makes it possible for a PCRE client to  dis-
+        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.
-      The function pcre_config() makes  it  possible  for  a  PCRE
+          PCRE_CONFIG_UNICODE_PROPERTIES
-      client  to  discover  which optional features have been com-
-      piled into the PCRE library. The pcrebuild documentation has
-      more details about these optional features.
-      The first argument for pcre_config() is an integer, specify-
+        The  output  is  an  integer  that is set to one if support for Unicode
-      ing  which information is required; the second argument is a
+        character properties is available; otherwise it is set to zero.
-      pointer to a variable into which the information is  placed.
-      The following information is available:
-        PCRE_CONFIG_UTF8
+          PCRE_CONFIG_NEWLINE
-      The output is an integer that is set to one if UTF-8 support
+        The output is an integer that is set to the value of the code  that  is
-      is available; otherwise it is set to zero.
+        used  for the newline character. It is either linefeed (10) or carriage
+        return (13), and should normally be the  standard  character  for  your
+        operating system.
-        PCRE_CONFIG_NEWLINE
+          PCRE_CONFIG_LINK_SIZE
-      The output is an integer that is set to  the  value  of  the
+        The  output  is  an  integer that contains the number of bytes used for
-      code  that  is  used for the newline character. It is either
+        internal linkage in compiled regular expressions. The value is 2, 3, or
-      linefeed (10) or carriage return (13), and  should  normally
+.  Larger  values  allow larger regular expressions to be compiled, at
-      be the standard character for your operating system.
+        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_LINK_SIZE
+          PCRE_CONFIG_POSIX_MALLOC_THRESHOLD
-      The output is an integer that contains the number  of  bytes
+        The output is an integer that contains the threshold  above  which  the
-      used  for  internal linkage in compiled regular expressions.
+        POSIX  interface  uses malloc() for output vectors. Further details are
-      The value is 2, 3, or 4. Larger values allow larger  regular
+        given in the pcreposix documentation.
-      expressions  to be compiled, at the expense of slower match-
-      ing. 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
+          PCRE_CONFIG_MATCH_LIMIT
-      The output is an integer that contains the  threshold  above
+        The output is an integer that gives the default limit for the number of
-      which  the POSIX interface uses malloc() for output vectors.
+        internal  matching  function  calls in a pcre_exec() execution. Further
-      Further details are given in the pcreposix documentation.
+        details are given with pcre_exec() below.
-        PCRE_CONFIG_MATCH_LIMIT
+          PCRE_CONFIG_STACKRECURSE
-      The output is an integer that gives the  default  limit  for
+        The output is an integer that is set to one if internal recursion  when
-      the   number  of  internal  matching  function  calls  in  a
+        running pcre_exec() is implemented by recursive function calls that use
-      pcre_exec()  execution.  Further  details  are  given   with
+        the stack to remember their state. This is the usual way that  PCRE  is
-      pcre_exec() below.
+        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,
+        pcre *pcre_compile(const char *pattern, int options,
-           const char **errptr, int *erroffset,
+             const char **errptr, int *erroffset,
-           const unsigned char *tableptr);
+             const unsigned char *tableptr);
-      The function pcre_compile() is called to compile  a  pattern
+        pcre *pcre_compile2(const char *pattern, int options,
-      into  an internal form. The pattern is a C string terminated
+             int *errorcodeptr,
-      by a binary zero, and is passed in the argument  pattern.  A
+             const char **errptr, int *erroffset,
-      pointer  to  a  single  block of memory that is obtained via
+             const unsigned char *tableptr);
-      pcre_malloc is returned. This contains the compiled code and
-      related  data.  The  pcre  type  is defined for the returned
+        Either of the functions pcre_compile() or pcre_compile2() can be called
-      block; this is a typedef for a structure whose contents  are
+        to compile a pattern into an internal form. The only difference between
-      not  externally  defined. It is up to the caller to free the
+        the two interfaces is that pcre_compile2() has an additional  argument,
-      memory when it is no longer required.
+        errorcodeptr, via which a numerical error code can be returned.
-      Although the compiled code of a PCRE regex  is  relocatable,
+        The pattern is a C string terminated by a binary zero, and is passed in
-      that is, it does not depend on memory location, the complete
+        the pattern argument. A pointer to a single block  of  memory  that  is
-      pcre data block is not fully relocatable,  because  it  con-
+        obtained  via  pcre_malloc is returned. This contains the compiled code
-      tains  a  copy of the tableptr argument, which is an address
+        and related data. The pcre type is defined for the returned block; this
-      (see below).
+        is a typedef for a structure whose contents are not externally defined.
-      The options argument contains independent bits  that  affect
+        It is up to the caller  to  free  the  memory  when  it  is  no  longer
-      the  compilation.  It  should  be  zero  if  no  options are
+        required.
-      required. Some of the options, in particular, those that are
-      compatible  with Perl, can also be set and unset from within
+        Although  the compiled code of a PCRE regex is relocatable, that is, it
-      the pattern (see the detailed description of regular expres-
+        does not depend on memory location, the complete pcre data block is not
-      sions  in the pcrepattern documentation). For these options,
+        fully  relocatable, because it may contain a copy of the tableptr argu-
-      the contents of the options argument specifies their initial
+        ment, which is an address (see below).
-      settings  at  the  start  of  compilation and execution. The
-      PCRE_ANCHORED option can be set at the time of  matching  as
+        The options argument contains independent bits that affect the compila-
-      well as at compile time.
+        tion.  It  should  be  zero  if  no options are required. The available
+        options are described below. Some of them, in  particular,  those  that
-      If errptr is NULL, pcre_compile() returns NULL  immediately.
+        are  compatible  with  Perl,  can also be set and unset from within the
-      Otherwise, if compilation of a pattern fails, pcre_compile()
+        pattern (see the detailed description  in  the  pcrepattern  documenta-
-      returns NULL, and sets the variable pointed to by errptr  to
+        tion).  For  these options, the contents of the options argument speci-
-      point  to a textual error message. The offset from the start
+        fies their initial settings at the start of compilation and  execution.
-      of  the  pattern  to  the  character  where  the  error  was
+        The  PCRE_ANCHORED option can be set at the time of matching as well as
-      discovered   is   placed  in  the  variable  pointed  to  by
+        at compile time.
-      erroffset, which must not be NULL. If it  is,  an  immediate
-      error is given.
+        If errptr is NULL, pcre_compile() returns NULL immediately.  Otherwise,
+        if  compilation  of  a  pattern fails, pcre_compile() returns NULL, and
-      If the final  argument,  tableptr,  is  NULL,  PCRE  uses  a
+        sets the variable pointed to by errptr to point to a textual error mes-
-      default  set  of character tables which are built when it is
+        sage.  The  offset from the start of the pattern to the character where
-      compiled, using the default C  locale.  Otherwise,  tableptr
+        the error was discovered is  placed  in  the  variable  pointed  to  by
-      must  be  the result of a call to pcre_maketables(). See the
+        erroffset,  which  must  not  be  NULL. If it is, an immediate error is
-      section on locale support below.
+        given.
-      This code fragment shows a typical straightforward  call  to
+        If pcre_compile2() is used instead of pcre_compile(),  and  the  error-
-      pcre_compile():
+        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
-        pcre *re;
+        textual error message. Error codes and messages are listed below.
-        const char *error;
-        int erroffset;
+        If  the  final  argument, tableptr, is NULL, PCRE uses a default set of
-        re = pcre_compile(
+        character tables that are  built  when  PCRE  is  compiled,  using  the
-          "^A.*Z",          /* the pattern */
+        default  C  locale.  Otherwise, tableptr must be an address that is the
-,                /* default options */
+        result of a call to pcre_maketables(). This value is  stored  with  the
-          &error,           /* for error message */
+        compiled  pattern,  and used again by pcre_exec(), unless another table
-          &erroffset,       /* for error offset */
+        pointer is passed to it. For more discussion, see the section on locale
-          NULL);            /* use default character tables */
+        support below.
-      The following option bits are defined:
+        This  code  fragment  shows a typical straightforward call to pcre_com-
+        pile():
-        PCRE_ANCHORED
+          pcre *re;
-      If this bit is set, the pattern is forced to be  "anchored",
+          const char *error;
-      that is, it is constrained to match only at the first match-
+          int erroffset;
-      ing point in the string which is being searched  (the  "sub-
+          re = pcre_compile(
-      ject string"). This effect can also be achieved by appropri-
+            "^A.*Z",          /* the pattern */
-      ate constructs in the pattern itself, which is the only  way
+,                /* default options */
-      to do it in Perl.
+            &error,           /* for error message */
+            &erroffset,       /* for error offset */
-        PCRE_CASELESS
+            NULL);            /* use default character tables */
-      If this bit is set, letters in the pattern match both  upper
+        The following names for option bits are defined in  the  pcre.h  header
-      and  lower  case  letters.  It  is  equivalent  to Perl's /i
+        file:
-      option, and it can be changed within a  pattern  by  a  (?i)
-      option setting.
+          PCRE_ANCHORED
-        PCRE_DOLLAR_ENDONLY
+        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
-      If this bit is set, a dollar metacharacter  in  the  pattern
+        that  is being searched (the "subject string"). This effect can also be
-      matches  only at the end of the subject string. Without this
+        achieved by appropriate constructs in the pattern itself, which is  the
-      option, a dollar also matches immediately before  the  final
+        only way to do it in Perl.
-      character  if it is a newline (but not before any other new-
-      lines).  The  PCRE_DOLLAR_ENDONLY  option  is   ignored   if
+          PCRE_AUTO_CALLOUT
-      PCRE_MULTILINE is set. There is no equivalent to this option
-      in Perl, and no way to set it within a pattern.
+        If this bit is set, pcre_compile() automatically inserts callout items,
+        all with number 255, before each pattern item. For  discussion  of  the
-        PCRE_DOTALL
+        callout facility, see the pcrecallout documentation.
-      If this bit is  set,  a  dot  metacharater  in  the  pattern
+          PCRE_CASELESS
-      matches all characters, including newlines. Without it, new-
-      lines are excluded. This option is equivalent to  Perl's  /s
+        If  this  bit is set, letters in the pattern match both upper and lower
-      option,  and  it  can  be changed within a pattern by a (?s)
+        case letters. It is equivalent to Perl's  /i  option,  and  it  can  be
-      option setting. A negative class such as [^a] always matches
+        changed  within a pattern by a (?i) option setting. In UTF-8 mode, PCRE
-      a  newline  character,  independent  of  the setting of this
+        always understands the concept of case for characters whose values  are
-      option.
+        less  than 128, so caseless matching is always possible. For characters
+        with higher values, the concept of case is supported if  PCRE  is  com-
-        PCRE_EXTENDED
+        piled  with Unicode property support, but not otherwise. If you want to
+        use caseless matching for characters 128 and  above,  you  must  ensure
-      If this bit is set, whitespace data characters in  the  pat-
+        that  PCRE  is  compiled  with Unicode property support as well as with
-      tern  are  totally  ignored  except when escaped or inside a
+        UTF-8 support.
-      character class. Whitespace does not include the VT  charac-
-      ter  (code 11). In addition, characters between an unescaped
+          PCRE_DOLLAR_ENDONLY
-      # outside a character class and the next newline  character,
-      inclusive, are also ignored. This is equivalent to Perl's /x
+        If this bit is set, a dollar metacharacter in the pattern matches  only
-      option, and it can be changed within a  pattern  by  a  (?x)
+        at  the  end  of the subject string. Without this option, a dollar also
-      option setting.
+        matches immediately before the final character if it is a newline  (but
+        not  before  any  other  newlines).  The  PCRE_DOLLAR_ENDONLY option is
-      This option makes it possible  to  include  comments  inside
+        ignored if PCRE_MULTILINE is set. There is no equivalent to this option
-      complicated patterns.  Note, however, that this applies only
+        in Perl, and no way to set it within a pattern.
-      to data characters. Whitespace characters may  never  appear
-      within special character sequences in a pattern, for example
+          PCRE_DOTALL
-      within the sequence (?( which introduces a conditional  sub-
-      pattern.
+        If this bit is set, a dot metacharater in the pattern matches all char-
+        acters, including newlines. Without it,  newlines  are  excluded.  This
-        PCRE_EXTRA
+        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]
-      This option was invented in  order  to  turn  on  additional
+        always  matches a newline character, independent of the setting of this
-      functionality of PCRE that is incompatible with Perl, but it
+        option.
-      is currently of very little use. When set, any backslash  in
-      a  pattern  that is followed by a letter that has no special
+          PCRE_EXTENDED
-      meaning causes an error, thus reserving  these  combinations
-      for  future  expansion.  By default, as in Perl, a backslash
+        If this bit is set, whitespace  data  characters  in  the  pattern  are
-      followed by a letter with no special meaning is treated as a
+        totally ignored except when escaped or inside a character class. White-
-      literal.  There  are at present no other features controlled
+        space does not include the VT character (code 11). In addition, charac-
-      by this option. It can also be set by a (?X) option  setting
+        ters between an unescaped # outside a character class and the next new-
-      within a pattern.
+        line character, inclusive, are also  ignored.  This  is  equivalent  to
+        Perl's  /x  option,  and  it  can be changed within a pattern by a (?x)
-        PCRE_MULTILINE
+        option setting.
-      By default, PCRE treats the subject string as consisting  of
+        This option makes it possible to include  comments  inside  complicated
-      a  single "line" of characters (even if it actually contains
+        patterns.   Note,  however,  that this applies only to data characters.
-      several newlines). The "start  of  line"  metacharacter  (^)
+        Whitespace  characters  may  never  appear  within  special   character
-      matches  only  at the start of the string, while the "end of
+        sequences  in  a  pattern,  for  example  within the sequence (?( which
-      line" metacharacter ($) matches  only  at  the  end  of  the
+        introduces a conditional subpattern.
-      string,    or   before   a   terminating   newline   (unless
-      PCRE_DOLLAR_ENDONLY is set). This is the same as Perl.
+          PCRE_EXTRA
-      When PCRE_MULTILINE it is set, the "start of line" and  "end
+        This option was invented in order to turn on  additional  functionality
-      of  line"  constructs match immediately following or immedi-
+        of  PCRE  that  is  incompatible with Perl, but it is currently of very
-      ately before any newline  in  the  subject  string,  respec-
+        little use. When set, any backslash in a pattern that is followed by  a
-      tively,  as  well  as  at  the  very  start and end. This is
+        letter  that  has  no  special  meaning causes an error, thus reserving
-      equivalent to Perl's /m option, and it can be changed within
+        these combinations for future expansion. By  default,  as  in  Perl,  a
-      a  pattern  by  a  (?m) option setting. If there are no "\n"
+        backslash  followed by a letter with no special meaning is treated as a
-      characters in a subject string, or no occurrences of ^ or  $
+        literal. There are at present no  other  features  controlled  by  this
-      in a pattern, setting PCRE_MULTILINE has no effect.
+        option. It can also be set by a (?X) option setting within a pattern.
-        PCRE_NO_AUTO_CAPTURE
+          PCRE_FIRSTLINE
-      If this option is set, it disables the use of numbered  cap-
+        If  this  option  is  set,  an  unanchored pattern is required to match
-      turing  parentheses  in the pattern. Any opening parenthesis
+        before or at the first newline character in the subject string,  though
-      that is not followed by ? behaves as if it were followed  by
+        the matched text may continue over the newline.
-      ?:  but  named  parentheses  can still be used for capturing
-      (and they acquire numbers in the usual  way).  There  is  no
+          PCRE_MULTILINE
-      equivalent of this option in Perl.
+        By  default,  PCRE  treats the subject string as consisting of a single
-        PCRE_UNGREEDY
+        line of characters (even if it actually contains newlines). The  "start
+        of  line"  metacharacter  (^)  matches only at the start of the string,
-      This option inverts the "greediness" of the  quantifiers  so
+        while the "end of line" metacharacter ($) matches only at  the  end  of
-      that  they  are  not greedy by default, but become greedy if
+        the string, or before a terminating newline (unless PCRE_DOLLAR_ENDONLY
-      followed by "?". It is not compatible with Perl. It can also
+        is set). This is the same as Perl.
-      be set by a (?U) option setting within the pattern.
+        When PCRE_MULTILINE it is set, the "start of line" and  "end  of  line"
-        PCRE_UTF8
+        constructs  match  immediately following or immediately before any new-
+        line in the subject string, respectively, as well as at the very  start
-      This option causes PCRE to regard both the pattern  and  the
+        and  end. This is equivalent to Perl's /m option, and it can be changed
-      subject  as  strings  of UTF-8 characters instead of single-
+        within a pattern by a (?m) option setting. If there are no "\n" charac-
-      byte character strings. However, it  is  available  only  if
+        ters  in  a  subject  string, or no occurrences of ^ or $ in a pattern,
-      PCRE  has  been  built to include UTF-8 support. If not, the
+        setting PCRE_MULTILINE has no effect.
-      use of this option provokes an error. Details  of  how  this
-      option  changes  the behaviour of PCRE are given in the sec-
+          PCRE_NO_AUTO_CAPTURE
-      tion on UTF-8 support in the main pcre page.
+        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. 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 performance 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 check-
+        ing of subject strings.
+ COMPILATION ERROR CODES
+        The following table lists the error  codes  than  may  be  returned  by
+        pcre_compile2(),  along with the error messages that may be returned by
+        both compiling functions.
+ no error
+ \ at end of pattern
+ \c at end of pattern
+ unrecognized character follows \
+ numbers out of order in {} quantifier
+ number too big in {} quantifier
+ missing terminating ] for character class
+ invalid escape sequence in character class
+ range out of order in character class
+ nothing to repeat
+ operand of unlimited repeat could match the empty string
+ internal error: unexpected repeat
+ unrecognized character after (?
+ POSIX named classes are supported only within a class
+ missing )
+ reference to non-existent subpattern
+ erroffset passed as NULL
+ unknown option bit(s) set
+ missing ) after comment
+ parentheses nested too deeply
+ regular expression too large
+ failed to get memory
+ unmatched parentheses
+ internal error: code overflow
+ unrecognized character after (?<
+ lookbehind assertion is not fixed length
+ malformed number after (?(
+ conditional group contains more than two branches
+ assertion expected after (?(
+ (?R or (?digits must be followed by )
+ unknown POSIX class name
+ POSIX collating elements are not supported
+ this version of PCRE is not compiled with PCRE_UTF8 support
+ spare error
+ character value in \x{...} sequence is too large
+ invalid condition (?(0)
+ \C not allowed in lookbehind assertion
+ PCRE does not support \L, \l, \N, \U, or \u
+ number after (?C is > 255
+ closing ) for (?C expected
+ recursive call could loop indefinitely
+ unrecognized character after (?P
+ syntax error after (?P
+ two named groups have the same name
+ invalid UTF-8 string
+ support for \P, \p, and \X has not been compiled
+ malformed \P or \p sequence
+ unknown property name after \P or \p
  STUDYING A PATTERN
-      pcre_extra *pcre_study(const pcre *code, int options,
+        pcre_extra *pcre_study(const pcre *code, int options
-           const char **errptr);
+             const char **errptr);
-      When a pattern is going to be  used  several  times,  it  is
+        If a compiled pattern is going to be used several times,  it  is  worth
-      worth  spending  more time analyzing it in order to speed up
+        spending more time analyzing it in order to speed up the time taken for
-      the time taken for matching. The function pcre_study() takes
+        matching. The function pcre_study() takes a pointer to a compiled  pat-
-      a  pointer  to  a compiled pattern as its first argument. If
+        tern as its first argument. If studying the pattern produces additional
-      studing the pattern  produces  additional  information  that
+        information that will help speed up matching,  pcre_study()  returns  a
-      will  help speed up matching, pcre_study() returns a pointer
+        pointer  to a pcre_extra block, in which the study_data field points to
-      to a pcre_extra block, in which the study_data field  points
+        the results of the study.
-      to the results of the study.
+        The  returned  value  from  pcre_study()  can  be  passed  directly  to
-      The  returned  value  from  a  pcre_study()  can  be  passed
+        pcre_exec().  However,  a  pcre_extra  block also contains other fields
-      directly  to pcre_exec(). However, the pcre_extra block also
+        that can be set by the caller before the block  is  passed;  these  are
-      contains other fields that can be set by the  caller  before
+        described below in the section on matching a pattern.
-      the  block is passed; these are described below. If studying
-      the pattern does not  produce  any  additional  information,
+        If  studying  the  pattern  does not produce any additional information
-      pcre_study() returns NULL. In that circumstance, if the cal-
+        pcre_study() returns NULL. In that circumstance, if the calling program
-      ling program wants to pass  some  of  the  other  fields  to
+        wants  to  pass  any of the other fields to pcre_exec(), it must set up
-      pcre_exec(), it must set up its own pcre_extra block.
+        its own pcre_extra block.
-      The second argument contains option  bits.  At  present,  no
+        The second argument of pcre_study() contains option bits.  At  present,
-      options  are  defined  for  pcre_study(),  and this argument
+        no options are defined, and this argument should always be zero.
-      should always be zero.
+        The  third argument for pcre_study() is a pointer for an error message.
-      The third argument for pcre_study()  is  a  pointer  for  an
+        If studying succeeds (even if no data is  returned),  the  variable  it
-      error  message.  If  studying  succeeds  (even if no data is
+        points  to  is set to NULL. Otherwise it points to a textual error mes-
-      returned), the variable it points to is set to NULL.  Other-
+        sage. You should therefore test the error pointer for NULL after  call-
-      wise it points to a textual error message. You should there-
+        ing pcre_study(), to be sure that it has run successfully.
-      fore  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():
-      This is a typical call to pcre_study():
+          pcre_extra *pe;
+          pe = pcre_study(
-        pcre_extra *pe;
+            re,             /* result of pcre_compile() */
-        pe = pcre_study(
+,              /* no options exist */
-          re,             /* result of pcre_compile() */
+            &error);        /* set to NULL or points to a message */
-,              /* 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-
-      At present, studying a  pattern  is  useful  only  for  non-
+        ble starting bytes is created.
-      anchored  patterns  that do not have a single fixed starting
-      character. A  bitmap  of  possible  starting  characters  is
-      created.
  LOCALE SUPPORT
-      PCRE handles caseless matching, and determines whether char-
+        PCRE  handles  caseless matching, and determines whether characters are
-      acters  are  letters, digits, or whatever, by reference to a
+        letters digits, or whatever, by reference to a set of  tables,  indexed
-      set of tables. When running in UTF-8 mode, this applies only
+        by  character  value.  When running in UTF-8 mode, this applies only to
-      to characters with codes less than 256. The library contains
+        characters with codes less than 128. Higher-valued  codes  never  match
-      a default set of tables that is created  in  the  default  C
+        escapes  such  as  \w or \d, but can be tested with \p if PCRE is built
-      locale  when  PCRE  is compiled. This is used when the final
+        with Unicode character property support.
-      argument of pcre_compile() is NULL, and  is  sufficient  for
-      many applications.
+        An internal set of tables is created in the default C locale when  PCRE
+        is  built.  This  is  used when the final argument of pcre_compile() is
-      An alternative set of tables can, however, be supplied. Such
+        NULL, and is sufficient for many applications. An  alternative  set  of
-      tables  are built by calling the pcre_maketables() function,
+        tables  can,  however, be supplied. These may be created in a different
-      which has no arguments, in the relevant locale.  The  result
+        locale from the default. As more and more applications change to  using
-      can  then be passed to pcre_compile() as often as necessary.
+        Unicode, the need for this locale support is expected to die away.
-      For example, to build and use tables  that  are  appropriate
-      for  the French locale (where accented characters with codes
+        External  tables  are  built by calling the pcre_maketables() function,
-      greater than 128 are treated as letters), the following code
+        which has no arguments, in the relevant locale. The result can then  be
-      could be used:
+        passed  to  pcre_compile()  or  pcre_exec()  as often as necessary. For
+        example, to build and use tables that are appropriate  for  the  French
-        setlocale(LC_CTYPE, "fr");
+        locale  (where  accented  characters  with  values greater than 128 are
-        tables = pcre_maketables();
+        treated as letters), the following code could be used:
-        re = pcre_compile(..., tables);
+          setlocale(LC_CTYPE, "fr_FR");
-      The  tables  are  built  in  memory  that  is  obtained  via
+          tables = pcre_maketables();
-      pcre_malloc.  The  pointer that is passed to pcre_compile is
+          re = pcre_compile(..., tables);
-      saved with the compiled pattern, and  the  same  tables  are
-      used via this pointer by pcre_study() and pcre_exec(). Thus,
+        When pcre_maketables() runs, the tables are built  in  memory  that  is
-      for any single pattern, compilation, studying  and  matching
+        obtained  via  pcre_malloc. It is the caller's responsibility to ensure
-      all happen in the same locale, but different patterns can be
+        that the memory containing the tables remains available for as long  as
-      compiled in different locales. It is the caller's  responsi-
+        it is needed.
-      bility  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 pcre_fullinfo(const pcre *code, const pcre_extra *extra,
-           int what, void *where);
+             int what, void *where);
-      The pcre_fullinfo() function  returns  information  about  a
+        The  pcre_fullinfo() function returns information about a compiled pat-
-      compiled pattern. It replaces the obsolete pcre_info() func-
+        tern. It replaces the obsolete pcre_info() function, which is neverthe-
-      tion, which is nevertheless retained for backwards compabil-
+        less retained for backwards compability (and is documented below).
-      ity (and is documented below).
+        The  first  argument  for  pcre_fullinfo() is a pointer to the compiled
-      The first argument for pcre_fullinfo() is a pointer  to  the
+        pattern. The second argument is the result of pcre_study(), or NULL  if
-      compiled  pattern.  The  second  argument  is  the result of
+        the  pattern  was not studied. The third argument specifies which piece
-      pcre_study(), or NULL if the pattern was  not  studied.  The
+        of information is required, and the fourth argument is a pointer  to  a
-      third  argument  specifies  which  piece  of  information is
+        variable  to  receive  the  data. The yield of the function is zero for
-      required, and the fourth argument is a pointer to a variable
+        success, or one of the following negative numbers:
-      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_NULL       the argument code was NULL
+          PCRE_ERROR_BADMAGIC   the "magic number" was not found
-                              the argument where was NULL
+          PCRE_ERROR_BADOPTION  the value of what was invalid
-        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
-      Here is a typical call of  pcre_fullinfo(),  to  obtain  the
+        typical call of pcre_fullinfo(), to obtain the length of  the  compiled
-      length of the compiled pattern:
+        pattern:
-        int rc;
+          int rc;
-        unsigned long int length;
+          unsigned long int length;
-        rc = pcre_fullinfo(
+          rc = pcre_fullinfo(
-          re,               /* result of pcre_compile() */
+            re,               /* result of pcre_compile() */
-          pe,               /* result of pcre_study(), or NULL */
+            pe,               /* result of pcre_study(), or NULL */
-          PCRE_INFO_SIZE,   /* what is required */
+            PCRE_INFO_SIZE,   /* what is required */
-          &length);         /* where to put the data */
+            &length);         /* where to put the data */
-      The possible values for the third argument  are  defined  in
+        The  possible  values for the third argument are defined in pcre.h, and
-      pcre.h, and are as follows:
+        are as follows:
-        PCRE_INFO_BACKREFMAX
+          PCRE_INFO_BACKREFMAX
-      Return the number of the highest back reference in the  pat-
+        Return the number of the highest back reference  in  the  pattern.  The
-      tern.  The  fourth argument should point to an int variable.
+        fourth  argument  should  point to an int variable. Zero is returned if
-      Zero is returned if there are no back references.
+        there are no back references.
-        PCRE_INFO_CAPTURECOUNT
+          PCRE_INFO_CAPTURECOUNT
-      Return the number of capturing subpatterns in  the  pattern.
+        Return the number of capturing subpatterns in the pattern.  The  fourth
-      The fourth argument should point to an int variable.
+        argument should point to an int variable.
-        PCRE_INFO_FIRSTBYTE
+          PCRE_INFO_DEFAULT_TABLES
-      Return information about  the  first  byte  of  any  matched
+        Return  a pointer to the internal default character tables within PCRE.
-      string,  for a non-anchored pattern. (This option used to be
+        The fourth argument should point to an unsigned char *  variable.  This
-      called PCRE_INFO_FIRSTCHAR; the old name is still recognized
+        information call is provided for internal use by the pcre_study() func-
-      for backwards compatibility.)
+        tion. External callers can cause PCRE to use  its  internal  tables  by
+        passing a NULL table pointer.
-      If there is a fixed first byte, e.g. from a pattern such  as
-      (cat|cow|coyote),  it  is returned in the integer pointed to
+          PCRE_INFO_FIRSTBYTE
-      by where. Otherwise, if either
+        Return  information  about  the first byte of any matched string, for a
-      (a) the pattern was compiled with the PCRE_MULTILINE option,
+        non-anchored   pattern.   (This    option    used    to    be    called
-      and every branch starts with "^", or
+        PCRE_INFO_FIRSTCHAR;  the  old  name  is still recognized for backwards
+        compatibility.)
-      (b) every  branch  of  the  pattern  starts  with  ".*"  and
-      PCRE_DOTALL is not set (if it were set, the pattern would be
+        If there is a fixed first byte, for example, from  a  pattern  such  as
-      anchored),
+        (cat|cow|coyote),  it  is  returned in the integer pointed to by where.
+        Otherwise, if either
-      -1 is returned, indicating that the pattern matches only  at
-      the  start  of  a subject string or after any newline within
+        (a) the pattern was compiled with the PCRE_MULTILINE option, and  every
-      the string. Otherwise -2 is returned. For anchored patterns,
+        branch starts with "^", or
-      -2 is returned.
+        (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not
-        PCRE_INFO_FIRSTTABLE
+        set (if it were set, the pattern would be anchored),
-      If the pattern was studied, and this resulted  in  the  con-
+        -1 is returned, indicating that the pattern matches only at  the  start
-      struction of a 256-bit table indicating a fixed set of bytes
+        of  a  subject string or after any newline within the string. Otherwise
-      for the first byte in any matching string, a pointer to  the
+        -2 is returned. For anchored patterns, -2 is returned.
-      table  is  returned.  Otherwise NULL is returned. The fourth
-      argument should point to an unsigned char * variable.
+          PCRE_INFO_FIRSTTABLE
-        PCRE_INFO_LASTLITERAL
+        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
-      For a non-anchored pattern, return the value of  the  right-
+        matching string, a pointer to the table is returned. Otherwise NULL  is
-      most  literal  byte  which must exist in any matched string,
+        returned.  The fourth argument should point to an unsigned char * vari-
-      other than at its start. The fourth argument should point to
+        able.
-      an int variable. If there is no such byte, or if the pattern
-      is anchored, -1 is returned. For example,  for  the  pattern
+          PCRE_INFO_LASTLITERAL
-      /a\d+z\d+/ the returned value is 'z'.
+        Return the value of the rightmost literal byte that must exist  in  any
-        PCRE_INFO_NAMECOUNT
+        matched  string,  other  than  at  its  start,  if such a byte has been
-        PCRE_INFO_NAMEENTRYSIZE
+        recorded. The fourth argument should point to an int variable. If there
-        PCRE_INFO_NAMETABLE
+        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
-      PCRE supports the use of named as well as numbered capturing
+        example, for the pattern /^a\d+z\d+/ the returned value is "z", but for
-      parentheses. The names are just an additional way of identi-
+        /^a\dz\d/ the returned value is -1.
-      fying the parentheses,  which  still  acquire  a  number.  A
-      caller  that  wants  to extract data from a named subpattern
+          PCRE_INFO_NAMECOUNT
-      must convert the name to a number in  order  to  access  the
+          PCRE_INFO_NAMEENTRYSIZE
-      correct  pointers  in  the  output  vector  (described  with
+          PCRE_INFO_NAMETABLE
-      pcre_exec() below). In order to do this, it must  first  use
-      these  three  values  to  obtain  the name-to-number mapping
+        PCRE supports the use of named as well as numbered capturing  parenthe-
-      table for the pattern.
+        ses.  The names are just an additional way of identifying the parenthe-
+        ses,  which  still  acquire  numbers.  A  convenience  function  called
-      The  map  consists  of  a  number  of  fixed-size   entries.
+        pcre_get_named_substring()  is  provided  for  extracting an individual
-      PCRE_INFO_NAMECOUNT   gives   the  number  of  entries,  and
+        captured substring by name. It is also possible  to  extract  the  data
-      PCRE_INFO_NAMEENTRYSIZE gives the size of each  entry;  both
+        directly,  by  first converting the name to a number in order to access
-      of  these return an int value. The entry size depends on the
+        the correct pointers in the output vector (described  with  pcre_exec()
-      length of the longest name.  PCRE_INFO_NAMETABLE  returns  a
+        below).  To  do the conversion, you need to use the name-to-number map,
-      pointer to the first entry of the table (a pointer to char).
+        which is described by these three values.
-      The first two bytes of each entry are the number of the cap-
-      turing parenthesis, most significant byte first. The rest of
+        The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT
-      the entry is the corresponding name,  zero  terminated.  The
+        gives the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size
-      names  are  in alphabetical order. For example, consider the
+        of each entry; both of these  return  an  int  value.  The  entry  size
-      following pattern (assume PCRE_EXTENDED  is  set,  so  white
+        depends  on the length of the longest name. PCRE_INFO_NAMETABLE returns
-      space - including newlines - is ignored):
+        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-
-        (?P<date> (?P<year>(\d\d)?\d\d) -
+        sis, most significant byte first. The rest of the entry is  the  corre-
-        (?P<month>\d\d) - (?P<day>\d\d) )
+        sponding  name,  zero  terminated. The names are in alphabetical order.
+        For example, consider the following pattern  (assume  PCRE_EXTENDED  is
-      There are four named subpatterns,  so  the  table  has  four
+        set, so white space - including newlines - is ignored):
-      entries,  and  each  entry in the table is eight bytes long.
-      The table is as follows, with non-printing  bytes  shows  in
+          (?P<date> (?P<year>(\d\d)?\d\d) -
-      hex, and undefined bytes shown as ??:
+          (?P<month>\d\d) - (?P<day>\d\d) )
-01 d  a  t  e  00 ??
+        There  are  four  named subpatterns, so the table has four entries, and
-05 d  a  y  00 ?? ??
+        each entry in the table is eight bytes long. The table is  as  follows,
-04 m  o  n  t  h  00
+        with non-printing bytes shows in hexadecimal, and undefined bytes shown
-02 y  e  a  r  00 ??
+        as ??:
-      When writing code to extract data  from  named  subpatterns,
+01 d  a  t  e  00 ??
-      remember  that the length of each entry may be different for
+05 d  a  y  00 ?? ??
-      each compiled pattern.
+04 m  o  n  t  h  00
+02 y  e  a  r  00 ??
-        PCRE_INFO_OPTIONS
+        When writing code to extract data  from  named  subpatterns  using  the
-      Return a copy of the options with which the pattern was com-
+        name-to-number map, remember that the length of each entry is likely to
-      piled.  The fourth argument should point to an unsigned long
+        be different for each compiled pattern.
-      int variable. These option bits are those specified  in  the
-      call  to  pcre_compile(),  modified  by any top-level option
+          PCRE_INFO_OPTIONS
-      settings within the pattern itself.
+        Return a copy of the options with which the pattern was  compiled.  The
-      A pattern is automatically anchored by PCRE if  all  of  its
+        fourth  argument  should  point to an unsigned long int variable. These
-      top-level alternatives begin with one of the following:
+        option bits are those specified in the call to pcre_compile(), modified
+        by any top-level option settings within the pattern itself.
-        ^     unless PCRE_MULTILINE is set
-        \A    always
+        A  pattern  is  automatically  anchored by PCRE if all of its top-level
-        \G    always
+        alternatives begin with one of the following:
-        .*    if PCRE_DOTALL is set and there are no back
-                references to the subpattern in which .* appears
+          ^     unless PCRE_MULTILINE is set
+          \A    always
-      For such patterns, the  PCRE_ANCHORED  bit  is  set  in  the
+          \G    always
-      options returned by pcre_fullinfo().
+          .*    if PCRE_DOTALL is set and there are no back
+                  references to the subpattern in which .* appears
-        PCRE_INFO_SIZE
+        For such patterns, the PCRE_ANCHORED bit is set in the options returned
-      Return the size of the compiled pattern, that is, the  value
+        by pcre_fullinfo().
-      that  was  passed as the argument to pcre_malloc() when PCRE
-      was getting memory in which to place the compiled data.  The
+          PCRE_INFO_SIZE
-      fourth argument should point to a size_t variable.
+        Return  the  size  of the compiled pattern, that is, the value that was
-        PCRE_INFO_STUDYSIZE
+        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
-      Returns the size  of  the  data  block  pointed  to  by  the
+        size_t variable.
-      study_data  field  in a pcre_extra block. That is, it is the
-      value that was passed to pcre_malloc() when PCRE was getting
+          PCRE_INFO_STUDYSIZE
-      memory into which to place the data created by pcre_study().
-      The fourth argument should point to a size_t variable.
+        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, *firstcharptr);
+        int pcre_info(const pcre *code, int *optptr, int *firstcharptr);
-      The pcre_info() function is now obsolete because its  inter-
+        The pcre_info() function is now obsolete because its interface  is  too
-      face  is  too  restrictive  to return all the available data
+        restrictive  to return all the available data about a compiled pattern.
-      about  a  compiled  pattern.   New   programs   should   use
+        New  programs  should  use  pcre_fullinfo()  instead.  The   yield   of
-      pcre_fullinfo()  instead.  The  yield  of pcre_info() is the
+        pcre_info()  is the number of capturing subpatterns, or one of the fol-
-      number of capturing subpatterns, or  one  of  the  following
+        lowing negative numbers:
-      negative numbers:
+          PCRE_ERROR_NULL       the argument code was NULL
-        PCRE_ERROR_NULL       the argument code was NULL
+          PCRE_ERROR_BADMAGIC   the "magic number" was not found
-        PCRE_ERROR_BADMAGIC   the "magic number" was not found
+        If the optptr argument is not NULL, a copy of the  options  with  which
-      If the optptr argument is not NULL, a copy  of  the  options
+        the  pattern  was  compiled  is placed in the integer it points to (see
-      with which the pattern was compiled is placed in the integer
+        PCRE_INFO_OPTIONS above).
-      it points to (see PCRE_INFO_OPTIONS above).
+        If the pattern is not anchored and the  firstcharptr  argument  is  not
-      If the pattern is not anchored and the firstcharptr argument
+        NULL,  it is used to pass back information about the first character of
-      is  not  NULL, it is used to pass back information about the
+        any matched string (see PCRE_INFO_FIRSTBYTE above).
-      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 fields in a pcre_extra block are as fol-
+        lows:
+          unsigned long int flags;
+          void *study_data;
+          unsigned long int match_limit;
+          void *callout_data;
+          const unsigned char *tables;
+        The flags field is a bitmap that specifies which of  the  other  fields
+        are set. The flag bits are:
+          PCRE_EXTRA_STUDY_DATA
+          PCRE_EXTRA_MATCH_LIMIT
+          PCRE_EXTRA_CALLOUT_DATA
+          PCRE_EXTRA_TABLES
+        Other  flag  bits should be set to zero. The study_data field is set in
+        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 is imposed  on  the  number  of
+        times  this  function is called during a match, which has the effect of
+        limiting the amount of recursion and backtracking that can take  place.
+        For patterns that are not anchored, the count starts from zero for each
+        position in the subject string.
+        The default limit for the library can be set when PCRE  is  built;  the
+        default  default  is 10 million, which handles all but the most extreme
+        cases. You can reduce  the  default  by  suppling  pcre_exec()  with  a
+        pcre_extra  block  in  which match_limit is set to a smaller value, and
+        PCRE_EXTRA_MATCH_LIMIT is set in the  flags  field.  If  the  limit  is
+        exceeded, pcre_exec() returns PCRE_ERROR_MATCHLIMIT.
+        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_NOTBOL,
+        PCRE_NOTEOL, PCRE_NOTEMPTY, 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_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_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. If an invalid UTF-8 sequence
+        of bytes is found, pcre_exec() returns the error PCRE_ERROR_BADUTF8. If
+        startoffset  contains  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  length, and a starting byte offset in startoffset. In UTF-8
+        mode, the byte offset must point to the start  of  a  UTF-8  character.
+        Unlike  the  pattern string, the subject may contain binary zero bytes.
+        When the starting offset is zero, the search for a match starts at  the
+        beginning of the subject, and this is by far the most common case.
+        A  non-zero  starting offset is useful when searching for another match
+        in the same subject by calling pcre_exec() again after a previous  suc-
+        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 integer
+        offsets whose address is passed in ovector. The number of  elements  in
+        the  vector 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 length 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 a pair is set to the offset of the first character in a sub-
+        string,  and  the  second  is  set to the offset of the first character
+        after the end of a substring. The  first  pair,  ovector[0]  and  ovec-
+        tor[1],  identify  the  portion  of  the  subject string matched by the
+        entire pattern. The next pair is used for the first  capturing  subpat-
+        tern,  and  so  on.  The value returned by pcre_exec() is the number of
+        pairs that have been set. 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.
+        Some convenience functions are provided  for  extracting  the  captured
+        substrings  as  separate  strings. These are described in the following
+        section.
+        It is possible for an capturing subpattern number  n+1  to  match  some
+        part  of  the  subject  when subpattern n has not been used at all. For
+        example, if the string "abc" is matched against the pattern (a|(z))(bc)
+        subpatterns  1 and 3 are matched, but 2 is not. When this happens, both
+        offset values corresponding to the unused subpattern are set to -1.
+        If a capturing subpattern is matched repeatedly, it is the last portion
+        of the string that it matched that 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. In particular, if the substring off-
+        sets 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 usually advisable to supply an ovector.
+        Note that pcre_info() can be used to find out how many  capturing  sub-
+        patterns there are in a compiled pattern. The smallest size for ovector
+        that will allow for n captured substrings, in addition to  the  offsets
+        of the substring matched by the whole pattern, is (n+1)*3.
+    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_NODE   (-5)
+        While running the pattern match, an unknown item was encountered in the
+        compiled pattern. This error could be caused by a bug  in  PCRE  or  by
+        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  recursion  and 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)
- MATCHING A PATTERN
+        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)
-      int pcre_exec(const pcre *code, const pcre_extra *extra,
+        This error is given if the value of the ovecsize argument is  negative.
-           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 pre-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.
-      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 for substring information */
-);            /* number of elements in the vector */
-      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 additional information in
-      it. The fields in the block are as follows:
-        unsigned long int flags;
-        void *study_data;
-        unsigned long int match_limit;
-        void *callout_data;
-      The flags field is a bitmap  that  specifies  which  of  the
-      other fields are set. The flag bits are:
-        PCRE_EXTRA_STUDY_DATA
-        PCRE_EXTRA_MATCH_LIMIT
-        PCRE_EXTRA_CALLOUT_DATA
-      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 can add to the block
-      by setting the other fields.
-      The match_limit field provides a means  of  preventing  PCRE
-      from  using  up a vast amount of resources when running pat-
-      terns 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  repeatedly  (sometimes  recursively).  The  limit  is
-      imposed  on the number of times this function is called dur-
-      ing a match, which has the effect of limiting the amount  of
-      recursion and backtracking that can take place. For patterns
-      that are not anchored, the count starts from zero  for  each
-      position in the subject string.
-      The default limit for the library can be set  when  PCRE  is
-      built;  the default default is 10 million, which handles all
-      but the most extreme cases. You can reduce  the  default  by
-      suppling  pcre_exec()  with  a  pcre_extra  block  in  which
-      match_limit   is   set   to    a    smaller    value,    and
-      PCRE_EXTRA_MATCH_LIMIT  is  set  in  the flags field. If the
-      limit      is      exceeded,       pcre_exec()       returns
-      PCRE_ERROR_MATCHLIMIT.
-      The pcre_callout field is used in conjunction with the "cal-
-      lout"  feature,  which is described in the pcrecallout docu-
-      mentation.
-      The PCRE_ANCHORED option can be passed in the options  argu-
-      ment,   whose   unused   bits  must  be  zero.  This  limits
-      pcre_exec() to matching at the first matching position. How-
-      ever,  if  a  pattern  was  compiled  with PCRE_ANCHORED, or
-      turned out to be anchored by virtue of its contents, it can-
-      not be made unachored at matching time.
-      There are also three further options that can be set only at
-      matching time:
-        PCRE_NOTBOL
-      The first character of the 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.
-        PCRE_NOTEOL
-      The end of the string is not the end of a line, so the  dol-
-      lar  metacharacter should not match it nor (except in multi-
-      line mode) a newline immediately  before  it.  Setting  this
-      without PCRE_MULTILINE (at compile time) causes dollar never
-      to match.
-        PCRE_NOTEMPTY
-      An empty string is not considered to be  a  valid  match  if
-      this  option  is  set. If there are alternatives in the pat-
-      tern, 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 occurrences of "a" or "b".
-      Perl has no direct equivalent of PCRE_NOTEMPTY, but it  does
-      make  a  special case of a pattern match of the empty string
-      within its split() function, and when using the /g modifier.
-      It  is possible to emulate Perl's behaviour after matching a
-      null string by first trying the  match  again  at  the  same
-      offset  with  PCRE_NOTEMPTY  set,  and then if that fails by
-      advancing the starting offset  (see  below)  and  trying  an
-      ordinary match again.
-      The subject string is passed to pcre_exec() as a pointer  in
-      subject,  a length in length, and a starting offset in star-
-      toffset. 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.
-      If the pattern was compiled with the PCRE_UTF8  option,  the
-      subject  must  be  a sequence of bytes that is a valid UTF-8
-      string.  If  an  invalid  UTF-8  string  is  passed,  PCRE's
-      behaviour is not defined.
-      A non-zero starting offset  is  useful  when  searching  for
-      another  match  in  the  same subject by calling pcre_exec()
-      again after a previous success.  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  occurrence  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 tried.
-      This can only succeed if the pattern does  not  require  the
-      match to be at the start of the subject.
-      In general, a pattern matches a certain portion of the  sub-
-      ject,  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 substring.
-      PCRE supports several other kinds of  parenthesized  subpat-
-      tern that do not cause substrings to be captured.
-      Captured substrings are returned to the caller via a  vector
-      of  integer  offsets whose address is passed in ovector. The
-      number of elements in the vector is passed in ovecsize.  The
-      first two-thirds of the vector is used to pass back captured
-      substrings, each substring using a  pair  of  integers.  The
-      remaining  third  of  the  vector  is  used  as workspace by
-      pcre_exec() while matching capturing subpatterns, and is not
-      available for passing back information. The length passed in
-      ovecsize should always be a multiple of three. If it is not,
-      it is rounded down.
-      When a match has been successful, information about captured
-      substrings is returned in pairs of integers, starting at the
-      beginning of ovector, and continuing up to two-thirds of its
-      length  at  the  most. The first element of a pair is set to
-      the offset of the first character in a  substring,  and  the
-      second is set to the offset of the first character after the
-      end of a substring. The first  pair,  ovector[0]  and  ovec-
-      tor[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 the number of pairs that have  been  set.  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.
-      Some convenience functions are provided for  extracting  the
-      captured substrings as separate strings. These are described
-      in the following section.
-      It is possible for an capturing  subpattern  number  n+1  to
-      match  some  part  of  the subject when subpattern n has not
-      been used at all.  For  example,  if  the  string  "abc"  is
-      matched  against the pattern (a|(z))(bc) subpatterns 1 and 3
-      are matched, but 2 is not. When this  happens,  both  offset
-      values corresponding to the unused subpattern are set to -1.
-      If a capturing subpattern is matched repeatedly, it  is  the
-      last  portion  of  the  string  that  it  matched  that gets
-      returned.
-      If the vector is too small to hold  all  the  captured  sub-
-      strings,  it is used as far as possible (up to two-thirds of
-      its length), and the function returns a value  of  zero.  In
-      particular,  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 isn't big enough to remember  the
-      related  substrings,  PCRE  has to get additional memory for
-      use during matching. Thus it is usually advisable to  supply
-      an ovector.
-      Note that pcre_info() can be used to find out how many  cap-
-      turing  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.
-      If pcre_exec() fails, it returns a negative number. The fol-
-      lowing 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 com-
-      piled  code,  to  catch  the  case  when it is passed a junk
-      pointer. This is the error it gives when  the  magic  number
-      isn't present.
-        PCRE_ERROR_UNKNOWN_NODE   (-5)
-      While running the pattern match, an unknown item was encoun-
-      tered 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
-      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()  func-
-      tions (see below). It is never returned by pcre_exec().
-        PCRE_ERROR_MATCHLIMIT     (-8)
-      The recursion and 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.
  EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
-      int pcre_copy_substring(const char *subject, int *ovector,
+        int pcre_copy_substring(const char *subject, int *ovector,
-           int stringcount, int stringnumber, char *buffer,
+             int stringcount, int stringnumber, char *buffer,
-           int buffersize);
+             int buffersize);
-      int pcre_get_substring(const char *subject, int *ovector,
+        int pcre_get_substring(const char *subject, int *ovector,
-           int stringcount, int stringnumber,
+             int stringcount, int stringnumber,
-           const char **stringptr);
+             const char **stringptr);
-      int pcre_get_substring_list(const char *subject,
+        int pcre_get_substring_list(const char *subject,
-           int *ovector, int stringcount, const char ***listptr);
+             int *ovector, int stringcount, const char ***listptr);
+        Captured  substrings  can  be  accessed  directly  by using the offsets
-      Captured substrings can be accessed directly  by  using  the
+        returned by pcre_exec() in  ovector.  For  convenience,  the  functions
-      offsets returned by pcre_exec() in ovector. For convenience,
+        pcre_copy_substring(),    pcre_get_substring(),    and    pcre_get_sub-
-      the functions  pcre_copy_substring(),  pcre_get_substring(),
+        string_list() are provided for extracting captured substrings  as  new,
-      and  pcre_get_substring_list()  are  provided for extracting
+        separate,  zero-terminated strings. These functions identify substrings
-      captured  substrings  as  new,   separate,   zero-terminated
+        by number. The next section describes functions  for  extracting  named
-      strings.  These functions identify substrings by number. The
+        substrings.  A  substring  that  contains  a  binary  zero is correctly
-      next section describes functions for extracting  named  sub-
+        extracted and has a further zero added on the end, but  the  result  is
-      strings.   A  substring  that  contains  a  binary  zero  is
+        not, of course, a C string.
-      correctly extracted and has a further zero added on the end,
-      but the result is not, of course, a C string.
+        The  first  three  arguments  are the same for all three of these func-
+        tions: subject is the subject string that has  just  been  successfully
-      The first three arguments are the  same  for  all  three  of
+        matched, ovector is a pointer to the vector of integer offsets that was
-      these  functions:   subject  is the subject string which has
+        passed to pcre_exec(), and stringcount is the number of substrings that
-      just been successfully matched, ovector is a pointer to  the
+        were  captured  by  the match, including the substring that matched the
-      vector  of  integer  offsets that was passed to pcre_exec(),
+        entire regular expression. This is the value returned by pcre_exec() if
-      and stringcount is the number of substrings that  were  cap-
+        it  is greater than zero. If pcre_exec() returned zero, indicating that
-      tured by the match, including the substring that matched the
+        it ran out of space in ovector, the value passed as stringcount  should
-      entire regular expression. This is  the  value  returned  by
+        be the number of elements in the vector divided by three.
-      pcre_exec  if  it  is  greater  than  zero.  If  pcre_exec()
-      returned zero, indicating that it ran out of space in  ovec-
+        The  functions pcre_copy_substring() and pcre_get_substring() extract a
-      tor,  the  value passed as stringcount should be the size of
+        single substring, whose number is given as  stringnumber.  A  value  of
-      the vector divided by three.
+        zero  extracts  the  substring that matched the entire pattern, whereas
+        higher values  extract  the  captured  substrings.  For  pcre_copy_sub-
-      The functions pcre_copy_substring() and pcre_get_substring()
+        string(),  the  string  is  placed  in buffer, whose length is given by
-      extract a single substring, whose number is given as string-
+        buffersize, while for pcre_get_substring() a new  block  of  memory  is
-      number. A value of zero extracts the substring that  matched
+        obtained  via  pcre_malloc,  and its address is returned via stringptr.
-      the entire pattern, while higher values extract the captured
+        The yield of the function is the length of the  string,  not  including
-      substrings. For pcre_copy_substring(), the string is  placed
+        the terminating zero, or one of
-      in  buffer,  whose  length is given by buffersize, while for
-      pcre_get_substring() a new block of memory is  obtained  via
+          PCRE_ERROR_NOMEMORY       (-6)
-      pcre_malloc,  and its address is returned via stringptr. The
-      yield of the function is  the  length  of  the  string,  not
+        The  buffer  was too small for pcre_copy_substring(), or the attempt to
-      including the terminating zero, or one of
+        get memory failed for pcre_get_substring().
-        PCRE_ERROR_NOMEMORY       (-6)
+          PCRE_ERROR_NOSUBSTRING    (-7)
-      The buffer was too small for pcre_copy_substring(),  or  the
+        There is no substring whose number is stringnumber.
-      attempt to get memory failed for pcre_get_substring().
+        The pcre_get_substring_list()  function  extracts  all  available  sub-
-        PCRE_ERROR_NOSUBSTRING    (-7)
+        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
-      There is no substring whose number is stringnumber.
+        the  memory  block  is returned via listptr, which is also the start of
+        the list of string pointers. The end of the list is marked  by  a  NULL
-      The pcre_get_substring_list() function extracts  all  avail-
+        pointer. The yield of the function is zero if all went well, or
-      able  substrings  and builds a list of pointers to them. All
-      this is done in a single block of memory which  is  obtained
+          PCRE_ERROR_NOMEMORY       (-6)
-      via pcre_malloc. The address of the memory block is returned
-      via listptr, which is also the start of the list  of  string
+        if the attempt to get the memory block failed.
-      pointers.  The  end of the list is marked by a NULL pointer.
-      The yield of the function is zero if all went well, or
+        When  any of these functions encounter a substring that is unset, which
+        can happen when capturing subpattern number n+1 matches  some  part  of
-        PCRE_ERROR_NOMEMORY       (-6)
+        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-
-      if the attempt to get the memory block failed.
+        string  by inspecting the appropriate offset in ovector, which is nega-
+        tive for unset substrings.
-      When any of these functions encounter a  substring  that  is
-      unset, which can happen when capturing subpattern number n+1
+        The two convenience functions pcre_free_substring() and  pcre_free_sub-
-      matches some part of the subject, but subpattern n  has  not
+        string_list()  can  be  used  to free the memory returned by a previous
-      been  used  at all, they return an empty string. This can be
+        call  of  pcre_get_substring()  or  pcre_get_substring_list(),  respec-
-      distinguished  from  a  genuine  zero-length  substring   by
+        tively.  They  do  nothing  more  than  call the function pointed to by
-      inspecting the appropriate offset in ovector, which is nega-
+        pcre_free, which of course could be called directly from a  C  program.
-      tive for unset substrings.
+        However,  PCRE is used in some situations where it is linked via a spe-
+        cial  interface  to  another  programming  language  which  cannot  use
-      The  two  convenience  functions  pcre_free_substring()  and
+        pcre_free  directly;  it is for these cases that the functions are pro-
-      pcre_free_substring_list()  can  be  used to free the memory
+        vided.
-      returned by  a  previous  call  of  pcre_get_substring()  or
-      pcre_get_substring_list(),  respectively.  They  do  nothing
-      more than call the function pointed to by  pcre_free,  which
-      of  course  could  be called directly from a C program. How-
-      ever, PCRE is used in some situations where it is linked via
-      a  special  interface  to another programming language which
-      cannot use pcre_free directly; it is for  these  cases  that
-      the functions are provided.
  EXTRACTING CAPTURED SUBSTRINGS BY NAME
-      int pcre_copy_named_substring(const pcre *code,
+        int pcre_get_stringnumber(const pcre *code,
-           const char *subject, int *ovector,
+             const char *name);
-           int stringcount, const char *stringname,
-           char *buffer, int buffersize);
+        int pcre_copy_named_substring(const pcre *code,
+             const char *subject, int *ovector,
-      int pcre_get_stringnumber(const pcre *code,
+             int stringcount, const char *stringname,
-           const char *name);
+             char *buffer, int buffersize);
-      int pcre_get_named_substring(const pcre *code,
+        int pcre_get_named_substring(const pcre *code,
-           const char *subject, int *ovector,
+             const char *subject, int *ovector,
-           int stringcount, const char *stringname,
+             int stringcount, const char *stringname,
-           const char **stringptr);
+             const char **stringptr);
-      To extract a substring by name, you first have to find asso-
+        To extract a substring by name, you first have to find associated  num-
-      ciated    number.    This    can    be   done   by   calling
+        ber.  For example, for this pattern
-      pcre_get_stringnumber(). The first argument is the  compiled
-      pattern,  and  the second is the name. For example, for this
+          (a+)b(?P<xxx>\d+)...
-      pattern
+        the number of the subpattern called "xxx" is 2. You can find the number
-        ab(?<xxx>\d+)...
+        from the name by calling pcre_get_stringnumber(). The first argument is
+        the  compiled  pattern,  and  the  second is the name. The yield of the
-      the number of the subpattern called "xxx" is  1.  Given  the
+        function is the subpattern number, or  PCRE_ERROR_NOSUBSTRING  (-7)  if
-      number,  you can then extract the substring directly, or use
+        there is no subpattern of that name.
-      one of the functions described in the previous section.  For
-      convenience,  there are also two functions that do the whole
+        Given the number, you can extract the substring directly, or use one of
-      job.
+        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
+        Most    of    the    arguments   of   pcre_copy_named_substring()   and
-      functions that  extract  by  number,  and  so  are  not  re-
+        pcre_get_named_substring() are the same  as  those  for  the  similarly
-      described here. There are just two differences.
+        named  functions  that extract by number. As these are described in the
+        previous section, they are not re-described here. There  are  just  two
-      First, instead of a substring number, a  substring  name  is
+        differences:
-      given.  Second,  there  is  an  extra argument, given at the
-      start, which is a pointer to the compiled pattern.  This  is
+        First,  instead  of a substring number, a substring name is given. Sec-
-      needed  in order to gain access to the name-to-number trans-
+        ond, there is an extra argument, given at the start, which is a pointer
-      lation table.
+        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
+        These functions call pcre_get_stringnumber(), and if it succeeds,  they
-      pcre_get_substring(), as appropriate.
+        then  call  pcre_copy_substring() or pcre_get_substring(), as appropri-
+        ate.
+ FINDING ALL POSSIBLE MATCHES
+        The traditional matching function uses a  similar  algorithm  to  Perl,
+        which stops when it finds the first match, starting at a given point in
+        the subject. If you want to find all possible matches, or  the  longest
+        possible  match,  consider using the alternative matching function (see
+        below) instead. If you cannot use the alternative function,  but  still
+        need  to  find all possible matches, you can kludge it up by making use
+        of the callout facility, which is described in the pcrecallout documen-
+        tation.
+        What you have to do is to insert a callout right at the end of the pat-
+        tern.  When your callout function is called, extract and save the  cur-
+        rent  matched  substring.  Then  return  1, which forces pcre_exec() to
+        backtrack and try other alternatives. Ultimately, when it runs  out  of
+        matches, pcre_exec() will yield PCRE_ERROR_NOMATCH.
+ MATCHING A PATTERN: THE ALTERNATIVE FUNCTION
+        int pcre_dfa_exec(const pcre *code, const pcre_extra *extra,
+             const char *subject, int length, int startoffset,
+             int options, int *ovector, int ovecsize,
+             int *workspace, int wscount);
+        The  function  pcre_dfa_exec()  is  called  to  match  a subject string
+        against a compiled pattern, using a "DFA" matching algorithm. This  has
+        different  characteristics to the normal algorithm, and is not compati-
+        ble with Perl. Some of the features of PCRE patterns are not supported.
+        Nevertheless, there are times when this kind of matching can be useful.
+        For a discussion of the two matching algorithms, see  the  pcrematching
+        documentation.
+        The  arguments  for  the  pcre_dfa_exec()  function are the same as for
+        pcre_exec(), plus two extras. The ovector argument is used in a differ-
+        ent  way,  and  this is described below. The other common arguments are
+        used in the same way as for pcre_exec(), so their  description  is  not
+        repeated here.
+        The  two  additional  arguments provide workspace for the function. The
+        workspace vector should contain at least 20 elements. It  is  used  for
+        keeping  track  of  multiple  paths  through  the  pattern  tree.  More
+        workspace will be needed for patterns and subjects where  there  are  a
+        lot of possible matches.
+        Here is an example of a simple call to pcre_exec():
+          int rc;
+          int ovector[10];
+          int wspace[20];
+          rc = pcre_exec(
+            re,             /* result of pcre_compile() */
+            NULL,           /* we didn't study the pattern */
+            "some string",  /* the subject string */
+,             /* the length of the subject string */
+,              /* start at offset 0 in the subject */
+,              /* default options */
+            ovector,        /* vector of integers for substring information */
+,             /* number of elements (NOT size in bytes) */
+            wspace,         /* working space vector */
+);            /* number of elements (NOT size in bytes) */
+    Option bits for pcre_dfa_exec()
+        The  unused  bits  of  the options argument for pcre_dfa_exec() must be
+        zero. The only bits that may be  set  are  PCRE_ANCHORED,  PCRE_NOTBOL,
+        PCRE_NOTEOL,     PCRE_NOTEMPTY,    PCRE_NO_UTF8_CHECK,    PCRE_PARTIAL,
+        PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART. All  but  the  last  three  of
+        these  are  the  same  as  for pcre_exec(), so their description is not
+        repeated here.
+          PCRE_PARTIAL
+        This has the same general effect as it does for  pcre_exec(),  but  the
+        details   are   slightly   different.  When  PCRE_PARTIAL  is  set  for
+        pcre_dfa_exec(), the return code PCRE_ERROR_NOMATCH is  converted  into
+        PCRE_ERROR_PARTIAL  if  the  end  of the subject is reached, there have
+        been no complete matches, but there is still at least one matching pos-
+        sibility.  The portion of the string that provided the partial match is
+        set as the first matching string.
+          PCRE_DFA_SHORTEST
+        Setting the PCRE_DFA_SHORTEST option causes the matching  algorithm  to
+        stop  as  soon  as  it  has found one match. Because of the way the DFA
+        algorithm works, this is necessarily the shortest possible match at the
+        first possible matching point in the subject string.
+          PCRE_DFA_RESTART
+        When  pcre_dfa_exec()  is  called  with  the  PCRE_PARTIAL  option, and
+        returns a partial match, it is possible to call it  again,  with  addi-
+        tional  subject  characters,  and have it continue with the same match.
+        The PCRE_DFA_RESTART option requests this action; when it is  set,  the
+        workspace  and wscount options must reference the same vector as before
+        because data about the match so far is left in  them  after  a  partial
+        match.  There  is  more  discussion of this facility in the pcrepartial
+        documentation.
+    Successful returns from pcre_dfa_exec()
+        When pcre_dfa_exec() succeeds, it may have matched more than  one  sub-
+        string in the subject. Note, however, that all the matches from one run
+        of the function start at the same point in  the  subject.  The  shorter
+        matches  are all initial substrings of the longer matches. For example,
+        if the pattern
+          <.*>
+        is matched against the string
+          This is <something> <something else> <something further> no more
+        the three matched strings are
+          <something>
+          <something> <something else>
+          <something> <something else> <something further>
+        On success, the yield of the function is a number  greater  than  zero,
+        which  is  the  number of matched substrings. The substrings themselves
+        are returned in ovector. Each string uses two elements;  the  first  is
+        the  offset  to the start, and the second is the offset to the end. All
+        the strings have the same start offset. (Space could have been saved by
+        giving  this only once, but it was decided to retain some compatibility
+        with the way pcre_exec() returns data, even though the meaning  of  the
+        strings is different.)
+        The strings are returned in reverse order of length; that is, the long-
+        est matching string is given first. If there were too many  matches  to
+        fit  into ovector, the yield of the function is zero, and the vector is
+        filled with the longest matches.
+    Error returns from pcre_dfa_exec()
+        The pcre_dfa_exec() function returns a negative number when  it  fails.
+        Many  of  the  errors  are  the  same as for pcre_exec(), and these are
+        described above.  There are in addition the following errors  that  are
+        specific to pcre_dfa_exec():
+          PCRE_ERROR_DFA_UITEM      (-16)
+        This  return is given if pcre_dfa_exec() encounters an item in the pat-
+        tern that it does not support, for instance, the use of \C  or  a  back
+        reference.
+          PCRE_ERROR_DFA_UCOND      (-17)
+        This  return is given if pcre_dfa_exec() encounters a condition item in
+        a pattern that uses a back reference for the  condition.  This  is  not
+        supported.
+          PCRE_ERROR_DFA_UMLIMIT    (-18)
+        This  return  is given if pcre_dfa_exec() is called with an extra block
+        that contains a setting of the match_limit field. This is not supported
+        (it is meaningless).
+          PCRE_ERROR_DFA_WSSIZE     (-19)
+        This  return  is  given  if  pcre_dfa_exec()  runs  out of space in the
+        workspace vector.
+          PCRE_ERROR_DFA_RECURSE    (-20)
+        When a recursive subpattern is processed, the matching  function  calls
+        itself  recursively,  using  private vectors for ovector and workspace.
+        This error is given if the output vector  is  not  large  enough.  This
+        should be extremely rare, as a vector of size 1000 is used.
+ Last updated: 16 May 2005
+ Copyright (c) 1997-2005 University of Cambridge.
+ ------------------------------------------------------------------------------
+ PCRECALLOUT(3)                                                  PCRECALLOUT(3)
- Last updated: 03 February 2003
- Copyright (c) 1997-2003 University of Cambridge.
- -----------------------------------------------------------------------------
  NAME
-      PCRE - Perl-compatible regular expressions
+        PCRE - Perl-compatible regular expressions
  PCRE CALLOUTS
-      int (*pcre_callout)(pcre_callout_block *);
+        int (*pcre_callout)(pcre_callout_block *);
-      PCRE provides a feature called "callout", which is  a  means
-      of  temporarily 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 cal-
-      lout points can be identified by putting a number less  than
- after  the  letter  C.  The default value is zero.  For
-      example, this pattern has two callout points:
-        (?C1)9abc(?C2)def
-      During matching, when PCRE  reaches  a  callout  point  (and
-      pcre_callout  is  set), the external function is called. Its
-      only argument is a pointer to  a  pcre_callout  block.  This
-      contains the following variables:
-        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;
-      The version field  is  an  integer  containing  the  version
-      number of the block format. The current version is zero. The
-      version number may change 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 compiled into the pattern (that is, the number after ?C).
-      The offset_vector field  is  a  pointer  to  the  vector  of
-      offsets  that  was  passed by the caller to pcre_exec(). The
-      contents can be inspected in  order  to  extract  substrings
-      that  have  been  matched  so  far,  in  the same way as for
-      extracting substrings after a match has completed.
-      The subject and subject_length  fields  contain  copies  the
-      values that were passed to pcre_exec().
-      The start_match field contains the offset within the subject
-      at  which  the current match attempt started. If the pattern
-      is not anchored, the callout function may be called  several
-      times for different starting points.
-      The current_position field contains the  offset  within  the
-      subject of the current match pointer.
-      The capture_top field contains the  number  of  the  highest
-      captured substring so far.
-      The capture_last field  contains  the  number  of  the  most
-      recently captured substring.
-      The callout_data field contains a value that  is  passed  to
-      pcre_exec()  by  the  caller  specifically so that it can be
-      passed back in callouts. 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.
+        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)eabc(?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, callouts sometimes do not happen. For example, if the
+        pattern is
+          ab(?C4)cd
+        PCRE knows that any matching string must contain the letter "d". If the
+        subject string is "abyz", the lack of "d" means that  matching  doesn't
+        ever  start,  and  the  callout is never reached. However, with "abyd",
+        though the result is still no match, the callout is obeyed.
+ THE CALLOUT INTERFACE
+        During matching, when PCRE reaches a callout point, the external  func-
+        tion  defined by pcre_callout is called (if it is set). This applies to
+        both the pcre_exec() and the pcre_dfa_exec()  matching  functions.  The
+        only  argument  to  the callout function is a pointer to a pcre_callout
+        block. This structure contains the following fields:
+          int          version;
+          int          callout_number;
+          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 contains the offset within the subject  at  which
+        the  current match attempt started. 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 callout function returns an integer.  If  the  value  is
+        The external callout function returns an integer to PCRE. If the  value
-      zero,  matching  proceeds as normal. If the value is greater
+        is  zero,  matching  proceeds  as  normal. If the value is greater than
-      than zero, matching fails at the current  point,  but  back-
+        zero, matching fails at the current point, but  the  testing  of  other
-      tracking  to test other possibilities goes ahead, just as if
+        matching possibilities goes ahead, just as if a lookahead assertion had
-      a lookahead assertion had failed. If the value is less  than
+        failed. If the value is less than zero, the  match  is  abandoned,  and
-      zero,  the  match  is abandoned, and pcre_exec() returns the
+        pcre_exec() (or pcre_dfa_exec()) returns the negative value.
-      value.
+        Negative   values   should   normally   be   chosen  from  the  set  of
-      Negative values should normally be chosen from  the  set  of
+        PCRE_ERROR_xxx values. In particular, PCRE_ERROR_NOMATCH forces a stan-
-      PCRE_ERROR_xxx  values.  In  particular,  PCRE_ERROR_NOMATCH
+        dard  "no  match"  failure.   The  error  number  PCRE_ERROR_CALLOUT is
-      forces a standard "no  match"  failure.   The  error  number
+        reserved for use by callout functions; it will never be  used  by  PCRE
-      PCRE_ERROR_CALLOUT is reserved for use by callout functions;
+        itself.
-      it will never be used by PCRE itself.
+ Last updated: 28 February 2005
+ Copyright (c) 1997-2005 University of Cambridge.
+ ------------------------------------------------------------------------------
+ PCRECOMPAT(3)                                                    PCRECOMPAT(3)
- Last updated: 21 January 2003
- Copyright (c) 1997-2003 University of Cambridge.
- -----------------------------------------------------------------------------
  NAME
-      PCRE - Perl-compatible regular expressions
+        PCRE - Perl-compatible regular expressions
- DIFFERENCES FROM PERL
+ DIFFERENCES BETWEEN PCRE AND PERL
-      This document describes the differences  in  the  ways  that
+        This  document describes the differences in the ways that PCRE and Perl
-      PCRE  and  Perl  handle regular expressions. The differences
+        handle regular expressions. The differences  described  here  are  with
-      described here are with respect to Perl 5.8.
+        respect to Perl 5.8.
-. 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  looka-
-      head  assertions  are  counted,  but  their  entries  in the
-      offsets vector are never set. Perl sets its numerical  vari-
-      ables  from  any  such  patterns that are matched before the
-      assertion fails to match something (thereby succeeding), but
-      only  if  the negative lookahead assertion contains just one
-      branch.
-. Though binary zero characters are supported in  the  sub-
-      ject  string,  they  are  not  allowed  in  a pattern string
-      because it is passed as a normal  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,  \P, \p, and \X. In fact these are imple-
-      mented by Perl's general string-handling and are not part of
-      its pattern matching engine. If any of these are encountered
-      by PCRE, an error is generated.
-. PCRE does support the \Q...\E  escape  for  quoting  sub-
-      strings. Characters 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
-      In PCRE, the \Q...\E mechanism is not  recognized  inside  a
-      character class.
-. Fairly obviously, PCRE does not support the (?{code}) and
-      (?p{code})  constructions. However, there is some experimen-
-      tal support for recursive patterns using the non-Perl  items
-      (?R),  (?number)  and  (?P>name).  Also,  the PCRE "callout"
-      feature allows an external function to be called during pat-
-      tern matching.
-. 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  provides  some  extensions  to  the  Perl  regular
-      expression facilities:
-      (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 special meaning is faulted.
-      (d) If PCRE_UNGREEDY is set, the greediness of  the  repeti-
-      tion  quantifiers  is inverted, that is, by default they are
-      not greedy, but if followed by a question mark they are.
-      (e) PCRE_ANCHORED can be used 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_CAPTURE  options  for  pcre_exec() have no Perl
-      equivalents.
-      (g) The (?R), (?number), and (?P>name) constructs allows for
-      recursive  pattern  matching  (Perl  can  do  this using the
-      (?p{code}) construct, which PCRE cannot support.)
-      (h) PCRE supports  named  capturing  substrings,  using  the
-      Python syntax.
-      (i) PCRE supports the  possessive  quantifier  "++"  syntax,
-      taken from Sun's Java package.
-      (j) The (R) condition, for  testing  recursion,  is  a  PCRE
+.  PCRE does not have full UTF-8 support. Details of what it does have
-      extension.
+        are given in the section on UTF-8 support in the main pcre page.
-      (k) The callout facility is PCRE-specific.
+. 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.
+. 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 (?p{code})
+        constructions.  However,  there is support for recursive patterns using
+        the non-Perl items (?R),  (?number),  and  (?P>name).  Also,  the  PCRE
+        "callout"  feature allows an external function to be called during pat-
+        tern matching. See the pcrecallout documentation for details.
+. 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 provides some extensions to the Perl regular expression facil-
+        ities:
+        (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.
+        (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), (?number), and (?P>name) constructs allows for  recursive
+        pattern  matching  (Perl  can  do  this using the (?p{code}) construct,
+        which PCRE cannot support.)
+        (h) PCRE supports named capturing substrings, using the Python  syntax.
+        (i)  PCRE  supports  the  possessive quantifier "++" syntax, taken from
+        Sun's Java package.
+        (j) The (R) condition, for testing recursion, is a PCRE extension.
+        (k) The callout facility is PCRE-specific.
+        (l) The partial matching facility is PCRE-specific.
+        (m) Patterns compiled by PCRE can be saved and re-used at a later time,
+        even on different hosts that have the other endianness.
+        (n)  The  alternative  matching function (pcre_dfa_exec()) matches in a
+        different way and is not Perl-compatible.
+ Last updated: 28 February 2005
+ Copyright (c) 1997-2005 University of Cambridge.
+ ------------------------------------------------------------------------------
+ PCREPATTERN(3)                                                  PCREPATTERN(3)
- Last updated: 03 February 2003
- Copyright (c) 1997-2003 University of Cambridge.
- -----------------------------------------------------------------------------
  NAME
-      PCRE - Perl-compatible regular expressions
+        PCRE - Perl-compatible regular expressions
  PCRE REGULAR EXPRESSION DETAILS
-      The syntax and semantics of  the  regular  expressions  sup-
+        The  syntax  and semantics of the regular expressions supported by PCRE
-      ported  by PCRE are described below. Regular expressions are
+        are described below. Regular expressions are also described in the Perl
-      also described in the Perl documentation and in a number  of
+        documentation  and  in  a  number  of books, some of which have copious
-      other  books,  some  of which have copious examples. Jeffrey
+        examples.  Jeffrey Friedl's "Mastering Regular Expressions",  published
-      Friedl's  "Mastering  Regular  Expressions",  published   by
+        by  O'Reilly, covers regular expressions in great detail. This descrip-
-      O'Reilly,  covers them in great detail. The description here
+        tion of PCRE's regular expressions is intended as reference material.
-      is intended as reference documentation.
+        The original operation of PCRE was on strings of  one-byte  characters.
-      The basic operation of PCRE is on strings of bytes. However,
+        However,  there is now also support for UTF-8 character strings. To use
-      there  is  also  support for UTF-8 character strings. To use
+        this, you must build PCRE to  include  UTF-8  support,  and  then  call
-      this support you must build PCRE to include  UTF-8  support,
+        pcre_compile()  with  the  PCRE_UTF8  option.  How this affects pattern
-      and  then call pcre_compile() with the PCRE_UTF8 option. How
+        matching is mentioned in several places below. There is also a  summary
-      this affects the pattern matching is  mentioned  in  several
+        of  UTF-8  features  in  the  section on UTF-8 support in the main pcre
-      places  below.  There is also a summary of UTF-8 features in
+        page.
-      the section on UTF-8 support in the main pcre page.
+        The remainder of this document discusses the  patterns  that  are  sup-
-      A regular expression is a pattern that is matched against  a
+        ported  by  PCRE when its main matching function, pcre_exec(), is used.
-      subject string from left to right. Most characters stand for
+        From  release  6.0,   PCRE   offers   a   second   matching   function,
-      themselves in a pattern, and match the corresponding charac-
+        pcre_dfa_exec(),  which matches using a different algorithm that is not
-      ters in the subject. As a trivial example, the pattern
+        Perl-compatible. The advantages and disadvantages  of  the  alternative
+        function, and how it differs from the normal function, are discussed in
-        The quick brown fox
+        the pcrematching page.
-      matches a portion of a subject string that is  identical  to
+        A regular expression is a pattern that is  matched  against  a  subject
-      itself.  The  power  of  regular  expressions comes from the
+        string  from  left  to right. Most characters stand for themselves in a
-      ability to include alternatives and repetitions in the  pat-
+        pattern, and match the corresponding characters in the  subject.  As  a
-      tern.  These  are encoded in the pattern by the use of meta-
+        trivial example, the pattern
-      characters, which do not stand for  themselves  but  instead
-      are interpreted in some special way.
+          The quick brown fox
-      There are two different sets of meta-characters: those  that
+        matches a portion of a subject string that is identical to itself. When
-      are  recognized anywhere in the pattern except within square
+        caseless matching is specified (the PCRE_CASELESS option), letters  are
-      brackets, and those that are recognized in square  brackets.
+        matched  independently  of case. In UTF-8 mode, PCRE always understands
-      Outside square brackets, the meta-characters are as follows:
+        the concept of case for characters whose values are less than  128,  so
+        caseless  matching  is always possible. For characters with higher val-
-        \      general escape character with several uses
+        ues, the concept of case is supported if PCRE is compiled with  Unicode
-        ^      assert start of string (or line, in multiline mode)
+        property  support,  but  not  otherwise.   If  you want to use caseless
-        $      assert end of string (or line, in multiline mode)
+        matching for characters 128 and above, you must  ensure  that  PCRE  is
-        .      match any character except newline (by default)
+        compiled with Unicode property support as well as with UTF-8 support.
-        [      start character class definition
-        |      start of alternative branch
+        The  power  of  regular  expressions  comes from the ability to include
-        (      start subpattern
+        alternatives and repetitions in the pattern. These are encoded  in  the
-        )      end subpattern
+        pattern by the use of metacharacters, which do not stand for themselves
-        ?      extends the meaning of (
+        but instead are interpreted in some special way.
-               also 0 or 1 quantifier
-               also quantifier minimizer
+        There are two different sets of metacharacters: those that  are  recog-
-        *      0 or more quantifier
+        nized  anywhere in the pattern except within square brackets, and those
-        +      1 or more quantifier
+        that are recognized in square brackets. Outside  square  brackets,  the
-               also "possessive quantifier"
+        metacharacters are as follows:
-        {      start min/max quantifier
+          \      general escape character with several uses
-      Part of a pattern that is in square  brackets  is  called  a
+          ^      assert start of string (or line, in multiline mode)
-      "character  class".  In  a  character  class  the only meta-
+          $      assert end of string (or line, in multiline mode)
-      characters are:
+          .      match any character except newline (by default)
+          [      start character class definition
-        \      general escape character
+          |      start of alternative branch
-        ^      negate the class, but only if the first character
+          (      start subpattern
-        -      indicates character range
+          )      end subpattern
-        [      POSIX character class (only if followed by POSIX
+          ?      extends the meaning of (
-                 syntax)
+                 also 0 or 1 quantifier
-        ]      terminates the character class
+                 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
+        The following sections describe the use of each of the  metacharacters.
-      meta-characters.
  BACKSLASH
-      The backslash character has several uses. Firstly, if it  is
+        The backslash character has several uses. Firstly, if it is followed by
-      followed  by  a  non-alphameric character, it takes away any
+        a non-alphanumeric character, it takes away any  special  meaning  that
-      special  meaning  that  character  may  have.  This  use  of
+        character  may  have.  This  use  of  backslash  as an escape character
-      backslash  as  an  escape  character applies both inside and
+        applies both inside and outside character classes.
-      outside character classes.
+        For example, if you want to match a * character, you write  \*  in  the
-      For example, if you want to match a * character,  you  write
+        pattern.   This  escaping  action  applies whether or not the following
-      \*  in the pattern.  This escaping action applies whether or
+        character would otherwise be interpreted as a metacharacter, so  it  is
-      not the following character would otherwise  be  interpreted
+        always  safe  to  precede  a non-alphanumeric with backslash to specify
-      as  a meta-character, so it is always safe to precede a non-
+        that it stands for itself. In particular, if you want to match a  back-
-      alphameric with backslash to  specify  that  it  stands  for
+        slash, you write \\.
-      itself. In particular, if you want to match a backslash, 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
-      If a pattern is compiled with the PCRE_EXTENDED option, whi-
+        # outside a character class and the next newline character are ignored.
-      tespace in the pattern (other than in a character class) and
+        An escaping backslash can be used to include a whitespace or #  charac-
-      characters between a # outside a  character  class  and  the
+        ter as part of the pattern.
-      next  newline  character  are ignored. An escaping backslash
-      can be used to include a whitespace or # character  as  part
+        If  you  want  to remove the special meaning from a sequence of charac-
-      of the pattern.
+        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
-      If you want to remove the special meaning from a sequence of
+        sequences in PCRE, whereas in Perl, $ and @ cause  variable  interpola-
-      characters, you can do so by putting them between \Q and \E.
+        tion. Note the following examples:
-      This is different from Perl in that $ and @ are  handled  as
-      literals  in  \Q...\E  sequences in PCRE, whereas in Perl, $
+          Pattern            PCRE matches   Perl matches
-      and @ cause variable interpolation. Note the following exam-
-      ples:
+          \Qabc$xyz\E        abc$xyz        abc followed by the
+                                              contents of $xyz
-        Pattern            PCRE matches   Perl matches
+          \Qabc\$xyz\E       abc\$xyz       abc\$xyz
+          \Qabc\E\$\Qxyz\E   abc$xyz        abc$xyz
-        \Qabc$xyz\E        abc$xyz        abc followed by the
+        The  \Q...\E  sequence  is recognized both inside and outside character
-                                            contents of $xyz
+        classes.
-        \Qabc\$xyz\E       abc\$xyz       abc\$xyz
-        \Qabc\E\$\Qxyz\E   abc$xyz        abc$xyz
+    Non-printing characters
-      The \Q...\E sequence is recognized both inside  and  outside
+        A second use of backslash provides a way of encoding non-printing char-
-      character classes.
+        acters  in patterns in a visible manner. There is no restriction on the
+        appearance of non-printing characters, apart from the binary zero  that
-      A second use of backslash provides a way  of  encoding  non-
+        terminates  a  pattern,  but  when  a pattern is being prepared by text
-      printing  characters  in patterns in a visible manner. There
+        editing, it is usually easier  to  use  one  of  the  following  escape
-      is no restriction on the appearance of non-printing  charac-
+        sequences than the binary character it represents:
-      ters,  apart from the binary zero that terminates a pattern,
-      but when a pattern is being prepared by text editing, it  is
+          \a        alarm, that is, the BEL character (hex 07)
-      usually  easier to use one of the following escape sequences
+          \cx       "control-x", where x is any character
-      than the binary character it represents:
+          \e        escape (hex 1B)
+          \f        formfeed (hex 0C)
-        \a        alarm, that is, the BEL character (hex 07)
+          \n        newline (hex 0A)
-        \cx       "control-x", where x is any character
+          \r        carriage return (hex 0D)
-        \e        escape (hex 1B)
+          \t        tab (hex 09)
-        \f        formfeed (hex 0C)
+          \ddd      character with octal code ddd, or backreference
-        \n        newline (hex 0A)
+          \xhh      character with hex code hh
-        \r        carriage return (hex 0D)
+          \x{hhh..} character with hex code hhh... (UTF-8 mode only)
-        \t        tab (hex 09)
-        \ddd      character with octal code ddd, or backreference
+        The  precise  effect of \cx is as follows: if x is a lower case letter,
-        \xhh      character with hex code hh
+        it is converted to upper case. Then bit 6 of the character (hex 40)  is
-        \x{hhh..} character with hex code hhh... (UTF-8 mode only)
+        inverted.   Thus  \cz becomes hex 1A, but \c{ becomes hex 3B, while \c;
+        becomes hex 7B.
-      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
+        After \x, from zero to two hexadecimal digits are read (letters can  be
-      the character (hex 40) is inverted.  Thus  \cz  becomes  hex
+        in  upper or lower case). In UTF-8 mode, any number of hexadecimal dig-
-A, but \c{ becomes hex 3B, while \c; becomes hex 7B.
+        its may appear between \x{ and }, but the value of the  character  code
+        must  be  less  than  2**31  (that is, the maximum hexadecimal value is
-      After \x, from zero  to  two  hexadecimal  digits  are  read
+FFFFFFF). If characters other than hexadecimal digits  appear  between
-      (letters  can be in upper or lower case). In UTF-8 mode, any
+        \x{  and }, or if there is no terminating }, this form of escape is not
-      number of hexadecimal digits may appear between \x{  and  },
+        recognized. Instead, the initial \x will  be  interpreted  as  a  basic
-      but  the value of the character code must be less than 2**31
+        hexadecimal  escape, with no following digits, giving a character whose
-      (that is, the maximum hexadecimal  value  is  7FFFFFFF).  If
+        value is zero.
-      characters  other than hexadecimal digits appear between \x{
-      and }, or if there is no terminating }, this form of  escape
+        Characters whose value is less than 256 can be defined by either of the
-      is  not  recognized.  Instead, the initial \x will be inter-
+        two  syntaxes for \x when PCRE is in UTF-8 mode. There is no difference
-      preted as a basic  hexadecimal  escape,  with  no  following
+        in the way they are handled. For example, \xdc is exactly the  same  as
-      digits, giving a byte whose value is zero.
+        \x{dc}.
-      Characters whose value is less than 256 can  be  defined  by
+        After  \0  up  to  two further octal digits are read. In both cases, if
-      either  of  the  two  syntaxes  for \x when PCRE is in UTF-8
+        there are fewer than two digits, just those that are present are  used.
-      mode. There is no difference in the way  they  are  handled.
+        Thus  the sequence \0\x\07 specifies two binary zeros followed by a BEL
-      For example, \xdc is exactly the same as \x{dc}.
+        character (code value 7). Make sure you supply  two  digits  after  the
+        initial  zero  if the pattern character that follows is itself an octal
-      After \0 up to two further octal digits are  read.  In  both
+        digit.
-      cases,  if  there are fewer than two digits, just those that
-      are present are used. Thus the  sequence  \0\x\07  specifies
+        The handling of a backslash followed by a digit other than 0 is compli-
-      two binary zeros followed by a BEL character (code value 7).
+        cated.  Outside a character class, PCRE reads it and any following dig-
-      Make sure you supply two digits after the  initial  zero  if
+        its as a decimal number. If the number is less than  10,  or  if  there
-      the character that follows is itself an octal digit.
+        have been at least that many previous capturing left parentheses in the
+        expression, the entire  sequence  is  taken  as  a  back  reference.  A
-      The handling of a backslash followed by a digit other than 0
+        description  of how this works is given later, following the discussion
-      is  complicated.   Outside  a character class, PCRE reads it
+        of parenthesized subpatterns.
-      and any following digits as a decimal number. If the  number
-      is  less  than  10, or if there have been at least that many
+        Inside a character class, or if the decimal number is  greater  than  9
-      previous capturing left parentheses in the  expression,  the
+        and  there have not been that many capturing subpatterns, PCRE re-reads
-      entire  sequence is taken as a back reference. A description
+        up to three octal digits following the backslash, and generates a  sin-
-      of how this works is given later, following  the  discussion
+        gle byte from the least significant 8 bits of the value. Any subsequent
-      of parenthesized subpatterns.
+        digits stand for themselves.  For example:
-      Inside a character  class,  or  if  the  decimal  number  is
+          \040   is another way of writing a space
-      greater  than  9 and there have not been that many capturing
+          \40    is the same, provided there are fewer than 40
-      subpatterns, PCRE re-reads up to three octal digits  follow-
+                    previous capturing subpatterns
-      ing  the  backslash,  and  generates  a single byte from the
+          \7     is always a back reference
-      least significant 8 bits of the value. Any subsequent digits
+          \11    might be a back reference, or another way of
-      stand for themselves.  For example:
+                    writing a tab
+          \011   is always a tab
-        \040   is another way of writing a space
+          \0113  is a tab followed by the character "3"
-        \40    is the same, provided there are fewer than 40
+          \113   might be a back reference, otherwise the
-                  previous capturing subpatterns
+                    character with octal code 113
-        \7     is always a back reference
+          \377   might be a back reference, otherwise
-        \11    might be a back reference, or another way of
+                    the byte consisting entirely of 1 bits
-                  writing a tab
+          \81    is either a back reference, or a binary zero
-        \011   is always a tab
+                    followed by the two characters "8" and "1"
-        \0113  is a tab followed by the character "3"
-        \113   might be a back reference, otherwise the
+        Note that octal values of 100 or greater must not be  introduced  by  a
-                  character with octal code 113
+        leading zero, because no more than three octal digits are ever read.
-        \377   might be a back reference, otherwise
-                  the byte consisting entirely of 1 bits
+        All  the  sequences  that  define a single byte value or a single UTF-8
-        \81    is either a back reference, or a binary zero
+        character (in UTF-8 mode) can be used both inside and outside character
-                  followed by the two characters "8" and "1"
+        classes.  In  addition,  inside  a  character class, the sequence \b is
+        interpreted as the backspace character (hex 08), and the sequence \X is
-      Note that octal values of 100 or greater must not be  intro-
+        interpreted  as  the  character  "X".  Outside a character class, these
-      duced  by  a  leading zero, because no more than three octal
+        sequences have different meanings (see below).
-      digits are ever read.
+    Generic character types
-      All the sequences that define a single byte value or a  sin-
-      gle  UTF-8 character (in UTF-8 mode) can be used both inside
+        The third use of backslash is for specifying generic  character  types.
-      and outside character classes. In addition, inside a charac-
+        The following are always recognized:
-      ter  class,  the sequence \b is interpreted as the backspace
-      character (hex 08). Outside a character class it has a  dif-
+          \d     any decimal digit
-      ferent meaning (see below).
+          \D     any character that is not a decimal digit
+          \s     any whitespace character
-      The third use of backslash is for specifying generic charac-
+          \S     any character that is not a whitespace character
-      ter types:
+          \w     any "word" character
+          \W     any "non-word" character
-        \d     any decimal digit
-        \D     any character that is not a decimal digit
+        Each pair of escape sequences partitions the complete set of characters
-        \s     any whitespace character
+        into two disjoint sets. Any given character matches one, and only  one,
-        \S     any character that is not a whitespace character
+        of each pair.
-        \w     any "word" character
-        W     any "non-word" character
+        These character type sequences can appear both inside and outside char-
+        acter classes. They each match one character of the  appropriate  type.
-      Each pair of escape sequences partitions the complete set of
+        If  the current matching point is at the end of the subject string, all
-      characters  into  two  disjoint  sets.  Any  given character
+        of them fail, since there is no character to match.
-      matches one, and only one, of each pair.
+        For compatibility with Perl, \s does not match the VT  character  (code
-      In UTF-8 mode, characters with values greater than 255 never
+).   This makes it different from the the POSIX "space" class. The \s
-      match \d, \s, or \w, and always match \D, \S, and \W.
+        characters are HT (9), LF (10), FF (12), CR (13), and space (32).
-      For compatibility with Perl, \s does not match the VT  char-
+        A "word" character is an underscore or any character less than 256 that
-      acter (code 11).  This makes it different from the the POSIX
+        is  a  letter  or  digit.  The definition of letters and digits is con-
-      "space" class. The \s characters are HT  (9),  LF  (10),  FF
+        trolled by PCRE's low-valued character tables, and may vary if  locale-
-      (12), CR (13), and space (32).
+        specific  matching is taking place (see "Locale support" in the pcreapi
+        page). For example, in the  "fr_FR"  (French)  locale,  some  character
-      A "word" character is any letter or digit or the  underscore
+        codes  greater  than  128  are used for accented letters, and these are
-      character,  that  is,  any  character which can be part of a
+        matched by \w.
-      Perl "word". The definition of letters and  digits  is  con-
-      trolled  by PCRE's character tables, and may vary if locale-
+        In UTF-8 mode, characters with values greater than 128 never match  \d,
-      specific matching is taking place (see "Locale  support"  in
+        \s, or \w, and always match \D, \S, and \W. This is true even when Uni-
-      the pcreapi page). For example, in the "fr" (French) locale,
+        code character property support is available.
-      some character codes greater than 128 are used for  accented
-      letters, and these are matched by \w.
+    Unicode character properties
-      These character type sequences can appear  both  inside  and
+        When PCRE is built with Unicode character property support, three addi-
-      outside  character classes. They each match one character of
+        tional  escape sequences to match generic character types are available
-      the appropriate type. If the current matching  point  is  at
+        when UTF-8 mode is selected. They are:
-      the end of the subject string, all of them fail, since there
-      is no character to match.
+         \p{xx}   a character with the xx property
+         \P{xx}   a character without the xx property
-      The fourth use of backslash is  for  certain  simple  asser-
+         \X       an extended Unicode sequence
-      tions. An assertion specifies a condition that has to be met
-      at a particular point in  a  match,  without  consuming  any
+        The property names represented by xx above are limited to  the  Unicode
-      characters  from  the subject string. The use of subpatterns
+        general  category properties. Each character has exactly one such prop-
-      for more complicated  assertions  is  described  below.  The
+        erty, specified by a two-letter abbreviation.  For  compatibility  with
-      backslashed assertions are
+        Perl,  negation  can be specified by including a circumflex between the
+        opening brace and the property name. For example, \p{^Lu} is  the  same
-        \b     matches at a word boundary
+        as \P{Lu}.
-        \B     matches when not at a word boundary
-        \A     matches at start of subject
+        If  only  one  letter  is  specified with \p or \P, it includes all the
-        \Z     matches at end of subject or before newline at end
+        properties that start with that letter. In this case, in the absence of
-        \z     matches at end of subject
+        negation, the curly brackets in the escape sequence are optional; these
-        \G     matches at first matching position in subject
+        two examples have the same effect:
-      These assertions may not appear in  character  classes  (but
+          \p{L}
-      note  that  \b has a different meaning, namely the backspace
+          \pL
-      character, inside a character class).
+        The following property codes are supported: