ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 41 by nigel, Sat Feb 24 21:39:17 2007 UTC revision 406 by ph10, Mon Mar 23 12:05:43 2009 UTC
# Line 1  Line 1 
1    -----------------------------------------------------------------------------
2    This file contains a concatenation of the PCRE man pages, converted to plain
3    text format for ease of searching with a text editor, or for use on systems
4    that do not have a man page processor. The small individual files that give
5    synopses of each function in the library have not been included. There are
6    separate text files for the pcregrep and pcretest commands.
7    -----------------------------------------------------------------------------
10    PCRE(3)                                                                PCRE(3)
13    NAME
14           PCRE - Perl-compatible regular expressions
19           The  PCRE  library is a set of functions that implement regular expres-
20           sion pattern matching using the same syntax and semantics as Perl, with
21           just  a  few  differences. Certain features that appeared in Python and
22           PCRE before they appeared in Perl are also available using  the  Python
23           syntax.  There is also some support for certain .NET and Oniguruma syn-
24           tax items, and there is an option for  requesting  some  minor  changes
25           that give better JavaScript compatibility.
27           The  current  implementation of PCRE (release 7.x) corresponds approxi-
28           mately with Perl 5.10, including support for UTF-8 encoded strings  and
29           Unicode general category properties. However, UTF-8 and Unicode support
30           has to be explicitly enabled; it is not the default. The Unicode tables
31           correspond to Unicode release 5.0.0.
33           In  addition to the Perl-compatible matching function, PCRE contains an
34           alternative matching function that matches the same  compiled  patterns
35           in  a different way. In certain circumstances, the alternative function
36           has some advantages. For a discussion of the two  matching  algorithms,
37           see the pcrematching page.
39           PCRE  is  written  in C and released as a C library. A number of people
40           have written wrappers and interfaces of various kinds.  In  particular,
41           Google  Inc.   have  provided  a comprehensive C++ wrapper. This is now
42           included as part of the PCRE distribution. The pcrecpp page has details
43           of  this  interface.  Other  people's contributions can be found in the
44           Contrib directory at the primary FTP site, which is:
46           ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre
48           Details of exactly which Perl regular expression features are  and  are
49           not supported by PCRE are given in separate documents. See the pcrepat-
50           tern and pcrecompat pages. There is a syntax summary in the  pcresyntax
51           page.
53           Some  features  of  PCRE can be included, excluded, or changed when the
54           library is built. The pcre_config() function makes it  possible  for  a
55           client  to  discover  which  features are available. The features them-
56           selves are described in the pcrebuild page. Documentation about  build-
57           ing  PCRE for various operating systems can be found in the README file
58           in the source distribution.
60           The library contains a number of undocumented  internal  functions  and
61           data  tables  that  are  used by more than one of the exported external
62           functions, but which are not intended  for  use  by  external  callers.
63           Their  names  all begin with "_pcre_", which hopefully will not provoke
64           any name clashes. In some environments, it is possible to control which
65           external  symbols  are  exported when a shared library is built, and in
66           these cases the undocumented symbols are not exported.
71           The user documentation for PCRE comprises a number  of  different  sec-
72           tions.  In the "man" format, each of these is a separate "man page". In
73           the HTML format, each is a separate page, linked from the  index  page.
74           In  the  plain text format, all the sections are concatenated, for ease
75           of searching. The sections are as follows:
77             pcre              this document
78             pcre-config       show PCRE installation configuration information
79             pcreapi           details of PCRE's native C API
80             pcrebuild         options for building PCRE
81             pcrecallout       details of the callout feature
82             pcrecompat        discussion of Perl compatibility
83             pcrecpp           details of the C++ wrapper
84             pcregrep          description of the pcregrep command
85             pcrematching      discussion of the two matching algorithms
86             pcrepartial       details of the partial matching facility
87             pcrepattern       syntax and semantics of supported
88                                 regular expressions
89             pcresyntax        quick syntax reference
90             pcreperform       discussion of performance issues
91             pcreposix         the POSIX-compatible C API
92             pcreprecompile    details of saving and re-using precompiled patterns
93             pcresample        discussion of the sample program
94             pcrestack         discussion of stack usage
95             pcretest          description of the pcretest testing command
97           In addition, in the "man" and HTML formats, there is a short  page  for
98           each C library function, listing its arguments and results.
103           There  are some size limitations in PCRE but it is hoped that they will
104           never in practice be relevant.
106           The maximum length of a compiled pattern is 65539 (sic) bytes  if  PCRE
107           is compiled with the default internal linkage size of 2. If you want to
108           process regular expressions that are truly enormous,  you  can  compile
109           PCRE  with  an  internal linkage size of 3 or 4 (see the README file in
110           the source distribution and the pcrebuild documentation  for  details).
111           In  these  cases the limit is substantially larger.  However, the speed
112           of execution is slower.
114           All values in repeating quantifiers must be less than 65536.
116           There is no limit to the number of parenthesized subpatterns, but there
117           can be no more than 65535 capturing subpatterns.
119           The maximum length of name for a named subpattern is 32 characters, and
120           the maximum number of named subpatterns is 10000.
122           The maximum length of a subject string is the largest  positive  number
123           that  an integer variable can hold. However, when using the traditional
124           matching function, PCRE uses recursion to handle subpatterns and indef-
125           inite  repetition.  This means that the available stack space may limit
126           the size of a subject string that can be processed by certain patterns.
127           For a discussion of stack issues, see the pcrestack documentation.
132           From  release  3.3,  PCRE  has  had  some support for character strings
133           encoded in the UTF-8 format. For release 4.0 this was greatly  extended
134           to  cover  most common requirements, and in release 5.0 additional sup-
135           port for Unicode general category properties was added.
137           In order process UTF-8 strings, you must build PCRE  to  include  UTF-8
138           support  in  the  code,  and, in addition, you must call pcre_compile()
139           with the PCRE_UTF8 option flag. When you do this, both the pattern  and
140           any  subject  strings  that are matched against it are treated as UTF-8
141           strings instead of just strings of bytes.
143           If you compile PCRE with UTF-8 support, but do not use it at run  time,
144           the  library will be a bit bigger, but the additional run time overhead
145           is limited to testing the PCRE_UTF8 flag occasionally, so should not be
146           very big.
148           If PCRE is built with Unicode character property support (which implies
149           UTF-8 support), the escape sequences \p{..}, \P{..}, and  \X  are  sup-
150           ported.  The available properties that can be tested are limited to the
151           general category properties such as Lu for an upper case letter  or  Nd
152           for  a  decimal number, the Unicode script names such as Arabic or Han,
153           and the derived properties Any and L&. A full  list  is  given  in  the
154           pcrepattern documentation. Only the short names for properties are sup-
155           ported. For example, \p{L} matches a letter. Its Perl synonym,  \p{Let-
156           ter},  is  not  supported.   Furthermore,  in Perl, many properties may
157           optionally be prefixed by "Is", for compatibility with Perl  5.6.  PCRE
158           does not support this.
160       Validity of UTF-8 strings
162           When  you  set  the  PCRE_UTF8 flag, the strings passed as patterns and
163           subjects are (by default) checked for validity on entry to the relevant
164           functions.  From  release 7.3 of PCRE, the check is according the rules
165           of RFC 3629, which are themselves derived from the  Unicode  specifica-
166           tion.  Earlier  releases  of PCRE followed the rules of RFC 2279, which
167           allows the full range of 31-bit values (0 to 0x7FFFFFFF).  The  current
168           check allows only values in the range U+0 to U+10FFFF, excluding U+D800
169           to U+DFFF.
171           The excluded code points are the "Low Surrogate Area"  of  Unicode,  of
172           which  the Unicode Standard says this: "The Low Surrogate Area does not
173           contain any  character  assignments,  consequently  no  character  code
174           charts or namelists are provided for this area. Surrogates are reserved
175           for use with UTF-16 and then must be used in pairs."  The  code  points
176           that  are  encoded  by  UTF-16  pairs are available as independent code
177           points in the UTF-8 encoding. (In  other  words,  the  whole  surrogate
178           thing is a fudge for UTF-16 which unfortunately messes up UTF-8.)
180           If  an  invalid  UTF-8  string  is  passed  to  PCRE,  an  error return
181           (PCRE_ERROR_BADUTF8) is given. In some situations, you may already know
182           that your strings are valid, and therefore want to skip these checks in
183           order to improve performance. If you set the PCRE_NO_UTF8_CHECK flag at
184           compile  time  or at run time, PCRE assumes that the pattern or subject
185           it is given (respectively) contains only valid  UTF-8  codes.  In  this
186           case, it does not diagnose an invalid UTF-8 string.
188           If  you  pass  an  invalid UTF-8 string when PCRE_NO_UTF8_CHECK is set,
189           what happens depends on why the string is invalid. If the  string  con-
190           forms to the "old" definition of UTF-8 (RFC 2279), it is processed as a
191           string of characters in the range 0  to  0x7FFFFFFF.  In  other  words,
192           apart from the initial validity test, PCRE (when in UTF-8 mode) handles
193           strings according to the more liberal rules of RFC  2279.  However,  if
194           the  string does not even conform to RFC 2279, the result is undefined.
195           Your program may crash.
197           If you want to process strings  of  values  in  the  full  range  0  to
198           0x7FFFFFFF,  encoded in a UTF-8-like manner as per the old RFC, you can
199           set PCRE_NO_UTF8_CHECK to bypass the more restrictive test. However, in
200           this situation, you will have to apply your own validity check.
202       General comments about UTF-8 mode
204           1.  An  unbraced  hexadecimal  escape sequence (such as \xb3) matches a
205           two-byte UTF-8 character if the value is greater than 127.
207           2. Octal numbers up to \777 are recognized, and  match  two-byte  UTF-8
208           characters for values greater than \177.
210           3.  Repeat quantifiers apply to complete UTF-8 characters, not to indi-
211           vidual bytes, for example: \x{100}{3}.
213           4. The dot metacharacter matches one UTF-8 character instead of a  sin-
214           gle byte.
216           5.  The  escape sequence \C can be used to match a single byte in UTF-8
217           mode, but its use can lead to some strange effects.  This  facility  is
218           not available in the alternative matching function, pcre_dfa_exec().
220           6.  The  character escapes \b, \B, \d, \D, \s, \S, \w, and \W correctly
221           test characters of any code value, but the characters that PCRE  recog-
222           nizes  as  digits,  spaces,  or  word characters remain the same set as
223           before, all with values less than 256. This remains true even when PCRE
224           includes  Unicode  property support, because to do otherwise would slow
225           down PCRE in many common cases. If you really want to test for a  wider
226           sense  of,  say,  "digit",  you must use Unicode property tests such as
227           \p{Nd}. Note that this also applies to \b, because  it  is  defined  in
228           terms of \w and \W.
230           7.  Similarly,  characters that match the POSIX named character classes
231           are all low-valued characters.
233           8. However, the Perl 5.10 horizontal and vertical  whitespace  matching
234           escapes (\h, \H, \v, and \V) do match all the appropriate Unicode char-
235           acters.
237           9. Case-insensitive matching applies only to  characters  whose  values
238           are  less than 128, unless PCRE is built with Unicode property support.
239           Even when Unicode property support is available, PCRE  still  uses  its
240           own  character  tables when checking the case of low-valued characters,
241           so as not to degrade performance.  The Unicode property information  is
242           used only for characters with higher values. Even when Unicode property
243           support is available, PCRE supports case-insensitive matching only when
244           there  is  a  one-to-one  mapping between a letter's cases. There are a
245           small number of many-to-one mappings in Unicode;  these  are  not  sup-
246           ported by PCRE.
249    AUTHOR
251           Philip Hazel
252           University Computing Service
253           Cambridge CB2 3QH, England.
255           Putting  an actual email address here seems to have been a spam magnet,
256           so I've taken it away. If you want to email me, use  my  two  initials,
257           followed by the two digits 10, at the domain cam.ac.uk.
262           Last updated: 18 March 2009
263           Copyright (c) 1997-2009 University of Cambridge.
264    ------------------------------------------------------------------------------
267    PCREBUILD(3)                                                      PCREBUILD(3)
270    NAME
271           PCRE - Perl-compatible regular expressions
276           This  document  describes  the  optional  features  of PCRE that can be
277           selected when the library is compiled. It assumes use of the  configure
278           script,  where the optional features are selected or deselected by pro-
279           viding options to configure before running the make  command.  However,
280           the  same  options  can be selected in both Unix-like and non-Unix-like
281           environments using the GUI facility of  CMakeSetup  if  you  are  using
282           CMake instead of configure to build PCRE.
284           The complete list of options for configure (which includes the standard
285           ones such as the  selection  of  the  installation  directory)  can  be
286           obtained by running
288             ./configure --help
290           The  following  sections  include  descriptions  of options whose names
291           begin with --enable or --disable. These settings specify changes to the
292           defaults  for  the configure command. Because of the way that configure
293           works, --enable and --disable always come in pairs, so  the  complemen-
294           tary  option always exists as well, but as it specifies the default, it
295           is not described.
298    C++ SUPPORT
300           By default, the configure script will search for a C++ compiler and C++
301           header files. If it finds them, it automatically builds the C++ wrapper
302           library for PCRE. You can disable this by adding
304             --disable-cpp
306           to the configure command.
309    UTF-8 SUPPORT
311           To build PCRE with support for UTF-8 Unicode character strings, add
313             --enable-utf8
315           to the configure command. Of itself, this  does  not  make  PCRE  treat
316           strings  as UTF-8. As well as compiling PCRE with this option, you also
317           have have to set the PCRE_UTF8 option when you call the  pcre_compile()
318           function.
320           If  you set --enable-utf8 when compiling in an EBCDIC environment, PCRE
321           expects its input to be either ASCII or UTF-8 (depending on the runtime
322           option).  It  is not possible to support both EBCDIC and UTF-8 codes in
323           the same  version  of  the  library.  Consequently,  --enable-utf8  and
324           --enable-ebcdic are mutually exclusive.
329           UTF-8  support allows PCRE to process character values greater than 255
330           in the strings that it handles. On its own, however, it does  not  pro-
331           vide any facilities for accessing the properties of such characters. If
332           you want to be able to use the pattern escapes \P, \p,  and  \X,  which
333           refer to Unicode character properties, you must add
335             --enable-unicode-properties
337           to  the configure command. This implies UTF-8 support, even if you have
338           not explicitly requested it.
340           Including Unicode property support adds around 30K  of  tables  to  the
341           PCRE  library.  Only  the general category properties such as Lu and Nd
342           are supported. Details are given in the pcrepattern documentation.
347           By default, PCRE interprets the linefeed (LF) character  as  indicating
348           the  end  of  a line. This is the normal newline character on Unix-like
349           systems. You can compile PCRE to use carriage return (CR)  instead,  by
350           adding
352             --enable-newline-is-cr
354           to  the  configure  command.  There  is  also  a --enable-newline-is-lf
355           option, which explicitly specifies linefeed as the newline character.
357           Alternatively, you can specify that line endings are to be indicated by
358           the two character sequence CRLF. If you want this, add
360             --enable-newline-is-crlf
362           to the configure command. There is a fourth option, specified by
364             --enable-newline-is-anycrlf
366           which  causes  PCRE  to recognize any of the three sequences CR, LF, or
367           CRLF as indicating a line ending. Finally, a fifth option, specified by
369             --enable-newline-is-any
371           causes PCRE to recognize any Unicode newline sequence.
373           Whatever line ending convention is selected when PCRE is built  can  be
374           overridden  when  the library functions are called. At build time it is
375           conventional to use the standard for your operating system.
380           By default, the sequence \R in a pattern matches  any  Unicode  newline
381           sequence,  whatever  has  been selected as the line ending sequence. If
382           you specify
384             --enable-bsr-anycrlf
386           the default is changed so that \R matches only CR, LF, or  CRLF.  What-
387           ever  is selected when PCRE is built can be overridden when the library
388           functions are called.
393           The PCRE building process uses libtool to build both shared and  static
394           Unix  libraries by default. You can suppress one of these by adding one
395           of
397             --disable-shared
398             --disable-static
400           to the configure command, as required.
405           When PCRE is called through the POSIX interface (see the pcreposix doc-
406           umentation),  additional  working  storage  is required for holding the
407           pointers to capturing substrings, because PCRE requires three  integers
408           per  substring,  whereas  the POSIX interface provides only two. If the
409           number of expected substrings is small, the wrapper function uses space
410           on the stack, because this is faster than using malloc() for each call.
411           The default threshold above which the stack is no longer used is 10; it
412           can be changed by adding a setting such as
414             --with-posix-malloc-threshold=20
416           to the configure command.
421           Within  a  compiled  pattern,  offset values are used to point from one
422           part to another (for example, from an opening parenthesis to an  alter-
423           nation  metacharacter).  By default, two-byte values are used for these
424           offsets, leading to a maximum size for a  compiled  pattern  of  around
425           64K.  This  is sufficient to handle all but the most gigantic patterns.
426           Nevertheless, some people do want to process enormous patterns,  so  it
427           is  possible  to compile PCRE to use three-byte or four-byte offsets by
428           adding a setting such as
430             --with-link-size=3
432           to the configure command. The value given must be 2,  3,  or  4.  Using
433           longer  offsets slows down the operation of PCRE because it has to load
434           additional bytes when handling them.
439           When matching with the pcre_exec() function, PCRE implements backtrack-
440           ing  by  making recursive calls to an internal function called match().
441           In environments where the size of the stack is limited,  this  can  se-
442           verely  limit  PCRE's operation. (The Unix environment does not usually
443           suffer from this problem, but it may sometimes be necessary to increase
444           the  maximum  stack size.  There is a discussion in the pcrestack docu-
445           mentation.) An alternative approach to recursion that uses memory  from
446           the  heap  to remember data, instead of using recursive function calls,
447           has been implemented to work round the problem of limited  stack  size.
448           If you want to build a version of PCRE that works this way, add
450             --disable-stack-for-recursion
452           to  the  configure  command. With this configuration, PCRE will use the
453           pcre_stack_malloc and pcre_stack_free variables to call memory  manage-
454           ment  functions. By default these point to malloc() and free(), but you
455           can replace the pointers so that your own functions are used.
457           Separate functions are  provided  rather  than  using  pcre_malloc  and
458           pcre_free  because  the  usage  is  very  predictable:  the block sizes
459           requested are always the same, and  the  blocks  are  always  freed  in
460           reverse  order.  A calling program might be able to implement optimized
461           functions that perform better  than  malloc()  and  free().  PCRE  runs
462           noticeably more slowly when built in this way. This option affects only
463           the  pcre_exec()  function;  it   is   not   relevant   for   the   the
464           pcre_dfa_exec() function.
469           Internally,  PCRE has a function called match(), which it calls repeat-
470           edly  (sometimes  recursively)  when  matching  a  pattern   with   the
471           pcre_exec()  function.  By controlling the maximum number of times this
472           function may be called during a single matching operation, a limit  can
473           be  placed  on  the resources used by a single call to pcre_exec(). The
474           limit can be changed at run time, as described in the pcreapi  documen-
475           tation.  The default is 10 million, but this can be changed by adding a
476           setting such as
478             --with-match-limit=500000
480           to  the  configure  command.  This  setting  has  no  effect   on   the
481           pcre_dfa_exec() matching function.
483           In  some  environments  it is desirable to limit the depth of recursive
484           calls of match() more strictly than the total number of calls, in order
485           to  restrict  the maximum amount of stack (or heap, if --disable-stack-
486           for-recursion is specified) that is used. A second limit controls this;
487           it  defaults  to  the  value  that is set for --with-match-limit, which
488           imposes no additional constraints. However, you can set a  lower  limit
489           by adding, for example,
491             --with-match-limit-recursion=10000
493           to  the  configure  command.  This  value can also be overridden at run
494           time.
499           PCRE uses fixed tables for processing characters whose code values  are
500           less  than 256. By default, PCRE is built with a set of tables that are
501           distributed in the file pcre_chartables.c.dist. These  tables  are  for
502           ASCII codes only. If you add
504             --enable-rebuild-chartables
506           to  the  configure  command, the distributed tables are no longer used.
507           Instead, a program called dftables is compiled and  run.  This  outputs
508           the source for new set of tables, created in the default locale of your
509           C runtime system. (This method of replacing the tables does not work if
510           you  are cross compiling, because dftables is run on the local host. If
511           you need to create alternative tables when cross  compiling,  you  will
512           have to do so "by hand".)
517           PCRE  assumes  by  default that it will run in an environment where the
518           character code is ASCII (or Unicode, which is  a  superset  of  ASCII).
519           This  is  the  case for most computer operating systems. PCRE can, how-
520           ever, be compiled to run in an EBCDIC environment by adding
522             --enable-ebcdic
524           to the configure command. This setting implies --enable-rebuild-charta-
525           bles.  You  should  only  use  it if you know that you are in an EBCDIC
526           environment (for example,  an  IBM  mainframe  operating  system).  The
527           --enable-ebcdic option is incompatible with --enable-utf8.
532           By default, pcregrep reads all files as plain text. You can build it so
533           that it recognizes files whose names end in .gz or .bz2, and reads them
534           with libz or libbz2, respectively, by adding one or both of
536             --enable-pcregrep-libz
537             --enable-pcregrep-libbz2
539           to the configure command. These options naturally require that the rel-
540           evant libraries are installed on your system. Configuration  will  fail
541           if they are not.
546           If you add
548             --enable-pcretest-libreadline
550           to  the  configure  command,  pcretest  is  linked with the libreadline
551           library, and when its input is from a terminal, it reads it  using  the
552           readline() function. This provides line-editing and history facilities.
553           Note that libreadline is GPL-licenced, so if you distribute a binary of
554           pcretest linked in this way, there may be licensing issues.
556           Setting  this  option  causes  the -lreadline option to be added to the
557           pcretest build. In many operating environments with  a  sytem-installed
558           libreadline this is sufficient. However, in some environments (e.g.  if
559           an unmodified distribution version of readline is in use),  some  extra
560           configuration  may  be necessary. The INSTALL file for libreadline says
561           this:
563             "Readline uses the termcap functions, but does not link with the
564             termcap or curses library itself, allowing applications which link
565             with readline the to choose an appropriate library."
567           If your environment has not been set up so that an appropriate  library
568           is automatically included, you may need to add something like
570             LIBS="-ncurses"
572           immediately before the configure command.
575    SEE ALSO
577           pcreapi(3), pcre_config(3).
580    AUTHOR
582           Philip Hazel
583           University Computing Service
584           Cambridge CB2 3QH, England.
589           Last updated: 17 March 2009
590           Copyright (c) 1997-2009 University of Cambridge.
591    ------------------------------------------------------------------------------
594    PCREMATCHING(3)                                                PCREMATCHING(3)
597    NAME
598           PCRE - Perl-compatible regular expressions
603           This document describes the two different algorithms that are available
604           in PCRE for matching a compiled regular expression against a given sub-
605           ject  string.  The  "standard"  algorithm  is  the  one provided by the
606           pcre_exec() function.  This works in the same was  as  Perl's  matching
607           function, and provides a Perl-compatible matching operation.
609           An  alternative  algorithm is provided by the pcre_dfa_exec() function;
610           this operates in a different way, and is not  Perl-compatible.  It  has
611           advantages  and disadvantages compared with the standard algorithm, and
612           these are described below.
614           When there is only one possible way in which a given subject string can
615           match  a pattern, the two algorithms give the same answer. A difference
616           arises, however, when there are multiple possibilities. For example, if
617           the pattern
619             ^<.*>
621           is matched against the string
623             <something> <something else> <something further>
625           there are three possible answers. The standard algorithm finds only one
626           of them, whereas the alternative algorithm finds all three.
631           The set of strings that are matched by a regular expression can be rep-
632           resented  as  a  tree structure. An unlimited repetition in the pattern
633           makes the tree of infinite size, but it is still a tree.  Matching  the
634           pattern  to a given subject string (from a given starting point) can be
635           thought of as a search of the tree.  There are two  ways  to  search  a
636           tree:  depth-first  and  breadth-first, and these correspond to the two
637           matching algorithms provided by PCRE.
642           In the terminology of Jeffrey Friedl's book "Mastering Regular  Expres-
643           sions",  the  standard  algorithm  is an "NFA algorithm". It conducts a
644           depth-first search of the pattern tree. That is, it  proceeds  along  a
645           single path through the tree, checking that the subject matches what is
646           required. When there is a mismatch, the algorithm  tries  any  alterna-
647           tives  at  the  current point, and if they all fail, it backs up to the
648           previous branch point in the  tree,  and  tries  the  next  alternative
649           branch  at  that  level.  This often involves backing up (moving to the
650           left) in the subject string as well.  The  order  in  which  repetition
651           branches  are  tried  is controlled by the greedy or ungreedy nature of
652           the quantifier.
654           If a leaf node is reached, a matching string has  been  found,  and  at
655           that  point the algorithm stops. Thus, if there is more than one possi-
656           ble match, this algorithm returns the first one that it finds.  Whether
657           this  is the shortest, the longest, or some intermediate length depends
658           on the way the greedy and ungreedy repetition quantifiers are specified
659           in the pattern.
661           Because  it  ends  up  with a single path through the tree, it is rela-
662           tively straightforward for this algorithm to keep  track  of  the  sub-
663           strings  that  are  matched  by portions of the pattern in parentheses.
664           This provides support for capturing parentheses and back references.
669           This algorithm conducts a breadth-first search of  the  tree.  Starting
670           from  the  first  matching  point  in the subject, it scans the subject
671           string from left to right, once, character by character, and as it does
672           this,  it remembers all the paths through the tree that represent valid
673           matches. In Friedl's terminology, this is a kind  of  "DFA  algorithm",
674           though  it is not implemented as a traditional finite state machine (it
675           keeps multiple states active simultaneously).
677           The scan continues until either the end of the subject is  reached,  or
678           there  are  no more unterminated paths. At this point, terminated paths
679           represent the different matching possibilities (if there are none,  the
680           match  has  failed).   Thus,  if there is more than one possible match,
681           this algorithm finds all of them, and in particular, it finds the long-
682           est.  In PCRE, there is an option to stop the algorithm after the first
683           match (which is necessarily the shortest) has been found.
685           Note that all the matches that are found start at the same point in the
686           subject. If the pattern
688             cat(er(pillar)?)
690           is  matched  against the string "the caterpillar catchment", the result
691           will be the three strings "cat", "cater", and "caterpillar" that  start
692           at the fourth character of the subject. The algorithm does not automat-
693           ically move on to find matches that start at later positions.
695           There are a number of features of PCRE regular expressions that are not
696           supported by the alternative matching algorithm. They are as follows:
698           1.  Because  the  algorithm  finds  all possible matches, the greedy or
699           ungreedy nature of repetition quantifiers is not relevant.  Greedy  and
700           ungreedy quantifiers are treated in exactly the same way. However, pos-
701           sessive quantifiers can make a difference when what follows could  also
702           match what is quantified, for example in a pattern like this:
704             ^a++\w!
706           This  pattern matches "aaab!" but not "aaa!", which would be matched by
707           a non-possessive quantifier. Similarly, if an atomic group is  present,
708           it  is matched as if it were a standalone pattern at the current point,
709           and the longest match is then "locked in" for the rest of  the  overall
710           pattern.
712           2. When dealing with multiple paths through the tree simultaneously, it
713           is not straightforward to keep track of  captured  substrings  for  the
714           different  matching  possibilities,  and  PCRE's implementation of this
715           algorithm does not attempt to do this. This means that no captured sub-
716           strings are available.
718           3.  Because no substrings are captured, back references within the pat-
719           tern are not supported, and cause errors if encountered.
721           4. For the same reason, conditional expressions that use  a  backrefer-
722           ence  as  the  condition or test for a specific group recursion are not
723           supported.
725           5. Because many paths through the tree may be  active,  the  \K  escape
726           sequence, which resets the start of the match when encountered (but may
727           be on some paths and not on others), is not  supported.  It  causes  an
728           error if encountered.
730           6.  Callouts  are  supported, but the value of the capture_top field is
731           always 1, and the value of the capture_last field is always -1.
733           7. The \C escape sequence, which (in the standard algorithm) matches  a
734           single  byte, even in UTF-8 mode, is not supported because the alterna-
735           tive algorithm moves through the subject  string  one  character  at  a
736           time, for all active paths through the tree.
738           8.  Except for (*FAIL), the backtracking control verbs such as (*PRUNE)
739           are not supported. (*FAIL) is supported, and  behaves  like  a  failing
740           negative assertion.
745           Using  the alternative matching algorithm provides the following advan-
746           tages:
748           1. All possible matches (at a single point in the subject) are automat-
749           ically  found,  and  in particular, the longest match is found. To find
750           more than one match using the standard algorithm, you have to do kludgy
751           things with callouts.
753           2.  There is much better support for partial matching. The restrictions
754           on the content of the pattern that apply when using the standard  algo-
755           rithm  for  partial matching do not apply to the alternative algorithm.
756           For non-anchored patterns, the starting position of a partial match  is
757           available.
759           3.  Because  the  alternative  algorithm  scans the subject string just
760           once, and never needs to backtrack, it is possible to  pass  very  long
761           subject  strings  to  the matching function in several pieces, checking
762           for partial matching each time.
767           The alternative algorithm suffers from a number of disadvantages:
769           1. It is substantially slower than  the  standard  algorithm.  This  is
770           partly  because  it has to search for all possible matches, but is also
771           because it is less susceptible to optimization.
773           2. Capturing parentheses and back references are not supported.
775           3. Although atomic groups are supported, their use does not provide the
776           performance advantage that it does for the standard algorithm.
779    AUTHOR
781           Philip Hazel
782           University Computing Service
783           Cambridge CB2 3QH, England.
788           Last updated: 19 April 2008
789           Copyright (c) 1997-2008 University of Cambridge.
790    ------------------------------------------------------------------------------
793    PCREAPI(3)                                                          PCREAPI(3)
796    NAME
797           PCRE - Perl-compatible regular expressions
802           #include <pcre.h>
804           pcre *pcre_compile(const char *pattern, int options,
805                const char **errptr, int *erroffset,
806                const unsigned char *tableptr);
808           pcre *pcre_compile2(const char *pattern, int options,
809                int *errorcodeptr,
810                const char **errptr, int *erroffset,
811                const unsigned char *tableptr);
813           pcre_extra *pcre_study(const pcre *code, int options,
814                const char **errptr);
816           int pcre_exec(const pcre *code, const pcre_extra *extra,
817                const char *subject, int length, int startoffset,
818                int options, int *ovector, int ovecsize);
820           int pcre_dfa_exec(const pcre *code, const pcre_extra *extra,
821                const char *subject, int length, int startoffset,
822                int options, int *ovector, int ovecsize,
823                int *workspace, int wscount);
825           int pcre_copy_named_substring(const pcre *code,
826                const char *subject, int *ovector,
827                int stringcount, const char *stringname,
828                char *buffer, int buffersize);
830           int pcre_copy_substring(const char *subject, int *ovector,
831                int stringcount, int stringnumber, char *buffer,
832                int buffersize);
834           int pcre_get_named_substring(const pcre *code,
835                const char *subject, int *ovector,
836                int stringcount, const char *stringname,
837                const char **stringptr);
839           int pcre_get_stringnumber(const pcre *code,
840                const char *name);
842           int pcre_get_stringtable_entries(const pcre *code,
843                const char *name, char **first, char **last);
845           int pcre_get_substring(const char *subject, int *ovector,
846                int stringcount, int stringnumber,
847                const char **stringptr);
849           int pcre_get_substring_list(const char *subject,
850                int *ovector, int stringcount, const char ***listptr);
852           void pcre_free_substring(const char *stringptr);
854           void pcre_free_substring_list(const char **stringptr);
856           const unsigned char *pcre_maketables(void);
858           int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
859                int what, void *where);
861           int pcre_info(const pcre *code, int *optptr, int *firstcharptr);
863           int pcre_refcount(pcre *code, int adjust);
865           int pcre_config(int what, void *where);
867           char *pcre_version(void);
869           void *(*pcre_malloc)(size_t);
871           void (*pcre_free)(void *);
873           void *(*pcre_stack_malloc)(size_t);
875           void (*pcre_stack_free)(void *);
877           int (*pcre_callout)(pcre_callout_block *);
882           PCRE has its own native API, which is described in this document. There
883           are also some wrapper functions that correspond to  the  POSIX  regular
884           expression  API.  These  are  described in the pcreposix documentation.
885           Both of these APIs define a set of C function calls. A C++  wrapper  is
886           distributed with PCRE. It is documented in the pcrecpp page.
888           The  native  API  C  function prototypes are defined in the header file
889           pcre.h, and on Unix systems the library itself is called  libpcre.   It
890           can normally be accessed by adding -lpcre to the command for linking an
891           application  that  uses  PCRE.  The  header  file  defines  the  macros
892           PCRE_MAJOR  and  PCRE_MINOR to contain the major and minor release num-
893           bers for the library.  Applications can use these  to  include  support
894           for different releases of PCRE.
896           The   functions   pcre_compile(),  pcre_compile2(),  pcre_study(),  and
897           pcre_exec() are used for compiling and matching regular expressions  in
898           a  Perl-compatible  manner. A sample program that demonstrates the sim-
899           plest way of using them is provided in the file  called  pcredemo.c  in
900           the  source distribution. The pcresample documentation describes how to
901           compile and run it.
903           A second matching function, pcre_dfa_exec(), which is not Perl-compati-
904           ble,  is  also provided. This uses a different algorithm for the match-
905           ing. The alternative algorithm finds all possible matches (at  a  given
906           point  in  the subject), and scans the subject just once. However, this
907           algorithm does not return captured substrings. A description of the two
908           matching  algorithms and their advantages and disadvantages is given in
909           the pcrematching documentation.
911           In addition to the main compiling and  matching  functions,  there  are
912           convenience functions for extracting captured substrings from a subject
913           string that is matched by pcre_exec(). They are:
915             pcre_copy_substring()
916             pcre_copy_named_substring()
917             pcre_get_substring()
918             pcre_get_named_substring()
919             pcre_get_substring_list()
920             pcre_get_stringnumber()
921             pcre_get_stringtable_entries()
923           pcre_free_substring() and pcre_free_substring_list() are also provided,
924           to free the memory used for extracted strings.
926           The  function  pcre_maketables()  is  used  to build a set of character
927           tables  in  the  current  locale   for   passing   to   pcre_compile(),
928           pcre_exec(),  or  pcre_dfa_exec(). This is an optional facility that is
929           provided for specialist use.  Most  commonly,  no  special  tables  are
930           passed,  in  which case internal tables that are generated when PCRE is
931           built are used.
933           The function pcre_fullinfo() is used to find out  information  about  a
934           compiled  pattern; pcre_info() is an obsolete version that returns only
935           some of the available information, but is retained for  backwards  com-
936           patibility.   The function pcre_version() returns a pointer to a string
937           containing the version of PCRE and its date of release.
939           The function pcre_refcount() maintains a  reference  count  in  a  data
940           block  containing  a compiled pattern. This is provided for the benefit
941           of object-oriented applications.
943           The global variables pcre_malloc and pcre_free  initially  contain  the
944           entry  points  of  the  standard malloc() and free() functions, respec-
945           tively. PCRE calls the memory management functions via these variables,
946           so  a  calling  program  can replace them if it wishes to intercept the
947           calls. This should be done before calling any PCRE functions.
949           The global variables pcre_stack_malloc  and  pcre_stack_free  are  also
950           indirections  to  memory  management functions. These special functions
951           are used only when PCRE is compiled to use  the  heap  for  remembering
952           data, instead of recursive function calls, when running the pcre_exec()
953           function. See the pcrebuild documentation for  details  of  how  to  do
954           this.  It  is  a non-standard way of building PCRE, for use in environ-
955           ments that have limited stacks. Because of the greater  use  of  memory
956           management,  it  runs  more  slowly. Separate functions are provided so
957           that special-purpose external code can be  used  for  this  case.  When
958           used,  these  functions  are always called in a stack-like manner (last
959           obtained, first freed), and always for memory blocks of the same  size.
960           There  is  a discussion about PCRE's stack usage in the pcrestack docu-
961           mentation.
963           The global variable pcre_callout initially contains NULL. It can be set
964           by  the  caller  to  a "callout" function, which PCRE will then call at
965           specified points during a matching operation. Details are given in  the
966           pcrecallout documentation.
971           PCRE  supports five different conventions for indicating line breaks in
972           strings: a single CR (carriage return) character, a  single  LF  (line-
973           feed) character, the two-character sequence CRLF, any of the three pre-
974           ceding, or any Unicode newline sequence. The Unicode newline  sequences
975           are  the  three just mentioned, plus the single characters VT (vertical
976           tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS  (line
977           separator, U+2028), and PS (paragraph separator, U+2029).
979           Each  of  the first three conventions is used by at least one operating
980           system as its standard newline sequence. When PCRE is built, a  default
981           can  be  specified.  The default default is LF, which is the Unix stan-
982           dard. When PCRE is run, the default can be overridden,  either  when  a
983           pattern is compiled, or when it is matched.
985           At compile time, the newline convention can be specified by the options
986           argument of pcre_compile(), or it can be specified by special  text  at
987           the start of the pattern itself; this overrides any other settings. See
988           the pcrepattern page for details of the special character sequences.
990           In the PCRE documentation the word "newline" is used to mean "the char-
991           acter  or pair of characters that indicate a line break". The choice of
992           newline convention affects the handling of  the  dot,  circumflex,  and
993           dollar metacharacters, the handling of #-comments in /x mode, and, when
994           CRLF is a recognized line ending sequence, the match position  advance-
995           ment for a non-anchored pattern. There is more detail about this in the
996           section on pcre_exec() options below.
998           The choice of newline convention does not affect the interpretation  of
999           the  \n  or  \r  escape  sequences, nor does it affect what \R matches,
1000           which is controlled in a similar way, but by separate options.
1005           The PCRE functions can be used in  multi-threading  applications,  with
1006           the  proviso  that  the  memory  management  functions  pointed  to  by
1007           pcre_malloc, pcre_free, pcre_stack_malloc, and pcre_stack_free, and the
1008           callout function pointed to by pcre_callout, are shared by all threads.
1010           The  compiled form of a regular expression is not altered during match-
1011           ing, so the same compiled pattern can safely be used by several threads
1012           at once.
1017           The compiled form of a regular expression can be saved and re-used at a
1018           later time, possibly by a different program, and even on a  host  other
1019           than  the  one  on  which  it  was  compiled.  Details are given in the
1020           pcreprecompile documentation. However, compiling a  regular  expression
1021           with  one version of PCRE for use with a different version is not guar-
1022           anteed to work and may cause crashes.
1027           int pcre_config(int what, void *where);
1029           The function pcre_config() makes it possible for a PCRE client to  dis-
1030           cover which optional features have been compiled into the PCRE library.
1031           The pcrebuild documentation has more details about these optional  fea-
1032           tures.
1034           The  first  argument  for pcre_config() is an integer, specifying which
1035           information is required; the second argument is a pointer to a variable
1036           into  which  the  information  is  placed. The following information is
1037           available:
1039             PCRE_CONFIG_UTF8
1041           The output is an integer that is set to one if UTF-8 support is  avail-
1042           able; otherwise it is set to zero.
1046           The  output  is  an  integer  that is set to one if support for Unicode
1047           character properties is available; otherwise it is set to zero.
1049             PCRE_CONFIG_NEWLINE
1051           The output is an integer whose value specifies  the  default  character
1052           sequence  that is recognized as meaning "newline". The four values that
1053           are supported are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF,
1054           and  -1  for  ANY.  Though they are derived from ASCII, the same values
1055           are returned in EBCDIC environments. The default should normally corre-
1056           spond to the standard sequence for your operating system.
1058             PCRE_CONFIG_BSR
1060           The output is an integer whose value indicates what character sequences
1061           the \R escape sequence matches by default. A value of 0 means  that  \R
1062           matches  any  Unicode  line ending sequence; a value of 1 means that \R
1063           matches only CR, LF, or CRLF. The default can be overridden when a pat-
1064           tern is compiled or matched.
1066             PCRE_CONFIG_LINK_SIZE
1068           The  output  is  an  integer that contains the number of bytes used for
1069           internal linkage in compiled regular expressions. The value is 2, 3, or
1070           4.  Larger  values  allow larger regular expressions to be compiled, at
1071           the expense of slower matching. The default value of  2  is  sufficient
1072           for  all  but  the  most massive patterns, since it allows the compiled
1073           pattern to be up to 64K in size.
1077           The output is an integer that contains the threshold  above  which  the
1078           POSIX  interface  uses malloc() for output vectors. Further details are
1079           given in the pcreposix documentation.
1081             PCRE_CONFIG_MATCH_LIMIT
1083           The output is a long integer that gives the default limit for the  num-
1084           ber  of  internal  matching  function calls in a pcre_exec() execution.
1085           Further details are given with pcre_exec() below.
1089           The output is a long integer that gives the default limit for the depth
1090           of   recursion  when  calling  the  internal  matching  function  in  a
1091           pcre_exec() execution.  Further  details  are  given  with  pcre_exec()
1092           below.
1096           The  output is an integer that is set to one if internal recursion when
1097           running pcre_exec() is implemented by recursive function calls that use
1098           the  stack  to remember their state. This is the usual way that PCRE is
1099           compiled. The output is zero if PCRE was compiled to use blocks of data
1100           on  the  heap  instead  of  recursive  function  calls.  In  this case,
1101           pcre_stack_malloc and  pcre_stack_free  are  called  to  manage  memory
1102           blocks on the heap, thus avoiding the use of the stack.
1107           pcre *pcre_compile(const char *pattern, int options,
1108                const char **errptr, int *erroffset,
1109                const unsigned char *tableptr);
1111           pcre *pcre_compile2(const char *pattern, int options,
1112                int *errorcodeptr,
1113                const char **errptr, int *erroffset,
1114                const unsigned char *tableptr);
1116           Either of the functions pcre_compile() or pcre_compile2() can be called
1117           to compile a pattern into an internal form. The only difference between
1118           the  two interfaces is that pcre_compile2() has an additional argument,
1119           errorcodeptr, via which a numerical error code can be returned.
1121           The pattern is a C string terminated by a binary zero, and is passed in
1122           the  pattern  argument.  A  pointer to a single block of memory that is
1123           obtained via pcre_malloc is returned. This contains the  compiled  code
1124           and related data. The pcre type is defined for the returned block; this
1125           is a typedef for a structure whose contents are not externally defined.
1126           It is up to the caller to free the memory (via pcre_free) when it is no
1127           longer required.
1129           Although the compiled code of a PCRE regex is relocatable, that is,  it
1130           does not depend on memory location, the complete pcre data block is not
1131           fully relocatable, because it may contain a copy of the tableptr  argu-
1132           ment, which is an address (see below).
1134           The options argument contains various bit settings that affect the com-
1135           pilation. It should be zero if no options are required.  The  available
1136           options  are  described  below. Some of them, in particular, those that
1137           are compatible with Perl, can also be set and  unset  from  within  the
1138           pattern  (see  the  detailed  description in the pcrepattern documenta-
1139           tion). For these options, the contents of the options  argument  speci-
1140           fies  their initial settings at the start of compilation and execution.
1141           The PCRE_ANCHORED and PCRE_NEWLINE_xxx options can be set at  the  time
1142           of matching as well as at compile time.
1144           If errptr is NULL, pcre_compile() returns NULL immediately.  Otherwise,
1145           if compilation of a pattern fails,  pcre_compile()  returns  NULL,  and
1146           sets the variable pointed to by errptr to point to a textual error mes-
1147           sage. This is a static string that is part of the library. You must not
1148           try to free it. The offset from the start of the pattern to the charac-
1149           ter where the error was discovered is placed in the variable pointed to
1150           by  erroffset,  which must not be NULL. If it is, an immediate error is
1151           given.
1153           If pcre_compile2() is used instead of pcre_compile(),  and  the  error-
1154           codeptr  argument is not NULL, a non-zero error code number is returned
1155           via this argument in the event of an error. This is in addition to  the
1156           textual error message. Error codes and messages are listed below.
1158           If  the  final  argument, tableptr, is NULL, PCRE uses a default set of
1159           character tables that are  built  when  PCRE  is  compiled,  using  the
1160           default  C  locale.  Otherwise, tableptr must be an address that is the
1161           result of a call to pcre_maketables(). This value is  stored  with  the
1162           compiled  pattern,  and used again by pcre_exec(), unless another table
1163           pointer is passed to it. For more discussion, see the section on locale
1164           support below.
1166           This  code  fragment  shows a typical straightforward call to pcre_com-
1167           pile():
1169             pcre *re;
1170             const char *error;
1171             int erroffset;
1172             re = pcre_compile(
1173               "^A.*Z",          /* the pattern */
1174               0,                /* default options */
1175               &error,           /* for error message */
1176               &erroffset,       /* for error offset */
1177               NULL);            /* use default character tables */
1179           The following names for option bits are defined in  the  pcre.h  header
1180           file:
1182             PCRE_ANCHORED
1184           If this bit is set, the pattern is forced to be "anchored", that is, it
1185           is constrained to match only at the first matching point in the  string
1186           that  is being searched (the "subject string"). This effect can also be
1187           achieved by appropriate constructs in the pattern itself, which is  the
1188           only way to do it in Perl.
1190             PCRE_AUTO_CALLOUT
1192           If this bit is set, pcre_compile() automatically inserts callout items,
1193           all with number 255, before each pattern item. For  discussion  of  the
1194           callout facility, see the pcrecallout documentation.
1196             PCRE_BSR_ANYCRLF
1197             PCRE_BSR_UNICODE
1199           These options (which are mutually exclusive) control what the \R escape
1200           sequence matches. The choice is either to match only CR, LF,  or  CRLF,
1201           or to match any Unicode newline sequence. The default is specified when
1202           PCRE is built. It can be overridden from within the pattern, or by set-
1203           ting an option when a compiled pattern is matched.
1205             PCRE_CASELESS
1207           If  this  bit is set, letters in the pattern match both upper and lower
1208           case letters. It is equivalent to Perl's  /i  option,  and  it  can  be
1209           changed  within a pattern by a (?i) option setting. In UTF-8 mode, PCRE
1210           always understands the concept of case for characters whose values  are
1211           less  than 128, so caseless matching is always possible. For characters
1212           with higher values, the concept of case is supported if  PCRE  is  com-
1213           piled  with Unicode property support, but not otherwise. If you want to
1214           use caseless matching for characters 128 and  above,  you  must  ensure
1215           that  PCRE  is  compiled  with Unicode property support as well as with
1216           UTF-8 support.
1218             PCRE_DOLLAR_ENDONLY
1220           If this bit is set, a dollar metacharacter in the pattern matches  only
1221           at  the  end  of the subject string. Without this option, a dollar also
1222           matches immediately before a newline at the end of the string (but  not
1223           before  any  other newlines). The PCRE_DOLLAR_ENDONLY option is ignored
1224           if PCRE_MULTILINE is set.  There is no equivalent  to  this  option  in
1225           Perl, and no way to set it within a pattern.
1227             PCRE_DOTALL
1229           If this bit is set, a dot metacharater in the pattern matches all char-
1230           acters, including those that indicate newline. Without it, a  dot  does
1231           not  match  when  the  current position is at a newline. This option is
1232           equivalent to Perl's /s option, and it can be changed within a  pattern
1233           by  a (?s) option setting. A negative class such as [^a] always matches
1234           newline characters, independent of the setting of this option.
1236             PCRE_DUPNAMES
1238           If this bit is set, names used to identify capturing  subpatterns  need
1239           not be unique. This can be helpful for certain types of pattern when it
1240           is known that only one instance of the named  subpattern  can  ever  be
1241           matched.  There  are  more details of named subpatterns below; see also
1242           the pcrepattern documentation.
1244             PCRE_EXTENDED
1246           If this bit is set, whitespace  data  characters  in  the  pattern  are
1247           totally ignored except when escaped or inside a character class. White-
1248           space does not include the VT character (code 11). In addition, charac-
1249           ters between an unescaped # outside a character class and the next new-
1250           line, inclusive, are also ignored. This  is  equivalent  to  Perl's  /x
1251           option,  and  it  can be changed within a pattern by a (?x) option set-
1252           ting.
1254           This option makes it possible to include  comments  inside  complicated
1255           patterns.   Note,  however,  that this applies only to data characters.
1256           Whitespace  characters  may  never  appear  within  special   character
1257           sequences  in  a  pattern,  for  example  within the sequence (?( which
1258           introduces a conditional subpattern.
1260             PCRE_EXTRA
1262           This option was invented in order to turn on  additional  functionality
1263           of  PCRE  that  is  incompatible with Perl, but it is currently of very
1264           little use. When set, any backslash in a pattern that is followed by  a
1265           letter  that  has  no  special  meaning causes an error, thus reserving
1266           these combinations for future expansion. By  default,  as  in  Perl,  a
1267           backslash  followed by a letter with no special meaning is treated as a
1268           literal. (Perl can, however, be persuaded to give a warning for  this.)
1269           There  are  at  present no other features controlled by this option. It
1270           can also be set by a (?X) option setting within a pattern.
1272             PCRE_FIRSTLINE
1274           If this option is set, an  unanchored  pattern  is  required  to  match
1275           before  or  at  the  first  newline  in  the subject string, though the
1276           matched text may continue over the newline.
1280           If this option is set, PCRE's behaviour is changed in some ways so that
1281           it  is  compatible with JavaScript rather than Perl. The changes are as
1282           follows:
1284           (1) A lone closing square bracket in a pattern  causes  a  compile-time
1285           error,  because this is illegal in JavaScript (by default it is treated
1286           as a data character). Thus, the pattern AB]CD becomes illegal when this
1287           option is set.
1289           (2)  At run time, a back reference to an unset subpattern group matches
1290           an empty string (by default this causes the current  matching  alterna-
1291           tive  to  fail). A pattern such as (\1)(a) succeeds when this option is
1292           set (assuming it can find an "a" in the subject), whereas it  fails  by
1293           default, for Perl compatibility.
1295             PCRE_MULTILINE
1297           By  default,  PCRE  treats the subject string as consisting of a single
1298           line of characters (even if it actually contains newlines). The  "start
1299           of  line"  metacharacter  (^)  matches only at the start of the string,
1300           while the "end of line" metacharacter ($) matches only at  the  end  of
1301           the string, or before a terminating newline (unless PCRE_DOLLAR_ENDONLY
1302           is set). This is the same as Perl.
1304           When PCRE_MULTILINE it is set, the "start of line" and  "end  of  line"
1305           constructs  match  immediately following or immediately before internal
1306           newlines in the subject string, respectively, as well as  at  the  very
1307           start  and  end.  This is equivalent to Perl's /m option, and it can be
1308           changed within a pattern by a (?m) option setting. If there are no new-
1309           lines  in  a  subject string, or no occurrences of ^ or $ in a pattern,
1310           setting PCRE_MULTILINE has no effect.
1312             PCRE_NEWLINE_CR
1313             PCRE_NEWLINE_LF
1314             PCRE_NEWLINE_CRLF
1315             PCRE_NEWLINE_ANYCRLF
1316             PCRE_NEWLINE_ANY
1318           These options override the default newline definition that  was  chosen
1319           when  PCRE  was built. Setting the first or the second specifies that a
1320           newline is indicated by a single character (CR  or  LF,  respectively).
1321           Setting  PCRE_NEWLINE_CRLF specifies that a newline is indicated by the
1322           two-character CRLF  sequence.  Setting  PCRE_NEWLINE_ANYCRLF  specifies
1323           that any of the three preceding sequences should be recognized. Setting
1324           PCRE_NEWLINE_ANY specifies that any Unicode newline sequence should  be
1325           recognized. The Unicode newline sequences are the three just mentioned,
1326           plus the single characters VT (vertical  tab,  U+000B),  FF  (formfeed,
1327           U+000C),  NEL  (next line, U+0085), LS (line separator, U+2028), and PS
1328           (paragraph separator, U+2029). The last  two  are  recognized  only  in
1329           UTF-8 mode.
1331           The  newline  setting  in  the  options  word  uses three bits that are
1332           treated as a number, giving eight possibilities. Currently only six are
1333           used  (default  plus the five values above). This means that if you set
1334           more than one newline option, the combination may or may not be  sensi-
1335           ble. For example, PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to
1336           PCRE_NEWLINE_CRLF, but other combinations may yield unused numbers  and
1337           cause an error.
1339           The  only time that a line break is specially recognized when compiling
1340           a pattern is if PCRE_EXTENDED is set, and  an  unescaped  #  outside  a
1341           character  class  is  encountered.  This indicates a comment that lasts
1342           until after the next line break sequence. In other circumstances,  line
1343           break   sequences   are   treated  as  literal  data,  except  that  in
1344           PCRE_EXTENDED mode, both CR and LF are treated as whitespace characters
1345           and are therefore ignored.
1347           The newline option that is set at compile time becomes the default that
1348           is used for pcre_exec() and pcre_dfa_exec(), but it can be overridden.
1350             PCRE_NO_AUTO_CAPTURE
1352           If this option is set, it disables the use of numbered capturing paren-
1353           theses  in the pattern. Any opening parenthesis that is not followed by
1354           ? behaves as if it were followed by ?: but named parentheses can  still
1355           be  used  for  capturing  (and  they acquire numbers in the usual way).
1356           There is no equivalent of this option in Perl.
1358             PCRE_UNGREEDY
1360           This option inverts the "greediness" of the quantifiers  so  that  they
1361           are  not greedy by default, but become greedy if followed by "?". It is
1362           not compatible with Perl. It can also be set by a (?U)  option  setting
1363           within the pattern.
1365             PCRE_UTF8
1367           This  option  causes PCRE to regard both the pattern and the subject as
1368           strings of UTF-8 characters instead of single-byte  character  strings.
1369           However,  it is available only when PCRE is built to include UTF-8 sup-
1370           port. If not, the use of this option provokes an error. Details of  how
1371           this  option  changes the behaviour of PCRE are given in the section on
1372           UTF-8 support in the main pcre page.
1374             PCRE_NO_UTF8_CHECK
1376           When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is
1377           automatically  checked.  There  is  a  discussion about the validity of
1378           UTF-8 strings in the main pcre page. If an invalid  UTF-8  sequence  of
1379           bytes  is  found,  pcre_compile() returns an error. If you already know
1380           that your pattern is valid, and you want to skip this check for perfor-
1381           mance  reasons,  you  can set the PCRE_NO_UTF8_CHECK option. When it is
1382           set, the effect of passing an invalid UTF-8  string  as  a  pattern  is
1383           undefined.  It  may  cause your program to crash. Note that this option
1384           can also be passed to pcre_exec() and pcre_dfa_exec(), to suppress  the
1385           UTF-8 validity checking of subject strings.
1390           The  following  table  lists  the  error  codes than may be returned by
1391           pcre_compile2(), along with the error messages that may be returned  by
1392           both  compiling functions. As PCRE has developed, some error codes have
1393           fallen out of use. To avoid confusion, they have not been re-used.
1395              0  no error
1396              1  \ at end of pattern
1397              2  \c at end of pattern
1398              3  unrecognized character follows \
1399              4  numbers out of order in {} quantifier
1400              5  number too big in {} quantifier
1401              6  missing terminating ] for character class
1402              7  invalid escape sequence in character class
1403              8  range out of order in character class
1404              9  nothing to repeat
1405             10  [this code is not in use]
1406             11  internal error: unexpected repeat
1407             12  unrecognized character after (? or (?-
1408             13  POSIX named classes are supported only within a class
1409             14  missing )
1410             15  reference to non-existent subpattern
1411             16  erroffset passed as NULL
1412             17  unknown option bit(s) set
1413             18  missing ) after comment
1414             19  [this code is not in use]
1415             20  regular expression is too large
1416             21  failed to get memory
1417             22  unmatched parentheses
1418             23  internal error: code overflow
1419             24  unrecognized character after (?<
1420             25  lookbehind assertion is not fixed length
1421             26  malformed number or name after (?(
1422             27  conditional group contains more than two branches
1423             28  assertion expected after (?(
1424             29  (?R or (?[+-]digits must be followed by )
1425             30  unknown POSIX class name
1426             31  POSIX collating elements are not supported
1427             32  this version of PCRE is not compiled with PCRE_UTF8 support
1428             33  [this code is not in use]
1429             34  character value in \x{...} sequence is too large
1430             35  invalid condition (?(0)
1431             36  \C not allowed in lookbehind assertion
1432             37  PCRE does not support \L, \l, \N, \U, or \u
1433             38  number after (?C is > 255
1434             39  closing ) for (?C expected
1435             40  recursive call could loop indefinitely
1436             41  unrecognized character after (?P
1437             42  syntax error in subpattern name (missing terminator)
1438             43  two named subpatterns have the same name
1439             44  invalid UTF-8 string
1440             45  support for \P, \p, and \X has not been compiled
1441             46  malformed \P or \p sequence
1442             47  unknown property name after \P or \p
1443             48  subpattern name is too long (maximum 32 characters)
1444             49  too many named subpatterns (maximum 10000)
1445             50  [this code is not in use]
1446             51  octal value is greater than \377 (not in UTF-8 mode)
1447             52  internal error: overran compiling workspace
1448             53  internal  error:  previously-checked  referenced  subpattern  not
1449           found
1450             54  DEFINE group contains more than one branch
1451             55  repeating a DEFINE group is not allowed
1452             56  inconsistent NEWLINE options
1453             57  \g is not followed by a braced, angle-bracketed, or quoted
1454                   name/number or by a plain number
1455             58  a numbered reference must not be zero
1456             59  (*VERB) with an argument is not supported
1457             60  (*VERB) not recognized
1458             61  number is too big
1459             62  subpattern name expected
1460             63  digit expected after (?+
1461             64  ] is an invalid data character in JavaScript compatibility mode
1463           The  numbers  32  and 10000 in errors 48 and 49 are defaults; different
1464           values may be used if the limits were changed when PCRE was built.
1469           pcre_extra *pcre_study(const pcre *code, int options
1470                const char **errptr);
1472           If a compiled pattern is going to be used several times,  it  is  worth
1473           spending more time analyzing it in order to speed up the time taken for
1474           matching. The function pcre_study() takes a pointer to a compiled  pat-
1475           tern as its first argument. If studying the pattern produces additional
1476           information that will help speed up matching,  pcre_study()  returns  a
1477           pointer  to a pcre_extra block, in which the study_data field points to
1478           the results of the study.
1480           The  returned  value  from  pcre_study()  can  be  passed  directly  to
1481           pcre_exec().  However,  a  pcre_extra  block also contains other fields
1482           that can be set by the caller before the block  is  passed;  these  are
1483           described below in the section on matching a pattern.
1485           If  studying  the  pattern  does not produce any additional information
1486           pcre_study() returns NULL. In that circumstance, if the calling program
1487           wants  to  pass  any of the other fields to pcre_exec(), it must set up
1488           its own pcre_extra block.
1490           The second argument of pcre_study() contains option bits.  At  present,
1491           no options are defined, and this argument should always be zero.
1493           The  third argument for pcre_study() is a pointer for an error message.
1494           If studying succeeds (even if no data is  returned),  the  variable  it
1495           points  to  is  set  to NULL. Otherwise it is set to point to a textual
1496           error message. This is a static string that is part of the library. You
1497           must  not  try  to  free it. You should test the error pointer for NULL
1498           after calling pcre_study(), to be sure that it has run successfully.
1500           This is a typical call to pcre_study():
1502             pcre_extra *pe;
1503             pe = pcre_study(
1504               re,             /* result of pcre_compile() */
1505               0,              /* no options exist */
1506               &error);        /* set to NULL or points to a message */
1508           At present, studying a pattern is useful only for non-anchored patterns
1509           that  do not have a single fixed starting character. A bitmap of possi-
1510           ble starting bytes is created.
1515           PCRE handles caseless matching, and determines whether  characters  are
1516           letters,  digits, or whatever, by reference to a set of tables, indexed
1517           by character value. When running in UTF-8 mode, this  applies  only  to
1518           characters  with  codes  less than 128. Higher-valued codes never match
1519           escapes such as \w or \d, but can be tested with \p if  PCRE  is  built
1520           with  Unicode  character property support. The use of locales with Uni-
1521           code is discouraged. If you are handling characters with codes  greater
1522           than  128, you should either use UTF-8 and Unicode, or use locales, but
1523           not try to mix the two.
1525           PCRE contains an internal set of tables that are used  when  the  final
1526           argument  of  pcre_compile()  is  NULL.  These  are sufficient for many
1527           applications.  Normally, the internal tables recognize only ASCII char-
1528           acters. However, when PCRE is built, it is possible to cause the inter-
1529           nal tables to be rebuilt in the default "C" locale of the local system,
1530           which may cause them to be different.
1532           The  internal tables can always be overridden by tables supplied by the
1533           application that calls PCRE. These may be created in a different locale
1534           from  the  default.  As more and more applications change to using Uni-
1535           code, the need for this locale support is expected to die away.
1537           External tables are built by calling  the  pcre_maketables()  function,
1538           which  has no arguments, in the relevant locale. The result can then be
1539           passed to pcre_compile() or pcre_exec()  as  often  as  necessary.  For
1540           example,  to  build  and use tables that are appropriate for the French
1541           locale (where accented characters with  values  greater  than  128  are
1542           treated as letters), the following code could be used:
1544             setlocale(LC_CTYPE, "fr_FR");
1545             tables = pcre_maketables();
1546             re = pcre_compile(..., tables);
1548           The  locale  name "fr_FR" is used on Linux and other Unix-like systems;
1549           if you are using Windows, the name for the French locale is "french".
1551           When pcre_maketables() runs, the tables are built  in  memory  that  is
1552           obtained  via  pcre_malloc. It is the caller's responsibility to ensure
1553           that the memory containing the tables remains available for as long  as
1554           it is needed.
1556           The pointer that is passed to pcre_compile() is saved with the compiled
1557           pattern, and the same tables are used via this pointer by  pcre_study()
1558           and normally also by pcre_exec(). Thus, by default, for any single pat-
1559           tern, compilation, studying and matching all happen in the same locale,
1560           but different patterns can be compiled in different locales.
1562           It  is  possible to pass a table pointer or NULL (indicating the use of
1563           the internal tables) to pcre_exec(). Although  not  intended  for  this
1564           purpose,  this facility could be used to match a pattern in a different
1565           locale from the one in which it was compiled. Passing table pointers at
1566           run time is discussed below in the section on matching a pattern.
1571           int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
1572                int what, void *where);
1574           The  pcre_fullinfo() function returns information about a compiled pat-
1575           tern. It replaces the obsolete pcre_info() function, which is neverthe-
1576           less retained for backwards compability (and is documented below).
1578           The  first  argument  for  pcre_fullinfo() is a pointer to the compiled
1579           pattern. The second argument is the result of pcre_study(), or NULL  if
1580           the  pattern  was not studied. The third argument specifies which piece
1581           of information is required, and the fourth argument is a pointer  to  a
1582           variable  to  receive  the  data. The yield of the function is zero for
1583           success, or one of the following negative numbers:
1585             PCRE_ERROR_NULL       the argument code was NULL
1586                                   the argument where was NULL
1587             PCRE_ERROR_BADMAGIC   the "magic number" was not found
1588             PCRE_ERROR_BADOPTION  the value of what was invalid
1590           The "magic number" is placed at the start of each compiled  pattern  as
1591           an  simple check against passing an arbitrary memory pointer. Here is a
1592           typical call of pcre_fullinfo(), to obtain the length of  the  compiled
1593           pattern:
1595             int rc;
1596             size_t length;
1597             rc = pcre_fullinfo(
1598               re,               /* result of pcre_compile() */
1599               pe,               /* result of pcre_study(), or NULL */
1600               PCRE_INFO_SIZE,   /* what is required */
1601               &length);         /* where to put the data */
1603           The  possible  values for the third argument are defined in pcre.h, and
1604           are as follows:
1606             PCRE_INFO_BACKREFMAX
1608           Return the number of the highest back reference  in  the  pattern.  The
1609           fourth  argument  should  point to an int variable. Zero is returned if
1610           there are no back references.
1614           Return the number of capturing subpatterns in the pattern.  The  fourth
1615           argument should point to an int variable.
1619           Return  a pointer to the internal default character tables within PCRE.
1620           The fourth argument should point to an unsigned char *  variable.  This
1621           information call is provided for internal use by the pcre_study() func-
1622           tion. External callers can cause PCRE to use  its  internal  tables  by
1623           passing a NULL table pointer.
1625             PCRE_INFO_FIRSTBYTE
1627           Return  information  about  the first byte of any matched string, for a
1628           non-anchored pattern. The fourth argument should point to an int  vari-
1629           able.  (This option used to be called PCRE_INFO_FIRSTCHAR; the old name
1630           is still recognized for backwards compatibility.)
1632           If there is a fixed first byte, for example, from  a  pattern  such  as
1633           (cat|cow|coyote), its value is returned. Otherwise, if either
1635           (a)  the pattern was compiled with the PCRE_MULTILINE option, and every
1636           branch starts with "^", or
1638           (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not
1639           set (if it were set, the pattern would be anchored),
1641           -1  is  returned, indicating that the pattern matches only at the start
1642           of a subject string or after any newline within the  string.  Otherwise
1643           -2 is returned. For anchored patterns, -2 is returned.
1645             PCRE_INFO_FIRSTTABLE
1647           If  the pattern was studied, and this resulted in the construction of a
1648           256-bit table indicating a fixed set of bytes for the first byte in any
1649           matching  string, a pointer to the table is returned. Otherwise NULL is
1650           returned. The fourth argument should point to an unsigned char *  vari-
1651           able.
1653             PCRE_INFO_HASCRORLF
1655           Return  1  if  the  pattern  contains any explicit matches for CR or LF
1656           characters, otherwise 0. The fourth argument should  point  to  an  int
1657           variable.  An explicit match is either a literal CR or LF character, or
1658           \r or \n.
1660             PCRE_INFO_JCHANGED
1662           Return 1 if the (?J) or (?-J) option setting is used  in  the  pattern,
1663           otherwise  0. The fourth argument should point to an int variable. (?J)
1664           and (?-J) set and unset the local PCRE_DUPNAMES option, respectively.
1666             PCRE_INFO_LASTLITERAL
1668           Return the value of the rightmost literal byte that must exist  in  any
1669           matched  string,  other  than  at  its  start,  if such a byte has been
1670           recorded. The fourth argument should point to an int variable. If there
1671           is  no such byte, -1 is returned. For anchored patterns, a last literal
1672           byte is recorded only if it follows something of variable  length.  For
1673           example, for the pattern /^a\d+z\d+/ the returned value is "z", but for
1674           /^a\dz\d/ the returned value is -1.
1676             PCRE_INFO_NAMECOUNT
1678             PCRE_INFO_NAMETABLE
1680           PCRE supports the use of named as well as numbered capturing  parenthe-
1681           ses.  The names are just an additional way of identifying the parenthe-
1682           ses, which still acquire numbers. Several convenience functions such as
1683           pcre_get_named_substring()  are  provided  for extracting captured sub-
1684           strings by name. It is also possible to extract the data  directly,  by
1685           first  converting  the  name to a number in order to access the correct
1686           pointers in the output vector (described with pcre_exec() below). To do
1687           the  conversion,  you  need  to  use  the  name-to-number map, which is
1688           described by these three values.
1690           The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT
1691           gives the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size
1692           of each entry; both of these  return  an  int  value.  The  entry  size
1693           depends  on the length of the longest name. PCRE_INFO_NAMETABLE returns
1694           a pointer to the first entry of the table  (a  pointer  to  char).  The
1695           first two bytes of each entry are the number of the capturing parenthe-
1696           sis, most significant byte first. The rest of the entry is  the  corre-
1697           sponding  name,  zero  terminated. The names are in alphabetical order.
1698           When PCRE_DUPNAMES is set, duplicate names are in order of their paren-
1699           theses  numbers.  For  example,  consider the following pattern (assume
1700           PCRE_EXTENDED is  set,  so  white  space  -  including  newlines  -  is
1701           ignored):
1703             (?<date> (?<year>(\d\d)?\d\d) -
1704             (?<month>\d\d) - (?<day>\d\d) )
1706           There  are  four  named subpatterns, so the table has four entries, and
1707           each entry in the table is eight bytes long. The table is  as  follows,
1708           with non-printing bytes shows in hexadecimal, and undefined bytes shown
1709           as ??:
1711             00 01 d  a  t  e  00 ??
1712             00 05 d  a  y  00 ?? ??
1713             00 04 m  o  n  t  h  00
1714             00 02 y  e  a  r  00 ??
1716           When writing code to extract data  from  named  subpatterns  using  the
1717           name-to-number  map,  remember that the length of the entries is likely
1718           to be different for each compiled pattern.
1720             PCRE_INFO_OKPARTIAL
1722           Return 1 if the pattern can be used for partial matching, otherwise  0.
1723           The  fourth  argument  should point to an int variable. The pcrepartial
1724           documentation lists the restrictions that apply to patterns  when  par-
1725           tial matching is used.
1727             PCRE_INFO_OPTIONS
1729           Return  a  copy of the options with which the pattern was compiled. The
1730           fourth argument should point to an unsigned long  int  variable.  These
1731           option bits are those specified in the call to pcre_compile(), modified
1732           by any top-level option settings at the start of the pattern itself. In
1733           other  words,  they are the options that will be in force when matching
1734           starts. For example, if the pattern /(?im)abc(?-i)d/ is  compiled  with
1735           the  PCRE_EXTENDED option, the result is PCRE_CASELESS, PCRE_MULTILINE,
1736           and PCRE_EXTENDED.
1738           A pattern is automatically anchored by PCRE if  all  of  its  top-level
1739           alternatives begin with one of the following:
1741             ^     unless PCRE_MULTILINE is set
1742             \A    always
1743             \G    always
1744             .*    if PCRE_DOTALL is set and there are no back
1745                     references to the subpattern in which .* appears
1747           For such patterns, the PCRE_ANCHORED bit is set in the options returned
1748           by pcre_fullinfo().
1750             PCRE_INFO_SIZE
1752           Return the size of the compiled pattern, that is, the  value  that  was
1753           passed as the argument to pcre_malloc() when PCRE was getting memory in
1754           which to place the compiled data. The fourth argument should point to a
1755           size_t variable.
1757             PCRE_INFO_STUDYSIZE
1759           Return the size of the data block pointed to by the study_data field in
1760           a pcre_extra block. That is,  it  is  the  value  that  was  passed  to
1761           pcre_malloc() when PCRE was getting memory into which to place the data
1762           created by pcre_study(). The fourth argument should point to  a  size_t
1763           variable.
1768           int pcre_info(const pcre *code, int *optptr, int *firstcharptr);
1770           The  pcre_info()  function is now obsolete because its interface is too
1771           restrictive to return all the available data about a compiled  pattern.
1772           New   programs   should  use  pcre_fullinfo()  instead.  The  yield  of
1773           pcre_info() is the number of capturing subpatterns, or one of the  fol-
1774           lowing negative numbers:
1776             PCRE_ERROR_NULL       the argument code was NULL
1777             PCRE_ERROR_BADMAGIC   the "magic number" was not found
1779           If  the  optptr  argument is not NULL, a copy of the options with which
1780           the pattern was compiled is placed in the integer  it  points  to  (see
1781           PCRE_INFO_OPTIONS above).
1783           If  the  pattern  is  not anchored and the firstcharptr argument is not
1784           NULL, it is used to pass back information about the first character  of
1785           any matched string (see PCRE_INFO_FIRSTBYTE above).
1790           int pcre_refcount(pcre *code, int adjust);
1792           The  pcre_refcount()  function is used to maintain a reference count in
1793           the data block that contains a compiled pattern. It is provided for the
1794           benefit  of  applications  that  operate  in an object-oriented manner,
1795           where different parts of the application may be using the same compiled
1796           pattern, but you want to free the block when they are all done.
1798           When a pattern is compiled, the reference count field is initialized to
1799           zero.  It is changed only by calling this function, whose action is  to
1800           add  the  adjust  value  (which may be positive or negative) to it. The
1801           yield of the function is the new value. However, the value of the count
1802           is  constrained to lie between 0 and 65535, inclusive. If the new value
1803           is outside these limits, it is forced to the appropriate limit value.
1805           Except when it is zero, the reference count is not correctly  preserved
1806           if  a  pattern  is  compiled on one host and then transferred to a host
1807           whose byte-order is different. (This seems a highly unlikely scenario.)
1812           int pcre_exec(const pcre *code, const pcre_extra *extra,
1813                const char *subject, int length, int startoffset,
1814                int options, int *ovector, int ovecsize);
1816           The function pcre_exec() is called to match a subject string against  a
1817           compiled  pattern, which is passed in the code argument. If the pattern
1818           has been studied, the result of the study should be passed in the extra
1819           argument.  This  function is the main matching facility of the library,
1820           and it operates in a Perl-like manner. For specialist use there is also
1821           an  alternative matching function, which is described below in the sec-
1822           tion about the pcre_dfa_exec() function.
1824           In most applications, the pattern will have been compiled (and  option-
1825           ally  studied)  in the same process that calls pcre_exec(). However, it
1826           is possible to save compiled patterns and study data, and then use them
1827           later  in  different processes, possibly even on different hosts. For a
1828           discussion about this, see the pcreprecompile documentation.
1830           Here is an example of a simple call to pcre_exec():
1832             int rc;
1833             int ovector[30];
1834             rc = pcre_exec(
1835               re,             /* result of pcre_compile() */
1836               NULL,           /* we didn't study the pattern */
1837               "some string",  /* the subject string */
1838               11,             /* the length of the subject string */
1839               0,              /* start at offset 0 in the subject */
1840               0,              /* default options */
1841               ovector,        /* vector of integers for substring information */
1842               30);            /* number of elements (NOT size in bytes) */
1844       Extra data for pcre_exec()
1846           If the extra argument is not NULL, it must point to a  pcre_extra  data
1847           block.  The pcre_study() function returns such a block (when it doesn't
1848           return NULL), but you can also create one for yourself, and pass  addi-
1849           tional  information  in it. The pcre_extra block contains the following
1850           fields (not necessarily in this order):
1852             unsigned long int flags;
1853             void *study_data;
1854             unsigned long int match_limit;
1855             unsigned long int match_limit_recursion;
1856             void *callout_data;
1857             const unsigned char *tables;
1859           The flags field is a bitmap that specifies which of  the  other  fields
1860           are set. The flag bits are:
1862             PCRE_EXTRA_STUDY_DATA
1863             PCRE_EXTRA_MATCH_LIMIT
1865             PCRE_EXTRA_CALLOUT_DATA
1866             PCRE_EXTRA_TABLES
1868           Other  flag  bits should be set to zero. The study_data field is set in
1869           the pcre_extra block that is returned by  pcre_study(),  together  with
1870           the appropriate flag bit. You should not set this yourself, but you may
1871           add to the block by setting the other fields  and  their  corresponding
1872           flag bits.
1874           The match_limit field provides a means of preventing PCRE from using up
1875           a vast amount of resources when running patterns that are not going  to
1876           match,  but  which  have  a very large number of possibilities in their
1877           search trees. The classic  example  is  the  use  of  nested  unlimited
1878           repeats.
1880           Internally,  PCRE uses a function called match() which it calls repeat-
1881           edly (sometimes recursively). The limit set by match_limit  is  imposed
1882           on  the  number  of times this function is called during a match, which
1883           has the effect of limiting the amount of  backtracking  that  can  take
1884           place. For patterns that are not anchored, the count restarts from zero
1885           for each position in the subject string.
1887           The default value for the limit can be set  when  PCRE  is  built;  the
1888           default  default  is 10 million, which handles all but the most extreme
1889           cases. You can override the default  by  suppling  pcre_exec()  with  a
1890           pcre_extra     block    in    which    match_limit    is    set,    and
1891           PCRE_EXTRA_MATCH_LIMIT is set in the  flags  field.  If  the  limit  is
1892           exceeded, pcre_exec() returns PCRE_ERROR_MATCHLIMIT.
1894           The  match_limit_recursion field is similar to match_limit, but instead
1895           of limiting the total number of times that match() is called, it limits
1896           the  depth  of  recursion. The recursion depth is a smaller number than
1897           the total number of calls, because not all calls to match() are  recur-
1898           sive.  This limit is of use only if it is set smaller than match_limit.
1900           Limiting  the  recursion  depth  limits the amount of stack that can be
1901           used, or, when PCRE has been compiled to use memory on the heap instead
1902           of the stack, the amount of heap memory that can be used.
1904           The  default  value  for  match_limit_recursion can be set when PCRE is
1905           built; the default default  is  the  same  value  as  the  default  for
1906           match_limit.  You can override the default by suppling pcre_exec() with
1907           a  pcre_extra  block  in  which  match_limit_recursion  is   set,   and
1908           PCRE_EXTRA_MATCH_LIMIT_RECURSION  is  set  in  the  flags field. If the
1909           limit is exceeded, pcre_exec() returns PCRE_ERROR_RECURSIONLIMIT.
1911           The pcre_callout field is used in conjunction with the  "callout"  fea-
1912           ture, which is described in the pcrecallout documentation.
1914           The  tables  field  is  used  to  pass  a  character  tables pointer to
1915           pcre_exec(); this overrides the value that is stored with the  compiled
1916           pattern.  A  non-NULL value is stored with the compiled pattern only if
1917           custom tables were supplied to pcre_compile() via  its  tableptr  argu-
1918           ment.  If NULL is passed to pcre_exec() using this mechanism, it forces
1919           PCRE's internal tables to be used. This facility is  helpful  when  re-
1920           using  patterns  that  have been saved after compiling with an external
1921           set of tables, because the external tables  might  be  at  a  different
1922           address  when  pcre_exec() is called. See the pcreprecompile documenta-
1923           tion for a discussion of saving compiled patterns for later use.
1925       Option bits for pcre_exec()
1927           The unused bits of the options argument for pcre_exec() must  be  zero.
1928           The  only  bits  that  may  be set are PCRE_ANCHORED, PCRE_NEWLINE_xxx,
1930           PCRE_NO_UTF8_CHECK and PCRE_PARTIAL.
1932             PCRE_ANCHORED
1934           The  PCRE_ANCHORED  option  limits pcre_exec() to matching at the first
1935           matching position. If a pattern was  compiled  with  PCRE_ANCHORED,  or
1936           turned  out to be anchored by virtue of its contents, it cannot be made
1937           unachored at matching time.
1939             PCRE_BSR_ANYCRLF
1940             PCRE_BSR_UNICODE
1942           These options (which are mutually exclusive) control what the \R escape
1943           sequence  matches.  The choice is either to match only CR, LF, or CRLF,
1944           or to match any Unicode newline sequence. These  options  override  the
1945           choice that was made or defaulted when the pattern was compiled.
1947             PCRE_NEWLINE_CR
1948             PCRE_NEWLINE_LF
1949             PCRE_NEWLINE_CRLF
1950             PCRE_NEWLINE_ANYCRLF
1951             PCRE_NEWLINE_ANY
1953           These  options  override  the  newline  definition  that  was chosen or
1954           defaulted when the pattern was compiled. For details, see the  descrip-
1955           tion  of  pcre_compile()  above.  During  matching,  the newline choice
1956           affects the behaviour of the dot, circumflex,  and  dollar  metacharac-
1957           ters.  It may also alter the way the match position is advanced after a
1958           match failure for an unanchored pattern.
1961           set,  and a match attempt for an unanchored pattern fails when the cur-
1962           rent position is at a  CRLF  sequence,  and  the  pattern  contains  no
1963           explicit  matches  for  CR  or  LF  characters,  the  match position is
1964           advanced by two characters instead of one, in other words, to after the
1965           CRLF.
1967           The above rule is a compromise that makes the most common cases work as
1968           expected. For example, if the  pattern  is  .+A  (and  the  PCRE_DOTALL
1969           option is not set), it does not match the string "\r\nA" because, after
1970           failing at the start, it skips both the CR and the LF before  retrying.
1971           However,  the  pattern  [\r\n]A does match that string, because it con-
1972           tains an explicit CR or LF reference, and so advances only by one char-
1973           acter after the first failure.
1975           An explicit match for CR of LF is either a literal appearance of one of
1976           those characters, or one of the \r or  \n  escape  sequences.  Implicit
1977           matches  such  as [^X] do not count, nor does \s (which includes CR and
1978           LF in the characters that it matches).
1980           Notwithstanding the above, anomalous effects may still occur when  CRLF
1981           is a valid newline sequence and explicit \r or \n escapes appear in the
1982           pattern.
1984             PCRE_NOTBOL
1986           This option specifies that first character of the subject string is not
1987           the  beginning  of  a  line, so the circumflex metacharacter should not
1988           match before it. Setting this without PCRE_MULTILINE (at compile  time)
1989           causes  circumflex  never to match. This option affects only the behav-
1990           iour of the circumflex metacharacter. It does not affect \A.
1992             PCRE_NOTEOL
1994           This option specifies that the end of the subject string is not the end
1995           of  a line, so the dollar metacharacter should not match it nor (except
1996           in multiline mode) a newline immediately before it. Setting this  with-
1997           out PCRE_MULTILINE (at compile time) causes dollar never to match. This
1998           option affects only the behaviour of the dollar metacharacter. It  does
1999           not affect \Z or \z.
2001             PCRE_NOTEMPTY
2003           An empty string is not considered to be a valid match if this option is
2004           set. If there are alternatives in the pattern, they are tried.  If  all
2005           the  alternatives  match  the empty string, the entire match fails. For
2006           example, if the pattern
2008             a?b?
2010           is applied to a string not beginning with "a" or "b",  it  matches  the
2011           empty  string at the start of the subject. With PCRE_NOTEMPTY set, this
2012           match is not valid, so PCRE searches further into the string for occur-
2013           rences of "a" or "b".
2015           Perl has no direct equivalent of PCRE_NOTEMPTY, but it does make a spe-
2016           cial case of a pattern match of the empty  string  within  its  split()
2017           function,  and  when  using  the /g modifier. It is possible to emulate
2018           Perl's behaviour after matching a null string by first trying the match
2019           again at the same offset with PCRE_NOTEMPTY and PCRE_ANCHORED, and then
2020           if that fails by advancing the starting offset (see below)  and  trying
2021           an ordinary match again. There is some code that demonstrates how to do
2022           this in the pcredemo.c sample program.
2024             PCRE_NO_START_OPTIMIZE
2026           There are a number of optimizations that pcre_exec() uses at the  start
2027           of  a  match,  in  order to speed up the process. For example, if it is
2028           known that a match must start with a specific  character,  it  searches
2029           the subject for that character, and fails immediately if it cannot find
2030           it, without actually running the main matching function. When  callouts
2031           are  in  use,  these  optimizations  can cause them to be skipped. This
2032           option disables the "start-up" optimizations,  causing  performance  to
2033           suffer, but ensuring that the callouts do occur.
2035             PCRE_NO_UTF8_CHECK
2037           When PCRE_UTF8 is set at compile time, the validity of the subject as a
2038           UTF-8 string is automatically checked when pcre_exec() is  subsequently
2039           called.   The  value  of  startoffset is also checked to ensure that it
2040           points to the start of a UTF-8 character. There is a  discussion  about
2041           the  validity  of  UTF-8 strings in the section on UTF-8 support in the
2042           main pcre page. If  an  invalid  UTF-8  sequence  of  bytes  is  found,
2043           pcre_exec()  returns  the error PCRE_ERROR_BADUTF8. If startoffset con-
2044           tains an invalid value, PCRE_ERROR_BADUTF8_OFFSET is returned.
2046           If you already know that your subject is valid, and you  want  to  skip
2047           these    checks    for   performance   reasons,   you   can   set   the
2048           PCRE_NO_UTF8_CHECK option when calling pcre_exec(). You might  want  to
2049           do  this  for the second and subsequent calls to pcre_exec() if you are
2050           making repeated calls to find all  the  matches  in  a  single  subject
2051           string.  However,  you  should  be  sure  that the value of startoffset
2052           points to the start of a UTF-8 character.  When  PCRE_NO_UTF8_CHECK  is
2053           set,  the  effect of passing an invalid UTF-8 string as a subject, or a
2054           value of startoffset that does not point to the start of a UTF-8  char-
2055           acter, is undefined. Your program may crash.
2057             PCRE_PARTIAL
2059           This  option  turns  on  the  partial  matching feature. If the subject
2060           string fails to match the pattern, but at some point during the  match-
2061           ing  process  the  end of the subject was reached (that is, the subject
2062           partially matches the pattern and the failure to  match  occurred  only
2063           because  there were not enough subject characters), pcre_exec() returns
2065           used,  there  are restrictions on what may appear in the pattern. These
2066           are discussed in the pcrepartial documentation.
2068       The string to be matched by pcre_exec()
2070           The subject string is passed to pcre_exec() as a pointer in subject,  a
2071           length (in bytes) in length, and a starting byte offset in startoffset.
2072           In UTF-8 mode, the byte offset must point to the start of a UTF-8 char-
2073           acter.  Unlike  the pattern string, the subject may contain binary zero
2074           bytes. When the starting offset is zero, the search for a match  starts
2075           at  the  beginning  of  the subject, and this is by far the most common
2076           case.
2078           A non-zero starting offset is useful when searching for  another  match
2079           in  the same subject by calling pcre_exec() again after a previous suc-
2080           cess.  Setting startoffset differs from just passing over  a  shortened
2081           string  and  setting  PCRE_NOTBOL  in the case of a pattern that begins
2082           with any kind of lookbehind. For example, consider the pattern
2084             \Biss\B
2086           which finds occurrences of "iss" in the middle of  words.  (\B  matches
2087           only  if  the  current position in the subject is not a word boundary.)
2088           When applied to the string "Mississipi" the first call  to  pcre_exec()
2089           finds  the  first  occurrence. If pcre_exec() is called again with just
2090           the remainder of the subject,  namely  "issipi",  it  does  not  match,
2091           because \B is always false at the start of the subject, which is deemed
2092           to be a word boundary. However, if pcre_exec()  is  passed  the  entire
2093           string again, but with startoffset set to 4, it finds the second occur-
2094           rence of "iss" because it is able to look behind the starting point  to
2095           discover that it is preceded by a letter.
2097           If  a  non-zero starting offset is passed when the pattern is anchored,
2098           one attempt to match at the given offset is made. This can only succeed
2099           if  the  pattern  does  not require the match to be at the start of the
2100           subject.
2102       How pcre_exec() returns captured substrings
2104           In general, a pattern matches a certain portion of the subject, and  in
2105           addition,  further  substrings  from  the  subject may be picked out by
2106           parts of the pattern. Following the usage  in  Jeffrey  Friedl's  book,
2107           this  is  called "capturing" in what follows, and the phrase "capturing
2108           subpattern" is used for a fragment of a pattern that picks out  a  sub-
2109           string.  PCRE  supports several other kinds of parenthesized subpattern
2110           that do not cause substrings to be captured.
2112           Captured substrings are returned to the caller via a vector of integers
2113           whose  address is passed in ovector. The number of elements in the vec-
2114           tor is passed in ovecsize, which must be a non-negative  number.  Note:
2115           this argument is NOT the size of ovector in bytes.
2117           The  first  two-thirds of the vector is used to pass back captured sub-
2118           strings, each substring using a pair of integers. The  remaining  third
2119           of  the  vector is used as workspace by pcre_exec() while matching cap-
2120           turing subpatterns, and is not available for passing back  information.
2121           The  number passed in ovecsize should always be a multiple of three. If
2122           it is not, it is rounded down.
2124           When a match is successful, information about  captured  substrings  is
2125           returned  in  pairs  of integers, starting at the beginning of ovector,
2126           and continuing up to two-thirds of its length at the  most.  The  first
2127           element  of  each pair is set to the byte offset of the first character
2128           in a substring, and the second is set to the byte offset of  the  first
2129           character  after  the end of a substring. Note: these values are always
2130           byte offsets, even in UTF-8 mode. They are not character counts.
2132           The first pair of integers, ovector[0]  and  ovector[1],  identify  the
2133           portion  of  the subject string matched by the entire pattern. The next
2134           pair is used for the first capturing subpattern, and so on.  The  value
2135           returned by pcre_exec() is one more than the highest numbered pair that
2136           has been set.  For example, if two substrings have been  captured,  the
2137           returned  value is 3. If there are no capturing subpatterns, the return
2138           value from a successful match is 1, indicating that just the first pair
2139           of offsets has been set.
2141           If a capturing subpattern is matched repeatedly, it is the last portion
2142           of the string that it matched that is returned.
2144           If the vector is too small to hold all the captured substring  offsets,
2145           it is used as far as possible (up to two-thirds of its length), and the
2146           function returns a value of zero. If the substring offsets are  not  of
2147           interest,  pcre_exec()  may  be  called with ovector passed as NULL and
2148           ovecsize as zero. However, if the pattern contains back references  and
2149           the  ovector is not big enough to remember the related substrings, PCRE
2150           has to get additional memory for use during matching. Thus it  is  usu-
2151           ally advisable to supply an ovector.
2153           The  pcre_info()  function  can  be used to find out how many capturing
2154           subpatterns there are in a compiled  pattern.  The  smallest  size  for
2155           ovector  that  will allow for n captured substrings, in addition to the
2156           offsets of the substring matched by the whole pattern, is (n+1)*3.
2158           It is possible for capturing subpattern number n+1 to match  some  part
2159           of the subject when subpattern n has not been used at all. For example,
2160           if the string "abc" is matched  against  the  pattern  (a|(z))(bc)  the
2161           return from the function is 4, and subpatterns 1 and 3 are matched, but
2162           2 is not. When this happens, both values in  the  offset  pairs  corre-
2163           sponding to unused subpatterns are set to -1.
2165           Offset  values  that correspond to unused subpatterns at the end of the
2166           expression are also set to -1. For example,  if  the  string  "abc"  is
2167           matched  against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are not
2168           matched. The return from the function is 2, because  the  highest  used
2169           capturing subpattern number is 1. However, you can refer to the offsets
2170           for the second and third capturing subpatterns if  you  wish  (assuming
2171           the vector is large enough, of course).
2173           Some  convenience  functions  are  provided for extracting the captured
2174           substrings as separate strings. These are described below.
2176       Error return values from pcre_exec()
2178           If pcre_exec() fails, it returns a negative number. The  following  are
2179           defined in the header file:
2181             PCRE_ERROR_NOMATCH        (-1)
2183           The subject string did not match the pattern.
2185             PCRE_ERROR_NULL           (-2)
2187           Either  code  or  subject  was  passed as NULL, or ovector was NULL and
2188           ovecsize was not zero.
2190             PCRE_ERROR_BADOPTION      (-3)
2192           An unrecognized bit was set in the options argument.
2194             PCRE_ERROR_BADMAGIC       (-4)
2196           PCRE stores a 4-byte "magic number" at the start of the compiled  code,
2197           to catch the case when it is passed a junk pointer and to detect when a
2198           pattern that was compiled in an environment of one endianness is run in
2199           an  environment  with the other endianness. This is the error that PCRE
2200           gives when the magic number is not present.
2202             PCRE_ERROR_UNKNOWN_OPCODE (-5)
2204           While running the pattern match, an unknown item was encountered in the
2205           compiled  pattern.  This  error  could be caused by a bug in PCRE or by
2206           overwriting of the compiled pattern.
2208             PCRE_ERROR_NOMEMORY       (-6)
2210           If a pattern contains back references, but the ovector that  is  passed
2211           to pcre_exec() is not big enough to remember the referenced substrings,
2212           PCRE gets a block of memory at the start of matching to  use  for  this
2213           purpose.  If the call via pcre_malloc() fails, this error is given. The
2214           memory is automatically freed at the end of matching.
2216             PCRE_ERROR_NOSUBSTRING    (-7)
2218           This error is used by the pcre_copy_substring(),  pcre_get_substring(),
2219           and  pcre_get_substring_list()  functions  (see  below).  It  is  never
2220           returned by pcre_exec().
2222             PCRE_ERROR_MATCHLIMIT     (-8)
2224           The backtracking limit, as specified by  the  match_limit  field  in  a
2225           pcre_extra  structure  (or  defaulted) was reached. See the description
2226           above.
2228             PCRE_ERROR_CALLOUT        (-9)
2230           This error is never generated by pcre_exec() itself. It is provided for
2231           use  by  callout functions that want to yield a distinctive error code.
2232           See the pcrecallout documentation for details.
2234             PCRE_ERROR_BADUTF8        (-10)
2236           A string that contains an invalid UTF-8 byte sequence was passed  as  a
2237           subject.
2239             PCRE_ERROR_BADUTF8_OFFSET (-11)
2241           The UTF-8 byte sequence that was passed as a subject was valid, but the
2242           value of startoffset did not point to the beginning of a UTF-8  charac-
2243           ter.
2245             PCRE_ERROR_PARTIAL        (-12)
2247           The  subject  string did not match, but it did match partially. See the
2248           pcrepartial documentation for details of partial matching.
2250             PCRE_ERROR_BADPARTIAL     (-13)
2252           The PCRE_PARTIAL option was used with  a  compiled  pattern  containing
2253           items  that are not supported for partial matching. See the pcrepartial
2254           documentation for details of partial matching.
2256             PCRE_ERROR_INTERNAL       (-14)
2258           An unexpected internal error has occurred. This error could  be  caused
2259           by a bug in PCRE or by overwriting of the compiled pattern.
2261             PCRE_ERROR_BADCOUNT       (-15)
2263           This error is given if the value of the ovecsize argument is negative.
2265             PCRE_ERROR_RECURSIONLIMIT (-21)
2267           The internal recursion limit, as specified by the match_limit_recursion
2268           field in a pcre_extra structure (or defaulted)  was  reached.  See  the
2269           description above.
2271             PCRE_ERROR_BADNEWLINE     (-23)
2273           An invalid combination of PCRE_NEWLINE_xxx options was given.
2275           Error numbers -16 to -20 and -22 are not used by pcre_exec().
2280           int pcre_copy_substring(const char *subject, int *ovector,
2281                int stringcount, int stringnumber, char *buffer,
2282                int buffersize);
2284           int pcre_get_substring(const char *subject, int *ovector,
2285                int stringcount, int stringnumber,
2286                const char **stringptr);
2288           int pcre_get_substring_list(const char *subject,
2289                int *ovector, int stringcount, const char ***listptr);
2291           Captured  substrings  can  be  accessed  directly  by using the offsets
2292           returned by pcre_exec() in  ovector.  For  convenience,  the  functions
2293           pcre_copy_substring(),    pcre_get_substring(),    and    pcre_get_sub-
2294           string_list() are provided for extracting captured substrings  as  new,
2295           separate,  zero-terminated strings. These functions identify substrings
2296           by number. The next section describes functions  for  extracting  named
2297           substrings.
2299           A  substring that contains a binary zero is correctly extracted and has
2300           a further zero added on the end, but the result is not, of course, a  C
2301           string.   However,  you  can  process such a string by referring to the
2302           length that is  returned  by  pcre_copy_substring()  and  pcre_get_sub-
2303           string().  Unfortunately, the interface to pcre_get_substring_list() is
2304           not adequate for handling strings containing binary zeros, because  the
2305           end of the final string is not independently indicated.
2307           The  first  three  arguments  are the same for all three of these func-
2308           tions: subject is the subject string that has  just  been  successfully
2309           matched, ovector is a pointer to the vector of integer offsets that was
2310           passed to pcre_exec(), and stringcount is the number of substrings that
2311           were  captured  by  the match, including the substring that matched the
2312           entire regular expression. This is the value returned by pcre_exec() if
2313           it  is greater than zero. If pcre_exec() returned zero, indicating that
2314           it ran out of space in ovector, the value passed as stringcount  should
2315           be the number of elements in the vector divided by three.
2317           The  functions pcre_copy_substring() and pcre_get_substring() extract a
2318           single substring, whose number is given as  stringnumber.  A  value  of
2319           zero  extracts  the  substring that matched the entire pattern, whereas
2320           higher values  extract  the  captured  substrings.  For  pcre_copy_sub-
2321           string(),  the  string  is  placed  in buffer, whose length is given by
2322           buffersize, while for pcre_get_substring() a new  block  of  memory  is
2323           obtained  via  pcre_malloc,  and its address is returned via stringptr.
2324           The yield of the function is the length of the  string,  not  including
2325           the terminating zero, or one of these error codes:
2327             PCRE_ERROR_NOMEMORY       (-6)
2329           The  buffer  was too small for pcre_copy_substring(), or the attempt to
2330           get memory failed for pcre_get_substring().
2332             PCRE_ERROR_NOSUBSTRING    (-7)
2334           There is no substring whose number is stringnumber.
2336           The pcre_get_substring_list()  function  extracts  all  available  sub-
2337           strings  and  builds  a list of pointers to them. All this is done in a
2338           single block of memory that is obtained via pcre_malloc. The address of
2339           the  memory  block  is returned via listptr, which is also the start of
2340           the list of string pointers. The end of the list is marked  by  a  NULL
2341           pointer.  The  yield  of  the function is zero if all went well, or the
2342           error code
2344             PCRE_ERROR_NOMEMORY       (-6)
2346           if the attempt to get the memory block failed.
2348           When any of these functions encounter a substring that is unset,  which
2349           can  happen  when  capturing subpattern number n+1 matches some part of
2350           the subject, but subpattern n has not been used at all, they return  an
2351           empty string. This can be distinguished from a genuine zero-length sub-
2352           string by inspecting the appropriate offset in ovector, which is  nega-
2353           tive for unset substrings.
2355           The  two convenience functions pcre_free_substring() and pcre_free_sub-
2356           string_list() can be used to free the memory  returned  by  a  previous
2357           call  of  pcre_get_substring()  or  pcre_get_substring_list(),  respec-
2358           tively. They do nothing more than  call  the  function  pointed  to  by
2359           pcre_free,  which  of course could be called directly from a C program.
2360           However, PCRE is used in some situations where it is linked via a  spe-
2361           cial   interface  to  another  programming  language  that  cannot  use
2362           pcre_free directly; it is for these cases that the functions  are  pro-
2363           vided.
2368           int pcre_get_stringnumber(const pcre *code,
2369                const char *name);
2371           int pcre_copy_named_substring(const pcre *code,
2372                const char *subject, int *ovector,
2373                int stringcount, const char *stringname,
2374                char *buffer, int buffersize);
2376           int pcre_get_named_substring(const pcre *code,
2377                const char *subject, int *ovector,
2378                int stringcount, const char *stringname,
2379                const char **stringptr);
2381           To  extract a substring by name, you first have to find associated num-
2382           ber.  For example, for this pattern
2384             (a+)b(?<xxx>\d+)...
2386           the number of the subpattern called "xxx" is 2. If the name is known to
2387           be unique (PCRE_DUPNAMES was not set), you can find the number from the
2388           name by calling pcre_get_stringnumber(). The first argument is the com-
2389           piled pattern, and the second is the name. The yield of the function is
2390           the subpattern number, or PCRE_ERROR_NOSUBSTRING (-7) if  there  is  no
2391           subpattern of that name.
2393           Given the number, you can extract the substring directly, or use one of
2394           the functions described in the previous section. For convenience, there
2395           are also two functions that do the whole job.
2397           Most    of    the    arguments   of   pcre_copy_named_substring()   and
2398           pcre_get_named_substring() are the same  as  those  for  the  similarly
2399           named  functions  that extract by number. As these are described in the
2400           previous section, they are not re-described here. There  are  just  two
2401           differences:
2403           First,  instead  of a substring number, a substring name is given. Sec-
2404           ond, there is an extra argument, given at the start, which is a pointer
2405           to  the compiled pattern. This is needed in order to gain access to the
2406           name-to-number translation table.
2408           These functions call pcre_get_stringnumber(), and if it succeeds,  they
2409           then  call  pcre_copy_substring() or pcre_get_substring(), as appropri-
2410           ate. NOTE: If PCRE_DUPNAMES is set and there are duplicate  names,  the
2411           behaviour may not be what you want (see the next section).
2413           Warning:  If the pattern uses the "(?|" feature to set up multiple sub-
2414           patterns with the same number, you  cannot  use  names  to  distinguish
2415           them, because names are not included in the compiled code. The matching
2416           process uses only numbers.
2421           int pcre_get_stringtable_entries(const pcre *code,
2422                const char *name, char **first, char **last);
2424           When a pattern is compiled with the  PCRE_DUPNAMES  option,  names  for
2425           subpatterns  are  not  required  to  be unique. Normally, patterns with
2426           duplicate names are such that in any one match, only one of  the  named
2427           subpatterns  participates. An example is shown in the pcrepattern docu-
2428           mentation.
2430           When   duplicates   are   present,   pcre_copy_named_substring()    and
2431           pcre_get_named_substring()  return the first substring corresponding to
2432           the given name that is set. If  none  are  set,  PCRE_ERROR_NOSUBSTRING
2433           (-7)  is  returned;  no  data  is returned. The pcre_get_stringnumber()
2434           function returns one of the numbers that are associated with the  name,
2435           but it is not defined which it is.
2437           If  you want to get full details of all captured substrings for a given
2438           name, you must use  the  pcre_get_stringtable_entries()  function.  The
2439           first argument is the compiled pattern, and the second is the name. The
2440           third and fourth are pointers to variables which  are  updated  by  the
2441           function. After it has run, they point to the first and last entries in
2442           the name-to-number table  for  the  given  name.  The  function  itself
2443           returns  the  length  of  each entry, or PCRE_ERROR_NOSUBSTRING (-7) if
2444           there are none. The format of the table is described above in the  sec-
2445           tion  entitled  Information  about  a  pattern.  Given all the relevant
2446           entries for the name, you can extract each of their numbers, and  hence
2447           the captured data, if any.
2452           The  traditional  matching  function  uses a similar algorithm to Perl,
2453           which stops when it finds the first match, starting at a given point in
2454           the  subject.  If you want to find all possible matches, or the longest
2455           possible match, consider using the alternative matching  function  (see
2456           below)  instead.  If you cannot use the alternative function, but still
2457           need to find all possible matches, you can kludge it up by  making  use
2458           of the callout facility, which is described in the pcrecallout documen-
2459           tation.
2461           What you have to do is to insert a callout right at the end of the pat-
2462           tern.   When your callout function is called, extract and save the cur-
2463           rent matched substring. Then return  1,  which  forces  pcre_exec()  to
2464           backtrack  and  try other alternatives. Ultimately, when it runs out of
2465           matches, pcre_exec() will yield PCRE_ERROR_NOMATCH.
2470           int pcre_dfa_exec(const pcre *code, const pcre_extra *extra,
2471                const char *subject, int length, int startoffset,
2472                int options, int *ovector, int ovecsize,
2473                int *workspace, int wscount);
2475           The function pcre_dfa_exec()  is  called  to  match  a  subject  string
2476           against  a  compiled pattern, using a matching algorithm that scans the
2477           subject string just once, and does not backtrack.  This  has  different
2478           characteristics  to  the  normal  algorithm, and is not compatible with
2479           Perl. Some of the features of PCRE patterns are not  supported.  Never-
2480           theless,  there are times when this kind of matching can be useful. For
2481           a discussion of the two matching algorithms, see the pcrematching docu-
2482           mentation.
2484           The  arguments  for  the  pcre_dfa_exec()  function are the same as for
2485           pcre_exec(), plus two extras. The ovector argument is used in a differ-
2486           ent  way,  and  this is described below. The other common arguments are
2487           used in the same way as for pcre_exec(), so their  description  is  not
2488           repeated here.
2490           The  two  additional  arguments provide workspace for the function. The
2491           workspace vector should contain at least 20 elements. It  is  used  for
2492           keeping  track  of  multiple  paths  through  the  pattern  tree.  More
2493           workspace will be needed for patterns and subjects where  there  are  a
2494           lot of potential matches.
2496           Here is an example of a simple call to pcre_dfa_exec():
2498             int rc;
2499             int ovector[10];
2500             int wspace[20];
2501             rc = pcre_dfa_exec(
2502               re,             /* result of pcre_compile() */
2503               NULL,           /* we didn't study the pattern */
2504               "some string",  /* the subject string */
2505               11,             /* the length of the subject string */
2506               0,              /* start at offset 0 in the subject */
2507               0,              /* default options */
2508               ovector,        /* vector of integers for substring information */
2509               10,             /* number of elements (NOT size in bytes) */
2510               wspace,         /* working space vector */
2511               20);            /* number of elements (NOT size in bytes) */
2513       Option bits for pcre_dfa_exec()
2515           The  unused  bits  of  the options argument for pcre_dfa_exec() must be
2516           zero. The only bits  that  may  be  set  are  PCRE_ANCHORED,  PCRE_NEW-
2518           PCRE_PARTIAL, PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART. All but the last
2519           three of these are the same as for pcre_exec(), so their description is
2520           not repeated here.
2522             PCRE_PARTIAL
2524           This has the same general effect as it does for  pcre_exec(),  but  the
2525           details   are   slightly   different.  When  PCRE_PARTIAL  is  set  for
2526           pcre_dfa_exec(), the return code PCRE_ERROR_NOMATCH is  converted  into
2527           PCRE_ERROR_PARTIAL  if  the  end  of the subject is reached, there have
2528           been no complete matches, but there is still at least one matching pos-
2529           sibility.  The portion of the string that provided the partial match is
2530           set as the first matching string.
2532             PCRE_DFA_SHORTEST
2534           Setting the PCRE_DFA_SHORTEST option causes the matching  algorithm  to
2535           stop as soon as it has found one match. Because of the way the alterna-
2536           tive algorithm works, this is necessarily the shortest  possible  match
2537           at the first possible matching point in the subject string.
2539             PCRE_DFA_RESTART
2541           When  pcre_dfa_exec()  is  called  with  the  PCRE_PARTIAL  option, and
2542           returns a partial match, it is possible to call it  again,  with  addi-
2543           tional  subject  characters,  and have it continue with the same match.
2544           The PCRE_DFA_RESTART option requests this action; when it is  set,  the
2545           workspace  and wscount options must reference the same vector as before
2546           because data about the match so far is left in  them  after  a  partial
2547           match.  There  is  more  discussion of this facility in the pcrepartial
2548           documentation.
2550       Successful returns from pcre_dfa_exec()
2552           When pcre_dfa_exec() succeeds, it may have matched more than  one  sub-
2553           string in the subject. Note, however, that all the matches from one run
2554           of the function start at the same point in  the  subject.  The  shorter
2555           matches  are all initial substrings of the longer matches. For example,
2556           if the pattern
2558             <.*>
2560           is matched against the string
2562             This is <something> <something else> <something further> no more
2564           the three matched strings are
2566             <something>
2567             <something> <something else>
2568             <something> <something else> <something further>
2570           On success, the yield of the function is a number  greater  than  zero,
2571           which  is  the  number of matched substrings. The substrings themselves
2572           are returned in ovector. Each string uses two elements;  the  first  is
2573           the  offset  to  the start, and the second is the offset to the end. In
2574           fact, all the strings have the same start  offset.  (Space  could  have
2575           been  saved by giving this only once, but it was decided to retain some
2576           compatibility with the way pcre_exec() returns data,  even  though  the
2577           meaning of the strings is different.)
2579           The strings are returned in reverse order of length; that is, the long-
2580           est matching string is given first. If there were too many  matches  to
2581           fit  into ovector, the yield of the function is zero, and the vector is
2582           filled with the longest matches.
2584       Error returns from pcre_dfa_exec()
2586           The pcre_dfa_exec() function returns a negative number when  it  fails.
2587           Many  of  the  errors  are  the  same as for pcre_exec(), and these are
2588           described above.  There are in addition the following errors  that  are
2589           specific to pcre_dfa_exec():
2591             PCRE_ERROR_DFA_UITEM      (-16)
2593           This  return is given if pcre_dfa_exec() encounters an item in the pat-
2594           tern that it does not support, for instance, the use of \C  or  a  back
2595           reference.
2597             PCRE_ERROR_DFA_UCOND      (-17)
2599           This  return  is  given  if pcre_dfa_exec() encounters a condition item
2600           that uses a back reference for the condition, or a test  for  recursion
2601           in a specific group. These are not supported.
2603             PCRE_ERROR_DFA_UMLIMIT    (-18)
2605           This  return  is given if pcre_dfa_exec() is called with an extra block
2606           that contains a setting of the match_limit field. This is not supported
2607           (it is meaningless).
2609             PCRE_ERROR_DFA_WSSIZE     (-19)
2611           This  return  is  given  if  pcre_dfa_exec()  runs  out of space in the
2612           workspace vector.
2614             PCRE_ERROR_DFA_RECURSE    (-20)
2616           When a recursive subpattern is processed, the matching  function  calls
2617           itself  recursively,  using  private vectors for ovector and workspace.
2618           This error is given if the output vector  is  not  large  enough.  This
2619           should be extremely rare, as a vector of size 1000 is used.
2622    SEE ALSO
2624           pcrebuild(3),  pcrecallout(3), pcrecpp(3)(3), pcrematching(3), pcrepar-
2625           tial(3), pcreposix(3), pcreprecompile(3), pcresample(3), pcrestack(3).
2628    AUTHOR
2630           Philip Hazel
2631           University Computing Service
2632           Cambridge CB2 3QH, England.
2635    REVISION
2637           Last updated: 17 March 2009
2638           Copyright (c) 1997-2009 University of Cambridge.
2639    ------------------------------------------------------------------------------
2642    PCRECALLOUT(3)                                                  PCRECALLOUT(3)
2645    NAME
2646           PCRE - Perl-compatible regular expressions
2651           int (*pcre_callout)(pcre_callout_block *);
2653           PCRE provides a feature called "callout", which is a means of temporar-
2654           ily passing control to the caller of PCRE  in  the  middle  of  pattern
2655           matching.  The  caller of PCRE provides an external function by putting
2656           its entry point in the global variable pcre_callout. By  default,  this
2657           variable contains NULL, which disables all calling out.
2659           Within  a  regular  expression,  (?C) indicates the points at which the
2660           external function is to be called.  Different  callout  points  can  be
2661           identified  by  putting  a number less than 256 after the letter C. The
2662           default value is zero.  For  example,  this  pattern  has  two  callout
2663           points:
2665             (?C1)abc(?C2)def
2667           If  the  PCRE_AUTO_CALLOUT  option  bit  is  set when pcre_compile() is
2668           called, PCRE automatically  inserts  callouts,  all  with  number  255,
2669           before  each  item in the pattern. For example, if PCRE_AUTO_CALLOUT is
2670           used with the pattern
2672             A(\d{2}|--)
2674           it is processed as if it were
2676           (?C255)A(?C255)((?C255)\d{2}(?C255)|(?C255)-(?C255)-(?C255))(?C255)
2678           Notice that there is a callout before and after  each  parenthesis  and
2679           alternation  bar.  Automatic  callouts  can  be  used  for tracking the
2680           progress of pattern matching. The pcretest command has an  option  that
2681           sets  automatic callouts; when it is used, the output indicates how the
2682           pattern is matched. This is useful information when you are  trying  to
2683           optimize the performance of a particular pattern.
2688           You  should  be  aware  that,  because of optimizations in the way PCRE
2689           matches patterns by default, callouts  sometimes  do  not  happen.  For
2690           example, if the pattern is
2692             ab(?C4)cd
2694           PCRE knows that any matching string must contain the letter "d". If the
2695           subject string is "abyz", the lack of "d" means that  matching  doesn't
2696           ever  start,  and  the  callout is never reached. However, with "abyd",
2697           though the result is still no match, the callout is obeyed.
2699           You can disable these optimizations by passing the  PCRE_NO_START_OPTI-
2700           MIZE  option  to  pcre_exec()  or  pcre_dfa_exec(). This slows down the
2701           matching process, but does ensure that callouts  such  as  the  example
2702           above are obeyed.
2707           During  matching, when PCRE reaches a callout point, the external func-
2708           tion defined by pcre_callout is called (if it is set). This applies  to
2709           both  the  pcre_exec()  and the pcre_dfa_exec() matching functions. The
2710           only argument to the callout function is a pointer  to  a  pcre_callout
2711           block. This structure contains the following fields:
2713             int          version;
2714             int          callout_number;
2715             int         *offset_vector;
2716             const char  *subject;
2717             int          subject_length;
2718             int          start_match;
2719             int          current_position;
2720             int          capture_top;
2721             int          capture_last;
2722             void        *callout_data;
2723             int          pattern_position;
2724             int          next_item_length;
2726           The  version  field  is an integer containing the version number of the
2727           block format. The initial version was 0; the current version is 1.  The
2728           version  number  will  change  again in future if additional fields are
2729           added, but the intention is never to remove any of the existing fields.
2731           The callout_number field contains the number of the  callout,  as  com-
2732           piled  into  the pattern (that is, the number after ?C for manual call-
2733           outs, and 255 for automatically generated callouts).
2735           The offset_vector field is a pointer to the vector of offsets that  was
2736           passed   by   the   caller  to  pcre_exec()  or  pcre_dfa_exec().  When
2737           pcre_exec() is used, the contents can be inspected in order to  extract
2738           substrings  that  have  been  matched  so  far,  in the same way as for
2739           extracting substrings after a match has completed. For  pcre_dfa_exec()
2740           this field is not useful.
2742           The subject and subject_length fields contain copies of the values that
2743           were passed to pcre_exec().
2745           The start_match field normally contains the offset within  the  subject
2746           at  which  the  current  match  attempt started. However, if the escape
2747           sequence \K has been encountered, this value is changed to reflect  the
2748           modified  starting  point.  If the pattern is not anchored, the callout
2749           function may be called several times from the same point in the pattern
2750           for different starting points in the subject.
2752           The  current_position  field  contains the offset within the subject of
2753           the current match pointer.
2755           When the pcre_exec() function is used, the capture_top  field  contains
2756           one  more than the number of the highest numbered captured substring so
2757           far. If no substrings have been captured, the value of  capture_top  is
2758           one.  This  is always the case when pcre_dfa_exec() is used, because it
2759           does not support captured substrings.
2761           The capture_last field contains the number of the  most  recently  cap-
2762           tured  substring. If no substrings have been captured, its value is -1.
2763           This is always the case when pcre_dfa_exec() is used.
2765           The callout_data field contains a value that is passed  to  pcre_exec()
2766           or  pcre_dfa_exec() specifically so that it can be passed back in call-
2767           outs. It is passed in the pcre_callout field  of  the  pcre_extra  data
2768           structure.  If  no such data was passed, the value of callout_data in a
2769           pcre_callout block is NULL. There is a description  of  the  pcre_extra
2770           structure in the pcreapi documentation.
2772           The  pattern_position field is present from version 1 of the pcre_call-
2773           out structure. It contains the offset to the next item to be matched in
2774           the pattern string.
2776           The  next_item_length field is present from version 1 of the pcre_call-
2777           out structure. It contains the length of the next item to be matched in
2778           the  pattern  string. When the callout immediately precedes an alterna-
2779           tion bar, a closing parenthesis, or the end of the pattern, the  length
2780           is  zero.  When the callout precedes an opening parenthesis, the length
2781           is that of the entire subpattern.
2783           The pattern_position and next_item_length fields are intended  to  help
2784           in  distinguishing between different automatic callouts, which all have
2785           the same callout number. However, they are set for all callouts.
2790           The external callout function returns an integer to PCRE. If the  value
2791           is  zero,  matching  proceeds  as  normal. If the value is greater than
2792           zero, matching fails at the current point, but  the  testing  of  other
2793           matching possibilities goes ahead, just as if a lookahead assertion had
2794           failed. If the value is less than zero, the  match  is  abandoned,  and
2795           pcre_exec() (or pcre_dfa_exec()) returns the negative value.
2797           Negative   values   should   normally   be   chosen  from  the  set  of
2798           PCRE_ERROR_xxx values. In particular, PCRE_ERROR_NOMATCH forces a stan-
2799           dard  "no  match"  failure.   The  error  number  PCRE_ERROR_CALLOUT is
2800           reserved for use by callout functions; it will never be  used  by  PCRE
2801           itself.
2804    AUTHOR
2806           Philip Hazel
2807           University Computing Service
2808           Cambridge CB2 3QH, England.
2811    REVISION
2813           Last updated: 15 March 2009
2814           Copyright (c) 1997-2009 University of Cambridge.
2815    ------------------------------------------------------------------------------
2818    PCRECOMPAT(3)                                                    PCRECOMPAT(3)
2821    NAME
2822           PCRE - Perl-compatible regular expressions
2827           This  document describes the differences in the ways that PCRE and Perl
2828           handle regular expressions. The differences described here  are  mainly
2829           with  respect  to  Perl 5.8, though PCRE versions 7.0 and later contain
2830           some features that are expected to be in the forthcoming Perl 5.10.
2832           1. PCRE has only a subset of Perl's UTF-8 and Unicode support.  Details
2833           of  what  it does have are given in the section on UTF-8 support in the
2834           main pcre page.
2836           2. PCRE does not allow repeat quantifiers on lookahead assertions. Perl
2837           permits  them,  but they do not mean what you might think. For example,
2838           (?!a){3} does not assert that the next three characters are not "a". It
2839           just asserts that the next character is not "a" three times.
2841           3.  Capturing  subpatterns  that occur inside negative lookahead asser-
2842           tions are counted, but their entries in the offsets  vector  are  never
2843           set.  Perl sets its numerical variables from any such patterns that are
2844           matched before the assertion fails to match something (thereby succeed-
2845           ing),  but  only  if the negative lookahead assertion contains just one
2846           branch.
2848           4. Though binary zero characters are supported in the  subject  string,
2849           they are not allowed in a pattern string because it is passed as a nor-
2850           mal C string, terminated by zero. The escape sequence \0 can be used in
2851           the pattern to represent a binary zero.
2853           5.  The  following Perl escape sequences are not supported: \l, \u, \L,
2854           \U, and \N. In fact these are implemented by Perl's general string-han-
2855           dling  and are not part of its pattern matching engine. If any of these
2856           are encountered by PCRE, an error is generated.
2858           6. The Perl escape sequences \p, \P, and \X are supported only if  PCRE
2859           is  built  with Unicode character property support. The properties that
2860           can be tested with \p and \P are limited to the general category  prop-
2861           erties  such  as  Lu and Nd, script names such as Greek or Han, and the
2862           derived properties Any and L&.
2864           7. PCRE does support the \Q...\E escape for quoting substrings. Charac-
2865           ters  in  between  are  treated as literals. This is slightly different
2866           from Perl in that $ and @ are  also  handled  as  literals  inside  the
2867           quotes.  In Perl, they cause variable interpolation (but of course PCRE
2868           does not have variables). Note the following examples:
2870               Pattern            PCRE matches      Perl matches
2872               \Qabc$xyz\E        abc$xyz           abc followed by the
2873                                                      contents of $xyz
2874               \Qabc\$xyz\E       abc\$xyz          abc\$xyz
2875               \Qabc\E\$\Qxyz\E   abc$xyz           abc$xyz
2877           The \Q...\E sequence is recognized both inside  and  outside  character
2878           classes.
2880           8. Fairly obviously, PCRE does not support the (?{code}) and (??{code})
2881           constructions. However, there is support for recursive  patterns.  This
2882           is  not available in Perl 5.8, but will be in Perl 5.10. Also, the PCRE
2883           "callout" feature allows an external function to be called during  pat-
2884           tern matching. See the pcrecallout documentation for details.
2886           9.  Subpatterns  that  are  called  recursively or as "subroutines" are
2887           always treated as atomic groups in  PCRE.  This  is  like  Python,  but
2888           unlike Perl.
2890           10.  There are some differences that are concerned with the settings of
2891           captured strings when part of  a  pattern  is  repeated.  For  example,
2892           matching  "aba"  against  the  pattern  /^(a(b)?)+$/  in Perl leaves $2
2893           unset, but in PCRE it is set to "b".
2895           11.  PCRE  does  support  Perl  5.10's  backtracking  verbs  (*ACCEPT),
2896           (*FAIL),  (*F),  (*COMMIT), (*PRUNE), (*SKIP), and (*THEN), but only in
2897           the forms without an  argument.  PCRE  does  not  support  (*MARK).  If
2898           (*ACCEPT)  is within capturing parentheses, PCRE does not set that cap-
2899           ture group; this is different to Perl.
2901           12. PCRE provides some extensions to the Perl regular expression facil-
2902           ities.   Perl  5.10  will  include new features that are not in earlier
2903           versions, some of which (such as named parentheses) have been  in  PCRE
2904           for some time. This list is with respect to Perl 5.10:
2906           (a)  Although  lookbehind  assertions  must match fixed length strings,
2907           each alternative branch of a lookbehind assertion can match a different
2908           length of string. Perl requires them all to have the same length.
2910           (b)  If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $
2911           meta-character matches only at the very end of the string.
2913           (c) If PCRE_EXTRA is set, a backslash followed by a letter with no spe-
2914           cial meaning is faulted. Otherwise, like Perl, the backslash is quietly
2915           ignored.  (Perl can be made to issue a warning.)
2917           (d) If PCRE_UNGREEDY is set, the greediness of the  repetition  quanti-
2918           fiers is inverted, that is, by default they are not greedy, but if fol-
2919           lowed by a question mark they are.
2921           (e) PCRE_ANCHORED can be used at matching time to force a pattern to be
2922           tried only at the first matching position in the subject string.
2925           TURE options for pcre_exec() have no Perl equivalents.
2927           (g) The \R escape sequence can be restricted to match only CR,  LF,  or
2928           CRLF by the PCRE_BSR_ANYCRLF option.
2930           (h) The callout facility is PCRE-specific.
2932           (i) The partial matching facility is PCRE-specific.
2934           (j) Patterns compiled by PCRE can be saved and re-used at a later time,
2935           even on different hosts that have the other endianness.
2937           (k) The alternative matching function (pcre_dfa_exec())  matches  in  a
2938           different way and is not Perl-compatible.
2940           (l)  PCRE  recognizes some special sequences such as (*CR) at the start
2941           of a pattern that set overall options that cannot be changed within the
2942           pattern.
2945    AUTHOR
2947           Philip Hazel
2948           University Computing Service
2949           Cambridge CB2 3QH, England.
2952    REVISION
2954           Last updated: 11 September 2007
2955           Copyright (c) 1997-2007 University of Cambridge.
2956    ------------------------------------------------------------------------------
2959    PCREPATTERN(3)                                                  PCREPATTERN(3)
2962    NAME
2963           PCRE - Perl-compatible regular expressions
2968           The  syntax and semantics of the regular expressions that are supported
2969           by PCRE are described in detail below. There is a quick-reference  syn-
2970           tax summary in the pcresyntax page. PCRE tries to match Perl syntax and
2971           semantics as closely as it can. PCRE  also  supports  some  alternative
2972           regular  expression  syntax (which does not conflict with the Perl syn-
2973           tax) in order to provide some compatibility with regular expressions in
2974           Python, .NET, and Oniguruma.
2976           Perl's  regular expressions are described in its own documentation, and
2977           regular expressions in general are covered in a number of  books,  some
2978           of  which  have  copious  examples. Jeffrey Friedl's "Mastering Regular
2979           Expressions", published by  O'Reilly,  covers  regular  expressions  in
2980           great  detail.  This  description  of  PCRE's  regular  expressions  is
2981           intended as reference material.
2983           The original operation of PCRE was on strings of  one-byte  characters.
2984           However,  there is now also support for UTF-8 character strings. To use
2985           this, you must build PCRE to  include  UTF-8  support,  and  then  call
2986           pcre_compile()  with  the  PCRE_UTF8  option.  How this affects pattern
2987           matching is mentioned in several places below. There is also a  summary
2988           of  UTF-8  features  in  the  section on UTF-8 support in the main pcre
2989           page.
2991           The remainder of this document discusses the  patterns  that  are  sup-
2992           ported  by  PCRE when its main matching function, pcre_exec(), is used.
2993           From  release  6.0,   PCRE   offers   a   second   matching   function,
2994           pcre_dfa_exec(),  which matches using a different algorithm that is not
2995           Perl-compatible. Some of the features discussed below are not available
2996           when  pcre_dfa_exec()  is used. The advantages and disadvantages of the
2997           alternative function, and how it differs from the normal function,  are
2998           discussed in the pcrematching page.
3003           PCRE  supports five different conventions for indicating line breaks in
3004           strings: a single CR (carriage return) character, a  single  LF  (line-
3005           feed) character, the two-character sequence CRLF, any of the three pre-
3006           ceding, or any Unicode newline sequence. The pcreapi page  has  further
3007           discussion  about newlines, and shows how to set the newline convention
3008           in the options arguments for the compiling and matching functions.
3010           It is also possible to specify a newline convention by starting a  pat-
3011           tern string with one of the following five sequences:
3013             (*CR)        carriage return
3014             (*LF)        linefeed
3015             (*CRLF)      carriage return, followed by linefeed
3016             (*ANYCRLF)   any of the three above
3017             (*ANY)       all Unicode newline sequences
3019           These override the default and the options given to pcre_compile(). For
3020           example, on a Unix system where LF is the default newline sequence, the
3021           pattern
3023             (*CR)a.b
3025           changes the convention to CR. That pattern matches "a\nb" because LF is
3026           no longer a newline. Note that these special settings,  which  are  not
3027           Perl-compatible,  are  recognized  only at the very start of a pattern,
3028           and that they must be in upper case.  If  more  than  one  of  them  is
3029           present, the last one is used.
3031           The  newline  convention  does  not  affect what the \R escape sequence
3032           matches. By default, this is any Unicode  newline  sequence,  for  Perl
3033           compatibility.  However, this can be changed; see the description of \R
3034           in the section entitled "Newline sequences" below. A change of \R  set-
3035           ting can be combined with a change of newline convention.
3040           A  regular  expression  is  a pattern that is matched against a subject
3041           string from left to right. Most characters stand for  themselves  in  a
3042           pattern,  and  match  the corresponding characters in the subject. As a
3043           trivial example, the pattern
3045             The quick brown fox
3047           matches a portion of a subject string that is identical to itself. When
3048           caseless  matching is specified (the PCRE_CASELESS option), letters are
3049           matched independently of case. In UTF-8 mode, PCRE  always  understands
3050           the  concept  of case for characters whose values are less than 128, so
3051           caseless matching is always possible. For characters with  higher  val-
3052           ues,  the concept of case is supported if PCRE is compiled with Unicode
3053           property support, but not otherwise.   If  you  want  to  use  caseless
3054           matching  for  characters  128  and above, you must ensure that PCRE is
3055           compiled with Unicode property support as well as with UTF-8 support.
3057           The power of regular expressions comes  from  the  ability  to  include
3058           alternatives  and  repetitions in the pattern. These are encoded in the
3059           pattern by the use of metacharacters, which do not stand for themselves
3060           but instead are interpreted in some special way.
3062           There  are  two different sets of metacharacters: those that are recog-
3063           nized anywhere in the pattern except within square brackets, and  those
3064           that  are  recognized  within square brackets. Outside square brackets,
3065           the metacharacters are as follows:
3067             \      general escape character with several uses
3068             ^      assert start of string (or line, in multiline mode)
3069             $      assert end of string (or line, in multiline mode)
3070             .      match any character except newline (by default)
3071             [      start character class definition
3072             |      start of alternative branch
3073             (      start subpattern
3074             )      end subpattern
3075             ?      extends the meaning of (
3076                    also 0 or 1 quantifier
3077                    also quantifier minimizer
3078             *      0 or more quantifier
3079             +      1 or more quantifier
3080                    also "possessive quantifier"
3081             {      start min/max quantifier
3083           Part of a pattern that is in square brackets  is  called  a  "character
3084           class". In a character class the only metacharacters are:
3086             \      general escape character
3087             ^      negate the class, but only if the first character
3088             -      indicates character range
3089             [      POSIX character class (only if followed by POSIX
3090                      syntax)
3091             ]      terminates the character class
3093           The following sections describe the use of each of the metacharacters.
3098           The backslash character has several uses. Firstly, if it is followed by
3099           a non-alphanumeric character, it takes away any  special  meaning  that
3100           character  may  have.  This  use  of  backslash  as an escape character
3101           applies both inside and outside character classes.
3103           For example, if you want to match a * character, you write  \*  in  the
3104           pattern.   This  escaping  action  applies whether or not the following
3105           character would otherwise be interpreted as a metacharacter, so  it  is
3106           always  safe  to  precede  a non-alphanumeric with backslash to specify
3107           that it stands for itself. In particular, if you want to match a  back-
3108           slash, you write \\.
3110           If  a  pattern is compiled with the PCRE_EXTENDED option, whitespace in
3111           the pattern (other than in a character class) and characters between  a
3112           # outside a character class and the next newline are ignored. An escap-
3113           ing backslash can be used to include a whitespace  or  #  character  as
3114           part of the pattern.
3116           If  you  want  to remove the special meaning from a sequence of charac-
3117           ters, you can do so by putting them between \Q and \E. This is  differ-
3118           ent  from  Perl  in  that  $  and  @ are handled as literals in \Q...\E
3119           sequences in PCRE, whereas in Perl, $ and @ cause  variable  interpola-
3120           tion. Note the following examples:
3122             Pattern            PCRE matches   Perl matches
3124             \Qabc$xyz\E        abc$xyz        abc followed by the
3125                                                 contents of $xyz
3126             \Qabc\$xyz\E       abc\$xyz       abc\$xyz
3127             \Qabc\E\$\Qxyz\E   abc$xyz        abc$xyz
3129           The  \Q...\E  sequence  is recognized both inside and outside character
3130           classes.
3132       Non-printing characters
3134           A second use of backslash provides a way of encoding non-printing char-
3135           acters  in patterns in a visible manner. There is no restriction on the
3136           appearance of non-printing characters, apart from the binary zero  that
3137           terminates  a  pattern,  but  when  a pattern is being prepared by text
3138           editing, it is usually easier  to  use  one  of  the  following  escape
3139           sequences than the binary character it represents:
3141             \a        alarm, that is, the BEL character (hex 07)
3142             \cx       "control-x", where x is any character
3143             \e        escape (hex 1B)
3144             \f        formfeed (hex 0C)
3145             \n        linefeed (hex 0A)
3146             \r        carriage return (hex 0D)
3147             \t        tab (hex 09)
3148             \ddd      character with octal code ddd, or backreference
3149             \xhh      character with hex code hh
3150             \x{hhh..} character with hex code hhh..
3152           The  precise  effect of \cx is as follows: if x is a lower case letter,
3153           it is converted to upper case. Then bit 6 of the character (hex 40)  is
3154           inverted.   Thus  \cz becomes hex 1A, but \c{ becomes hex 3B, while \c;
3155           becomes hex 7B.
3157           After \x, from zero to two hexadecimal digits are read (letters can  be
3158           in  upper  or  lower case). Any number of hexadecimal digits may appear
3159           between \x{ and }, but the value of the character  code  must  be  less
3160           than 256 in non-UTF-8 mode, and less than 2**31 in UTF-8 mode. That is,
3161           the maximum value in hexadecimal is 7FFFFFFF. Note that this is  bigger
3162           than the largest Unicode code point, which is 10FFFF.
3164           If  characters  other than hexadecimal digits appear between \x{ and },
3165           or if there is no terminating }, this form of escape is not recognized.
3166           Instead,  the  initial  \x  will  be interpreted as a basic hexadecimal
3167           escape, with no following digits, giving a  character  whose  value  is
3168           zero.
3170           Characters whose value is less than 256 can be defined by either of the
3171           two syntaxes for \x. There is no difference in the way  they  are  han-
3172           dled. For example, \xdc is exactly the same as \x{dc}.
3174           After  \0  up  to two further octal digits are read. If there are fewer
3175           than two digits, just  those  that  are  present  are  used.  Thus  the
3176           sequence \0\x\07 specifies two binary zeros followed by a BEL character
3177           (code value 7). Make sure you supply two digits after the initial  zero
3178           if the pattern character that follows is itself an octal digit.
3180           The handling of a backslash followed by a digit other than 0 is compli-
3181           cated.  Outside a character class, PCRE reads it and any following dig-
3182           its  as  a  decimal  number. If the number is less than 10, or if there
3183           have been at least that many previous capturing left parentheses in the
3184           expression,  the  entire  sequence  is  taken  as  a  back reference. A
3185           description of how this works is given later, following the  discussion
3186           of parenthesized subpatterns.
3188           Inside  a  character  class, or if the decimal number is greater than 9
3189           and there have not been that many capturing subpatterns, PCRE  re-reads
3190           up to three octal digits following the backslash, and uses them to gen-
3191           erate a data character. Any subsequent digits stand for themselves.  In
3192           non-UTF-8  mode,  the  value  of a character specified in octal must be
3193           less than \400. In UTF-8 mode, values up to  \777  are  permitted.  For
3194           example:
3196             \040   is another way of writing a space
3197             \40    is the same, provided there are fewer than 40
3198                       previous capturing subpatterns
3199             \7     is always a back reference
3200             \11    might be a back reference, or another way of
3201                       writing a tab
3202             \011   is always a tab
3203             \0113  is a tab followed by the character "3"
3204             \113   might be a back reference, otherwise the
3205                       character with octal code 113
3206             \377   might be a back reference, otherwise
3207                       the byte consisting entirely of 1 bits
3208             \81    is either a back reference, or a binary zero
3209                       followed by the two characters "8" and "1"
3211           Note  that  octal  values of 100 or greater must not be introduced by a
3212           leading zero, because no more than three octal digits are ever read.
3214           All the sequences that define a single character value can be used both
3215           inside  and  outside character classes. In addition, inside a character
3216           class, the sequence \b is interpreted as the backspace  character  (hex
3217           08),  and the sequences \R and \X are interpreted as the characters "R"
3218           and "X", respectively. Outside a character class, these sequences  have
3219           different meanings (see below).
3221       Absolute and relative back references
3223           The  sequence  \g followed by an unsigned or a negative number, option-
3224           ally enclosed in braces, is an absolute or relative back  reference.  A
3225           named back reference can be coded as \g{name}. Back references are dis-
3226           cussed later, following the discussion of parenthesized subpatterns.
3228       Absolute and relative subroutine calls
3230           For compatibility with Oniguruma, the non-Perl syntax \g followed by  a
3231           name or a number enclosed either in angle brackets or single quotes, is
3232           an alternative syntax for referencing a subpattern as  a  "subroutine".
3233           Details  are  discussed  later.   Note  that  \g{...} (Perl syntax) and
3234           \g<...> (Oniguruma syntax) are not synonymous. The  former  is  a  back
3235           reference; the latter is a subroutine call.
3237       Generic character types
3239           Another use of backslash is for specifying generic character types. The
3240           following are always recognized:
3242             \d     any decimal digit
3243             \D     any character that is not a decimal digit
3244             \h     any horizontal whitespace character
3245             \H     any character that is not a horizontal whitespace character
3246             \s     any whitespace character
3247             \S     any character that is not a whitespace character
3248             \v     any vertical whitespace character
3249             \V     any character that is not a vertical whitespace character
3250             \w     any "word" character
3251             \W     any "non-word" character
3253           Each pair of escape sequences partitions the complete set of characters
3254           into  two disjoint sets. Any given character matches one, and only one,
3255           of each pair.
3257           These character type sequences can appear both inside and outside char-
3258           acter  classes.  They each match one character of the appropriate type.
3259           If the current matching point is at the end of the subject string,  all
3260           of them fail, since there is no character to match.
3262           For  compatibility  with Perl, \s does not match the VT character (code
3263           11).  This makes it different from the the POSIX "space" class. The  \s
3264           characters  are  HT  (9), LF (10), FF (12), CR (13), and space (32). If
3265           "use locale;" is included in a Perl script, \s may match the VT charac-
3266           ter. In PCRE, it never does.
3268           In  UTF-8 mode, characters with values greater than 128 never match \d,
3269           \s, or \w, and always match \D, \S, and \W. This is true even when Uni-
3270           code  character  property  support is available. These sequences retain
3271           their original meanings from before UTF-8 support was available, mainly
3272           for  efficiency  reasons. Note that this also affects \b, because it is
3273           defined in terms of \w and \W.
3275           The sequences \h, \H, \v, and \V are Perl 5.10 features. In contrast to
3276           the  other  sequences, these do match certain high-valued codepoints in
3277           UTF-8 mode.  The horizontal space characters are:
3279             U+0009     Horizontal tab
3280             U+0020     Space
3281             U+00A0     Non-break space
3282             U+1680     Ogham space mark
3283             U+180E     Mongolian vowel separator
3284             U+2000     En quad
3285             U+2001     Em quad
3286             U+2002     En space
3287             U+2003     Em space
3288             U+2004     Three-per-em space
3289             U+2005     Four-per-em space
3290             U+2006     Six-per-em space
3291             U+2007     Figure space
3292             U+2008     Punctuation space
3293             U+2009     Thin space
3294             U+200A     Hair space
3295             U+202F     Narrow no-break space
3296             U+205F     Medium mathematical space
3297             U+3000     Ideographic space
3299           The vertical space characters are:
3301             U+000A     Linefeed
3302             U+000B     Vertical tab
3303             U+000C     Formfeed
3304             U+000D     Carriage return
3305             U+0085     Next line
3306             U+2028     Line separator
3307             U+2029     Paragraph separator
3309           A "word" character is an underscore or any character less than 256 that
3310           is  a  letter  or  digit.  The definition of letters and digits is con-
3311           trolled by PCRE's low-valued character tables, and may vary if  locale-
3312           specific  matching is taking place (see "Locale support" in the pcreapi
3313           page). For example, in a French locale such  as  "fr_FR"  in  Unix-like
3314           systems,  or "french" in Windows, some character codes greater than 128
3315           are used for accented letters, and these are matched by \w. The use  of
3316           locales with Unicode is discouraged.
3318       Newline sequences
3320           Outside  a  character class, by default, the escape sequence \R matches
3321           any Unicode newline sequence. This is a Perl 5.10 feature. In non-UTF-8
3322           mode \R is equivalent to the following:
3324             (?>\r\n|\n|\x0b|\f|\r|\x85)
3326           This  is  an  example  of an "atomic group", details of which are given
3327           below.  This particular group matches either the two-character sequence
3328           CR  followed  by  LF,  or  one  of  the single characters LF (linefeed,
3329           U+000A), VT (vertical tab, U+000B), FF (formfeed, U+000C), CR (carriage
3330           return, U+000D), or NEL (next line, U+0085). The two-character sequence
3331           is treated as a single unit that cannot be split.
3333           In UTF-8 mode, two additional characters whose codepoints  are  greater
3334           than 255 are added: LS (line separator, U+2028) and PS (paragraph sepa-
3335           rator, U+2029).  Unicode character property support is not  needed  for
3336           these characters to be recognized.
3338           It is possible to restrict \R to match only CR, LF, or CRLF (instead of
3339           the complete set  of  Unicode  line  endings)  by  setting  the  option
3340           PCRE_BSR_ANYCRLF either at compile time or when the pattern is matched.
3341           (BSR is an abbrevation for "backslash R".) This can be made the default
3342           when  PCRE  is  built;  if this is the case, the other behaviour can be
3343           requested via the PCRE_BSR_UNICODE option.   It  is  also  possible  to
3344           specify  these  settings  by  starting a pattern string with one of the
3345           following sequences:
3347             (*BSR_ANYCRLF)   CR, LF, or CRLF only
3348             (*BSR_UNICODE)   any Unicode newline sequence
3350           These override the default and the options given to pcre_compile(), but
3351           they can be overridden by options given to pcre_exec(). Note that these
3352           special settings, which are not Perl-compatible, are recognized only at
3353           the  very  start  of a pattern, and that they must be in upper case. If
3354           more than one of them is present, the last one is  used.  They  can  be
3355           combined  with  a  change of newline convention, for example, a pattern
3356           can start with:
3358             (*ANY)(*BSR_ANYCRLF)
3360           Inside a character class, \R matches the letter "R".
3362       Unicode character properties
3364           When PCRE is built with Unicode character property support, three addi-
3365           tional  escape sequences that match characters with specific properties
3366           are available.  When not in UTF-8 mode, these sequences are  of  course
3367           limited  to  testing characters whose codepoints are less than 256, but
3368           they do work in this mode.  The extra escape sequences are:
3370             \p{xx}   a character with the xx property
3371             \P{xx}   a character without the xx property
3372             \X       an extended Unicode sequence
3374           The property names represented by xx above are limited to  the  Unicode
3375           script names, the general category properties, and "Any", which matches
3376           any character (including newline). Other properties such as "InMusical-
3377           Symbols"  are  not  currently supported by PCRE. Note that \P{Any} does
3378           not match any characters, so always causes a match failure.
3380           Sets of Unicode characters are defined as belonging to certain scripts.
3381           A  character from one of these sets can be matched using a script name.
3382           For example:
3384             \p{Greek}
3385             \P{Han}
3387           Those that are not part of an identified script are lumped together  as
3388           "Common". The current list of scripts is:
3390           Arabic,  Armenian,  Balinese,  Bengali,  Bopomofo,  Braille,  Buginese,
3391           Buhid,  Canadian_Aboriginal,  Cherokee,  Common,   Coptic,   Cuneiform,
3392           Cypriot, Cyrillic, Deseret, Devanagari, Ethiopic, Georgian, Glagolitic,
3393           Gothic, Greek, Gujarati, Gurmukhi, Han, Hangul, Hanunoo, Hebrew,  Hira-
3394           gana,  Inherited,  Kannada,  Katakana,  Kharoshthi,  Khmer, Lao, Latin,
3395           Limbu,  Linear_B,  Malayalam,  Mongolian,  Myanmar,  New_Tai_Lue,  Nko,
3396           Ogham,  Old_Italic,  Old_Persian, Oriya, Osmanya, Phags_Pa, Phoenician,
3397           Runic,  Shavian,  Sinhala,  Syloti_Nagri,  Syriac,  Tagalog,  Tagbanwa,
3398           Tai_Le, Tamil, Telugu, Thaana, Thai, Tibetan, Tifinagh, Ugaritic, Yi.
3400           Each  character has exactly one general category property, specified by
3401           a two-letter abbreviation. For compatibility with Perl, negation can be
3402           specified  by  including a circumflex between the opening brace and the
3403           property name. For example, \p{^Lu} is the same as \P{Lu}.
3405           If only one letter is specified with \p or \P, it includes all the gen-
3406           eral  category properties that start with that letter. In this case, in
3407           the absence of negation, the curly brackets in the escape sequence  are
3408           optional; these two examples have the same effect:
3410             \p{L}
3411             \pL
3413           The following general category property codes are supported:
3415             C     Other
3416             Cc    Control
3417             Cf    Format
3418             Cn    Unassigned
3419             Co    Private use
3420             Cs    Surrogate
3422             L     Letter
3423             Ll    Lower case letter
3424             Lm    Modifier letter
3425             Lo    Other letter
3426             Lt    Title case letter
3427             Lu    Upper case letter
3429             M     Mark
3430             Mc    Spacing mark
3431             Me    Enclosing mark
3432             Mn    Non-spacing mark
3434             N     Number
3435             Nd    Decimal number
3436             Nl    Letter number
3437             No    Other number
3439             P     Punctuation
3440             Pc    Connector punctuation
3441             Pd    Dash punctuation
3442             Pe    Close punctuation
3443             Pf    Final punctuation
3444             Pi    Initial punctuation
3445             Po    Other punctuation
3446             Ps    Open punctuation