chiark / gitweb /
Commit upstream pcre-8.39.tar.bz2
[pcre3.git] / doc / pcre.txt
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. Neither has
6 the pcredemo program. There are separate text files for the pcregrep and
7 pcretest commands.
8 -----------------------------------------------------------------------------
9
10
11 PCRE(3)                    Library Functions Manual                    PCRE(3)
12
13
14
15 NAME
16        PCRE - Perl-compatible regular expressions (original API)
17
18 PLEASE TAKE NOTE
19
20        This  document relates to PCRE releases that use the original API, with
21        library names libpcre, libpcre16, and libpcre32. January 2015  saw  the
22        first release of a new API, known as PCRE2, with release numbers start-
23        ing  at  10.00  and  library   names   libpcre2-8,   libpcre2-16,   and
24        libpcre2-32. The old libraries (now called PCRE1) are still being main-
25        tained for bug fixes,  but  there  will  be  no  new  development.  New
26        projects are advised to use the new PCRE2 libraries.
27
28
29 INTRODUCTION
30
31        The  PCRE  library is a set of functions that implement regular expres-
32        sion pattern matching using the same syntax and semantics as Perl, with
33        just  a few differences. Some features that appeared in Python and PCRE
34        before they appeared in Perl are also available using the  Python  syn-
35        tax,  there  is  some  support for one or two .NET and Oniguruma syntax
36        items, and there is an option for requesting some  minor  changes  that
37        give better JavaScript compatibility.
38
39        Starting with release 8.30, it is possible to compile two separate PCRE
40        libraries:  the  original,  which  supports  8-bit  character   strings
41        (including  UTF-8  strings),  and a second library that supports 16-bit
42        character strings (including UTF-16 strings). The build process  allows
43        either  one  or both to be built. The majority of the work to make this
44        possible was done by Zoltan Herczeg.
45
46        Starting with release 8.32 it is possible to compile a  third  separate
47        PCRE  library  that supports 32-bit character strings (including UTF-32
48        strings). The build process allows any combination of the 8-,  16-  and
49        32-bit  libraries. The work to make this possible was done by Christian
50        Persch.
51
52        The three libraries contain identical sets of  functions,  except  that
53        the  names  in  the 16-bit library start with pcre16_ instead of pcre_,
54        and the names in the 32-bit  library  start  with  pcre32_  instead  of
55        pcre_.  To avoid over-complication and reduce the documentation mainte-
56        nance load, most of the documentation describes the 8-bit library, with
57        the  differences  for  the  16-bit and 32-bit libraries described sepa-
58        rately in the pcre16 and  pcre32  pages.  References  to  functions  or
59        structures  of  the  form  pcre[16|32]_xxx  should  be  read as meaning
60        "pcre_xxx when using the  8-bit  library,  pcre16_xxx  when  using  the
61        16-bit library, or pcre32_xxx when using the 32-bit library".
62
63        The  current implementation of PCRE corresponds approximately with Perl
64        5.12, including support for UTF-8/16/32  encoded  strings  and  Unicode
65        general  category  properties. However, UTF-8/16/32 and Unicode support
66        has to be explicitly enabled; it is not the default. The Unicode tables
67        correspond to Unicode release 6.3.0.
68
69        In  addition to the Perl-compatible matching function, PCRE contains an
70        alternative function that matches the same compiled patterns in a  dif-
71        ferent way. In certain circumstances, the alternative function has some
72        advantages.  For a discussion of the two matching algorithms,  see  the
73        pcrematching page.
74
75        PCRE  is  written  in C and released as a C library. A number of people
76        have written wrappers and interfaces of various kinds.  In  particular,
77        Google  Inc.   have  provided a comprehensive C++ wrapper for the 8-bit
78        library. This is now included as part of  the  PCRE  distribution.  The
79        pcrecpp  page  has  details of this interface. Other people's contribu-
80        tions can be found in the Contrib directory at the  primary  FTP  site,
81        which is:
82
83        ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre
84
85        Details  of  exactly which Perl regular expression features are and are
86        not supported by PCRE are given in separate documents. See the pcrepat-
87        tern  and pcrecompat pages. There is a syntax summary in the pcresyntax
88        page.
89
90        Some features of PCRE can be included, excluded, or  changed  when  the
91        library  is  built.  The pcre_config() function makes it possible for a
92        client to discover which features are  available.  The  features  them-
93        selves  are described in the pcrebuild page. Documentation about build-
94        ing PCRE for various operating systems can be found in the  README  and
95        NON-AUTOTOOLS_BUILD files in the source distribution.
96
97        The  libraries contains a number of undocumented internal functions and
98        data tables that are used by more than one  of  the  exported  external
99        functions,  but  which  are  not  intended for use by external callers.
100        Their names all begin with "_pcre_" or "_pcre16_" or "_pcre32_",  which
101        hopefully  will  not provoke any name clashes. In some environments, it
102        is possible to control which  external  symbols  are  exported  when  a
103        shared  library  is  built, and in these cases the undocumented symbols
104        are not exported.
105
106
107 SECURITY CONSIDERATIONS
108
109        If you are using PCRE in a non-UTF application that  permits  users  to
110        supply  arbitrary  patterns  for  compilation, you should be aware of a
111        feature that allows users to turn on UTF support from within a pattern,
112        provided  that  PCRE  was built with UTF support. For example, an 8-bit
113        pattern that begins with "(*UTF8)" or "(*UTF)"  turns  on  UTF-8  mode,
114        which  interprets  patterns and subjects as strings of UTF-8 characters
115        instead of individual 8-bit characters.  This causes both  the  pattern
116        and any data against which it is matched to be checked for UTF-8 valid-
117        ity. If the data string is very long, such a  check  might  use  suffi-
118        ciently  many  resources  as  to cause your application to lose perfor-
119        mance.
120
121        One  way  of  guarding  against  this  possibility  is   to   use   the
122        pcre_fullinfo()  function  to  check the compiled pattern's options for
123        UTF.  Alternatively, from release 8.33, you can set the  PCRE_NEVER_UTF
124        option  at compile time. This causes an compile time error if a pattern
125        contains a UTF-setting sequence.
126
127        If your application is one that supports UTF, be  aware  that  validity
128        checking  can  take time. If the same data string is to be matched many
129        times, you can use the PCRE_NO_UTF[8|16|32]_CHECK option for the second
130        and subsequent matches to save redundant checks.
131
132        Another  way  that  performance can be hit is by running a pattern that
133        has a very large search tree against a string that  will  never  match.
134        Nested  unlimited  repeats in a pattern are a common example. PCRE pro-
135        vides some protection against this: see the PCRE_EXTRA_MATCH_LIMIT fea-
136        ture in the pcreapi page.
137
138
139 USER DOCUMENTATION
140
141        The  user  documentation  for PCRE comprises a number of different sec-
142        tions. In the "man" format, each of these is a separate "man page".  In
143        the  HTML  format, each is a separate page, linked from the index page.
144        In the plain text format, the descriptions of the pcregrep and pcretest
145        programs  are  in  files  called pcregrep.txt and pcretest.txt, respec-
146        tively. The remaining sections, except for the pcredemo section  (which
147        is  a  program  listing),  are  concatenated  in  pcre.txt, for ease of
148        searching. The sections are as follows:
149
150          pcre              this document
151          pcre-config       show PCRE installation configuration information
152          pcre16            details of the 16-bit library
153          pcre32            details of the 32-bit library
154          pcreapi           details of PCRE's native C API
155          pcrebuild         building PCRE
156          pcrecallout       details of the callout feature
157          pcrecompat        discussion of Perl compatibility
158          pcrecpp           details of the C++ wrapper for the 8-bit library
159          pcredemo          a demonstration C program that uses PCRE
160          pcregrep          description of the pcregrep command (8-bit only)
161          pcrejit           discussion of the just-in-time optimization support
162          pcrelimits        details of size and other limits
163          pcrematching      discussion of the two matching algorithms
164          pcrepartial       details of the partial matching facility
165          pcrepattern       syntax and semantics of supported
166                              regular expressions
167          pcreperform       discussion of performance issues
168          pcreposix         the POSIX-compatible C API for the 8-bit library
169          pcreprecompile    details of saving and re-using precompiled patterns
170          pcresample        discussion of the pcredemo program
171          pcrestack         discussion of stack usage
172          pcresyntax        quick syntax reference
173          pcretest          description of the pcretest testing command
174          pcreunicode       discussion of Unicode and UTF-8/16/32 support
175
176        In the "man" and HTML formats, there is also a short page  for  each  C
177        library function, listing its arguments and results.
178
179
180 AUTHOR
181
182        Philip Hazel
183        University Computing Service
184        Cambridge CB2 3QH, England.
185
186        Putting  an actual email address here seems to have been a spam magnet,
187        so I've taken it away. If you want to email me, use  my  two  initials,
188        followed by the two digits 10, at the domain cam.ac.uk.
189
190
191 REVISION
192
193        Last updated: 10 February 2015
194        Copyright (c) 1997-2015 University of Cambridge.
195 ------------------------------------------------------------------------------
196
197
198 PCRE(3)                    Library Functions Manual                    PCRE(3)
199
200
201
202 NAME
203        PCRE - Perl-compatible regular expressions
204
205        #include <pcre.h>
206
207
208 PCRE 16-BIT API BASIC FUNCTIONS
209
210        pcre16 *pcre16_compile(PCRE_SPTR16 pattern, int options,
211             const char **errptr, int *erroffset,
212             const unsigned char *tableptr);
213
214        pcre16 *pcre16_compile2(PCRE_SPTR16 pattern, int options,
215             int *errorcodeptr,
216             const char **errptr, int *erroffset,
217             const unsigned char *tableptr);
218
219        pcre16_extra *pcre16_study(const pcre16 *code, int options,
220             const char **errptr);
221
222        void pcre16_free_study(pcre16_extra *extra);
223
224        int pcre16_exec(const pcre16 *code, const pcre16_extra *extra,
225             PCRE_SPTR16 subject, int length, int startoffset,
226             int options, int *ovector, int ovecsize);
227
228        int pcre16_dfa_exec(const pcre16 *code, const pcre16_extra *extra,
229             PCRE_SPTR16 subject, int length, int startoffset,
230             int options, int *ovector, int ovecsize,
231             int *workspace, int wscount);
232
233
234 PCRE 16-BIT API STRING EXTRACTION FUNCTIONS
235
236        int pcre16_copy_named_substring(const pcre16 *code,
237             PCRE_SPTR16 subject, int *ovector,
238             int stringcount, PCRE_SPTR16 stringname,
239             PCRE_UCHAR16 *buffer, int buffersize);
240
241        int pcre16_copy_substring(PCRE_SPTR16 subject, int *ovector,
242             int stringcount, int stringnumber, PCRE_UCHAR16 *buffer,
243             int buffersize);
244
245        int pcre16_get_named_substring(const pcre16 *code,
246             PCRE_SPTR16 subject, int *ovector,
247             int stringcount, PCRE_SPTR16 stringname,
248             PCRE_SPTR16 *stringptr);
249
250        int pcre16_get_stringnumber(const pcre16 *code,
251             PCRE_SPTR16 name);
252
253        int pcre16_get_stringtable_entries(const pcre16 *code,
254             PCRE_SPTR16 name, PCRE_UCHAR16 **first, PCRE_UCHAR16 **last);
255
256        int pcre16_get_substring(PCRE_SPTR16 subject, int *ovector,
257             int stringcount, int stringnumber,
258             PCRE_SPTR16 *stringptr);
259
260        int pcre16_get_substring_list(PCRE_SPTR16 subject,
261             int *ovector, int stringcount, PCRE_SPTR16 **listptr);
262
263        void pcre16_free_substring(PCRE_SPTR16 stringptr);
264
265        void pcre16_free_substring_list(PCRE_SPTR16 *stringptr);
266
267
268 PCRE 16-BIT API AUXILIARY FUNCTIONS
269
270        pcre16_jit_stack *pcre16_jit_stack_alloc(int startsize, int maxsize);
271
272        void pcre16_jit_stack_free(pcre16_jit_stack *stack);
273
274        void pcre16_assign_jit_stack(pcre16_extra *extra,
275             pcre16_jit_callback callback, void *data);
276
277        const unsigned char *pcre16_maketables(void);
278
279        int pcre16_fullinfo(const pcre16 *code, const pcre16_extra *extra,
280             int what, void *where);
281
282        int pcre16_refcount(pcre16 *code, int adjust);
283
284        int pcre16_config(int what, void *where);
285
286        const char *pcre16_version(void);
287
288        int pcre16_pattern_to_host_byte_order(pcre16 *code,
289             pcre16_extra *extra, const unsigned char *tables);
290
291
292 PCRE 16-BIT API INDIRECTED FUNCTIONS
293
294        void *(*pcre16_malloc)(size_t);
295
296        void (*pcre16_free)(void *);
297
298        void *(*pcre16_stack_malloc)(size_t);
299
300        void (*pcre16_stack_free)(void *);
301
302        int (*pcre16_callout)(pcre16_callout_block *);
303
304
305 PCRE 16-BIT API 16-BIT-ONLY FUNCTION
306
307        int pcre16_utf16_to_host_byte_order(PCRE_UCHAR16 *output,
308             PCRE_SPTR16 input, int length, int *byte_order,
309             int keep_boms);
310
311
312 THE PCRE 16-BIT LIBRARY
313
314        Starting  with  release  8.30, it is possible to compile a PCRE library
315        that supports 16-bit character strings, including  UTF-16  strings,  as
316        well  as  or instead of the original 8-bit library. The majority of the
317        work to make  this  possible  was  done  by  Zoltan  Herczeg.  The  two
318        libraries contain identical sets of functions, used in exactly the same
319        way. Only the names of the functions and the data types of their  argu-
320        ments  and results are different. To avoid over-complication and reduce
321        the documentation maintenance load,  most  of  the  PCRE  documentation
322        describes  the  8-bit  library,  with only occasional references to the
323        16-bit library. This page describes what is different when you use  the
324        16-bit library.
325
326        WARNING:  A  single  application can be linked with both libraries, but
327        you must take care when processing any particular pattern to use  func-
328        tions  from  just one library. For example, if you want to study a pat-
329        tern that was compiled with  pcre16_compile(),  you  must  do  so  with
330        pcre16_study(), not pcre_study(), and you must free the study data with
331        pcre16_free_study().
332
333
334 THE HEADER FILE
335
336        There is only one header file, pcre.h. It contains prototypes  for  all
337        the functions in all libraries, as well as definitions of flags, struc-
338        tures, error codes, etc.
339
340
341 THE LIBRARY NAME
342
343        In Unix-like systems, the 16-bit library is called libpcre16,  and  can
344        normally  be  accesss  by adding -lpcre16 to the command for linking an
345        application that uses PCRE.
346
347
348 STRING TYPES
349
350        In the 8-bit library, strings are passed to PCRE library  functions  as
351        vectors  of  bytes  with  the  C  type "char *". In the 16-bit library,
352        strings are passed as vectors of unsigned 16-bit quantities. The  macro
353        PCRE_UCHAR16  specifies  an  appropriate  data type, and PCRE_SPTR16 is
354        defined as "const PCRE_UCHAR16 *". In very  many  environments,  "short
355        int" is a 16-bit data type. When PCRE is built, it defines PCRE_UCHAR16
356        as "unsigned short int", but checks that it really  is  a  16-bit  data
357        type.  If  it is not, the build fails with an error message telling the
358        maintainer to modify the definition appropriately.
359
360
361 STRUCTURE TYPES
362
363        The types of the opaque structures that are used  for  compiled  16-bit
364        patterns  and  JIT stacks are pcre16 and pcre16_jit_stack respectively.
365        The  type  of  the  user-accessible  structure  that  is  returned   by
366        pcre16_study()  is  pcre16_extra, and the type of the structure that is
367        used for passing data to a callout  function  is  pcre16_callout_block.
368        These structures contain the same fields, with the same names, as their
369        8-bit counterparts. The only difference is that pointers  to  character
370        strings are 16-bit instead of 8-bit types.
371
372
373 16-BIT FUNCTIONS
374
375        For  every function in the 8-bit library there is a corresponding func-
376        tion in the 16-bit library with a name that starts with pcre16_ instead
377        of  pcre_.  The  prototypes are listed above. In addition, there is one
378        extra function, pcre16_utf16_to_host_byte_order(). This  is  a  utility
379        function  that converts a UTF-16 character string to host byte order if
380        necessary. The other 16-bit  functions  expect  the  strings  they  are
381        passed to be in host byte order.
382
383        The input and output arguments of pcre16_utf16_to_host_byte_order() may
384        point to the same address, that is, conversion in place  is  supported.
385        The output buffer must be at least as long as the input.
386
387        The  length  argument  specifies the number of 16-bit data units in the
388        input string; a negative value specifies a zero-terminated string.
389
390        If byte_order is NULL, it is assumed that the string starts off in host
391        byte  order. This may be changed by byte-order marks (BOMs) anywhere in
392        the string (commonly as the first character).
393
394        If byte_order is not NULL, a non-zero value of the integer to which  it
395        points  means  that  the input starts off in host byte order, otherwise
396        the opposite order is assumed. Again, BOMs in  the  string  can  change
397        this. The final byte order is passed back at the end of processing.
398
399        If  keep_boms  is  not  zero,  byte-order  mark characters (0xfeff) are
400        copied into the output string. Otherwise they are discarded.
401
402        The result of the function is the number of 16-bit  units  placed  into
403        the  output  buffer,  including  the  zero terminator if the string was
404        zero-terminated.
405
406
407 SUBJECT STRING OFFSETS
408
409        The lengths and starting offsets of subject strings must  be  specified
410        in  16-bit  data units, and the offsets within subject strings that are
411        returned by the matching functions are in also 16-bit units rather than
412        bytes.
413
414
415 NAMED SUBPATTERNS
416
417        The  name-to-number translation table that is maintained for named sub-
418        patterns uses 16-bit characters.  The  pcre16_get_stringtable_entries()
419        function returns the length of each entry in the table as the number of
420        16-bit data units.
421
422
423 OPTION NAMES
424
425        There   are   two   new   general   option   names,   PCRE_UTF16    and
426        PCRE_NO_UTF16_CHECK,     which     correspond    to    PCRE_UTF8    and
427        PCRE_NO_UTF8_CHECK in the 8-bit library. In  fact,  these  new  options
428        define  the  same bits in the options word. There is a discussion about
429        the validity of UTF-16 strings in the pcreunicode page.
430
431        For the pcre16_config() function there is an  option  PCRE_CONFIG_UTF16
432        that  returns  1  if UTF-16 support is configured, otherwise 0. If this
433        option  is  given  to  pcre_config()  or  pcre32_config(),  or  if  the
434        PCRE_CONFIG_UTF8  or  PCRE_CONFIG_UTF32  option is given to pcre16_con-
435        fig(), the result is the PCRE_ERROR_BADOPTION error.
436
437
438 CHARACTER CODES
439
440        In 16-bit mode, when  PCRE_UTF16  is  not  set,  character  values  are
441        treated in the same way as in 8-bit, non UTF-8 mode, except, of course,
442        that they can range from 0 to 0xffff instead of 0  to  0xff.  Character
443        types  for characters less than 0xff can therefore be influenced by the
444        locale in the same way as before.  Characters greater  than  0xff  have
445        only one case, and no "type" (such as letter or digit).
446
447        In  UTF-16  mode,  the  character  code  is  Unicode, in the range 0 to
448        0x10ffff, with the exception of values in the range  0xd800  to  0xdfff
449        because  those  are "surrogate" values that are used in pairs to encode
450        values greater than 0xffff.
451
452        A UTF-16 string can indicate its endianness by special code knows as  a
453        byte-order mark (BOM). The PCRE functions do not handle this, expecting
454        strings  to  be  in  host  byte  order.  A  utility   function   called
455        pcre16_utf16_to_host_byte_order()  is  provided  to help with this (see
456        above).
457
458
459 ERROR NAMES
460
461        The errors PCRE_ERROR_BADUTF16_OFFSET and PCRE_ERROR_SHORTUTF16  corre-
462        spond  to  their  8-bit  counterparts.  The error PCRE_ERROR_BADMODE is
463        given when a compiled pattern is passed to a  function  that  processes
464        patterns  in  the  other  mode, for example, if a pattern compiled with
465        pcre_compile() is passed to pcre16_exec().
466
467        There are new error codes whose names  begin  with  PCRE_UTF16_ERR  for
468        invalid  UTF-16  strings,  corresponding to the PCRE_UTF8_ERR codes for
469        UTF-8 strings that are described in the section entitled "Reason  codes
470        for  invalid UTF-8 strings" in the main pcreapi page. The UTF-16 errors
471        are:
472
473          PCRE_UTF16_ERR1  Missing low surrogate at end of string
474          PCRE_UTF16_ERR2  Invalid low surrogate follows high surrogate
475          PCRE_UTF16_ERR3  Isolated low surrogate
476          PCRE_UTF16_ERR4  Non-character
477
478
479 ERROR TEXTS
480
481        If there is an error while compiling a pattern, the error text that  is
482        passed  back by pcre16_compile() or pcre16_compile2() is still an 8-bit
483        character string, zero-terminated.
484
485
486 CALLOUTS
487
488        The subject and mark fields in the callout block that is  passed  to  a
489        callout function point to 16-bit vectors.
490
491
492 TESTING
493
494        The  pcretest  program continues to operate with 8-bit input and output
495        files, but it can be used for testing the 16-bit library. If it is  run
496        with the command line option -16, patterns and subject strings are con-
497        verted from 8-bit to 16-bit before being passed to PCRE, and the 16-bit
498        library  functions  are used instead of the 8-bit ones. Returned 16-bit
499        strings are converted to 8-bit for output. If both the  8-bit  and  the
500        32-bit libraries were not compiled, pcretest defaults to 16-bit and the
501        -16 option is ignored.
502
503        When PCRE is being built, the RunTest script that is  called  by  "make
504        check"  uses  the  pcretest  -C  option to discover which of the 8-bit,
505        16-bit and 32-bit libraries has been built, and runs the  tests  appro-
506        priately.
507
508
509 NOT SUPPORTED IN 16-BIT MODE
510
511        Not all the features of the 8-bit library are available with the 16-bit
512        library. The C++ and POSIX wrapper functions  support  only  the  8-bit
513        library, and the pcregrep program is at present 8-bit only.
514
515
516 AUTHOR
517
518        Philip Hazel
519        University Computing Service
520        Cambridge CB2 3QH, England.
521
522
523 REVISION
524
525        Last updated: 12 May 2013
526        Copyright (c) 1997-2013 University of Cambridge.
527 ------------------------------------------------------------------------------
528
529
530 PCRE(3)                    Library Functions Manual                    PCRE(3)
531
532
533
534 NAME
535        PCRE - Perl-compatible regular expressions
536
537        #include <pcre.h>
538
539
540 PCRE 32-BIT API BASIC FUNCTIONS
541
542        pcre32 *pcre32_compile(PCRE_SPTR32 pattern, int options,
543             const char **errptr, int *erroffset,
544             const unsigned char *tableptr);
545
546        pcre32 *pcre32_compile2(PCRE_SPTR32 pattern, int options,
547             int *errorcodeptr,
548             const unsigned char *tableptr);
549
550        pcre32_extra *pcre32_study(const pcre32 *code, int options,
551             const char **errptr);
552
553        void pcre32_free_study(pcre32_extra *extra);
554
555        int pcre32_exec(const pcre32 *code, const pcre32_extra *extra,
556             PCRE_SPTR32 subject, int length, int startoffset,
557             int options, int *ovector, int ovecsize);
558
559        int pcre32_dfa_exec(const pcre32 *code, const pcre32_extra *extra,
560             PCRE_SPTR32 subject, int length, int startoffset,
561             int options, int *ovector, int ovecsize,
562             int *workspace, int wscount);
563
564
565 PCRE 32-BIT API STRING EXTRACTION FUNCTIONS
566
567        int pcre32_copy_named_substring(const pcre32 *code,
568             PCRE_SPTR32 subject, int *ovector,
569             int stringcount, PCRE_SPTR32 stringname,
570             PCRE_UCHAR32 *buffer, int buffersize);
571
572        int pcre32_copy_substring(PCRE_SPTR32 subject, int *ovector,
573             int stringcount, int stringnumber, PCRE_UCHAR32 *buffer,
574             int buffersize);
575
576        int pcre32_get_named_substring(const pcre32 *code,
577             PCRE_SPTR32 subject, int *ovector,
578             int stringcount, PCRE_SPTR32 stringname,
579             PCRE_SPTR32 *stringptr);
580
581        int pcre32_get_stringnumber(const pcre32 *code,
582             PCRE_SPTR32 name);
583
584        int pcre32_get_stringtable_entries(const pcre32 *code,
585             PCRE_SPTR32 name, PCRE_UCHAR32 **first, PCRE_UCHAR32 **last);
586
587        int pcre32_get_substring(PCRE_SPTR32 subject, int *ovector,
588             int stringcount, int stringnumber,
589             PCRE_SPTR32 *stringptr);
590
591        int pcre32_get_substring_list(PCRE_SPTR32 subject,
592             int *ovector, int stringcount, PCRE_SPTR32 **listptr);
593
594        void pcre32_free_substring(PCRE_SPTR32 stringptr);
595
596        void pcre32_free_substring_list(PCRE_SPTR32 *stringptr);
597
598
599 PCRE 32-BIT API AUXILIARY FUNCTIONS
600
601        pcre32_jit_stack *pcre32_jit_stack_alloc(int startsize, int maxsize);
602
603        void pcre32_jit_stack_free(pcre32_jit_stack *stack);
604
605        void pcre32_assign_jit_stack(pcre32_extra *extra,
606             pcre32_jit_callback callback, void *data);
607
608        const unsigned char *pcre32_maketables(void);
609
610        int pcre32_fullinfo(const pcre32 *code, const pcre32_extra *extra,
611             int what, void *where);
612
613        int pcre32_refcount(pcre32 *code, int adjust);
614
615        int pcre32_config(int what, void *where);
616
617        const char *pcre32_version(void);
618
619        int pcre32_pattern_to_host_byte_order(pcre32 *code,
620             pcre32_extra *extra, const unsigned char *tables);
621
622
623 PCRE 32-BIT API INDIRECTED FUNCTIONS
624
625        void *(*pcre32_malloc)(size_t);
626
627        void (*pcre32_free)(void *);
628
629        void *(*pcre32_stack_malloc)(size_t);
630
631        void (*pcre32_stack_free)(void *);
632
633        int (*pcre32_callout)(pcre32_callout_block *);
634
635
636 PCRE 32-BIT API 32-BIT-ONLY FUNCTION
637
638        int pcre32_utf32_to_host_byte_order(PCRE_UCHAR32 *output,
639             PCRE_SPTR32 input, int length, int *byte_order,
640             int keep_boms);
641
642
643 THE PCRE 32-BIT LIBRARY
644
645        Starting  with  release  8.32, it is possible to compile a PCRE library
646        that supports 32-bit character strings, including  UTF-32  strings,  as
647        well as or instead of the original 8-bit library. This work was done by
648        Christian Persch, based on the work done  by  Zoltan  Herczeg  for  the
649        16-bit  library.  All  three  libraries contain identical sets of func-
650        tions, used in exactly the same way.  Only the names of  the  functions
651        and  the  data  types  of their arguments and results are different. To
652        avoid over-complication and reduce the documentation maintenance  load,
653        most  of  the PCRE documentation describes the 8-bit library, with only
654        occasional references to the 16-bit and  32-bit  libraries.  This  page
655        describes what is different when you use the 32-bit library.
656
657        WARNING:  A  single  application  can  be linked with all or any of the
658        three libraries, but you must take care when processing any  particular
659        pattern  to  use  functions  from just one library. For example, if you
660        want to study a pattern that was compiled  with  pcre32_compile(),  you
661        must do so with pcre32_study(), not pcre_study(), and you must free the
662        study data with pcre32_free_study().
663
664
665 THE HEADER FILE
666
667        There is only one header file, pcre.h. It contains prototypes  for  all
668        the functions in all libraries, as well as definitions of flags, struc-
669        tures, error codes, etc.
670
671
672 THE LIBRARY NAME
673
674        In Unix-like systems, the 32-bit library is called libpcre32,  and  can
675        normally  be  accesss  by adding -lpcre32 to the command for linking an
676        application that uses PCRE.
677
678
679 STRING TYPES
680
681        In the 8-bit library, strings are passed to PCRE library  functions  as
682        vectors  of  bytes  with  the  C  type "char *". In the 32-bit library,
683        strings are passed as vectors of unsigned 32-bit quantities. The  macro
684        PCRE_UCHAR32  specifies  an  appropriate  data type, and PCRE_SPTR32 is
685        defined as "const PCRE_UCHAR32 *". In very many environments, "unsigned
686        int" is a 32-bit data type. When PCRE is built, it defines PCRE_UCHAR32
687        as "unsigned int", but checks that it really is a 32-bit data type.  If
688        it is not, the build fails with an error message telling the maintainer
689        to modify the definition appropriately.
690
691
692 STRUCTURE TYPES
693
694        The types of the opaque structures that are used  for  compiled  32-bit
695        patterns  and  JIT stacks are pcre32 and pcre32_jit_stack respectively.
696        The  type  of  the  user-accessible  structure  that  is  returned   by
697        pcre32_study()  is  pcre32_extra, and the type of the structure that is
698        used for passing data to a callout  function  is  pcre32_callout_block.
699        These structures contain the same fields, with the same names, as their
700        8-bit counterparts. The only difference is that pointers  to  character
701        strings are 32-bit instead of 8-bit types.
702
703
704 32-BIT FUNCTIONS
705
706        For  every function in the 8-bit library there is a corresponding func-
707        tion in the 32-bit library with a name that starts with pcre32_ instead
708        of  pcre_.  The  prototypes are listed above. In addition, there is one
709        extra function, pcre32_utf32_to_host_byte_order(). This  is  a  utility
710        function  that converts a UTF-32 character string to host byte order if
711        necessary. The other 32-bit  functions  expect  the  strings  they  are
712        passed to be in host byte order.
713
714        The input and output arguments of pcre32_utf32_to_host_byte_order() may
715        point to the same address, that is, conversion in place  is  supported.
716        The output buffer must be at least as long as the input.
717
718        The  length  argument  specifies the number of 32-bit data units in the
719        input string; a negative value specifies a zero-terminated string.
720
721        If byte_order is NULL, it is assumed that the string starts off in host
722        byte  order. This may be changed by byte-order marks (BOMs) anywhere in
723        the string (commonly as the first character).
724
725        If byte_order is not NULL, a non-zero value of the integer to which  it
726        points  means  that  the input starts off in host byte order, otherwise
727        the opposite order is assumed. Again, BOMs in  the  string  can  change
728        this. The final byte order is passed back at the end of processing.
729
730        If  keep_boms  is  not  zero,  byte-order  mark characters (0xfeff) are
731        copied into the output string. Otherwise they are discarded.
732
733        The result of the function is the number of 32-bit  units  placed  into
734        the  output  buffer,  including  the  zero terminator if the string was
735        zero-terminated.
736
737
738 SUBJECT STRING OFFSETS
739
740        The lengths and starting offsets of subject strings must  be  specified
741        in  32-bit  data units, and the offsets within subject strings that are
742        returned by the matching functions are in also 32-bit units rather than
743        bytes.
744
745
746 NAMED SUBPATTERNS
747
748        The  name-to-number translation table that is maintained for named sub-
749        patterns uses 32-bit characters.  The  pcre32_get_stringtable_entries()
750        function returns the length of each entry in the table as the number of
751        32-bit data units.
752
753
754 OPTION NAMES
755
756        There   are   two   new   general   option   names,   PCRE_UTF32    and
757        PCRE_NO_UTF32_CHECK,     which     correspond    to    PCRE_UTF8    and
758        PCRE_NO_UTF8_CHECK in the 8-bit library. In  fact,  these  new  options
759        define  the  same bits in the options word. There is a discussion about
760        the validity of UTF-32 strings in the pcreunicode page.
761
762        For the pcre32_config() function there is an  option  PCRE_CONFIG_UTF32
763        that  returns  1  if UTF-32 support is configured, otherwise 0. If this
764        option  is  given  to  pcre_config()  or  pcre16_config(),  or  if  the
765        PCRE_CONFIG_UTF8  or  PCRE_CONFIG_UTF16  option is given to pcre32_con-
766        fig(), the result is the PCRE_ERROR_BADOPTION error.
767
768
769 CHARACTER CODES
770
771        In 32-bit mode, when  PCRE_UTF32  is  not  set,  character  values  are
772        treated in the same way as in 8-bit, non UTF-8 mode, except, of course,
773        that they can range from 0 to 0x7fffffff instead of 0 to 0xff.  Charac-
774        ter  types for characters less than 0xff can therefore be influenced by
775        the locale in the same way as before.   Characters  greater  than  0xff
776        have only one case, and no "type" (such as letter or digit).
777
778        In  UTF-32  mode,  the  character  code  is  Unicode, in the range 0 to
779        0x10ffff, with the exception of values in the range  0xd800  to  0xdfff
780        because those are "surrogate" values that are ill-formed in UTF-32.
781
782        A  UTF-32 string can indicate its endianness by special code knows as a
783        byte-order mark (BOM). The PCRE functions do not handle this, expecting
784        strings   to   be  in  host  byte  order.  A  utility  function  called
785        pcre32_utf32_to_host_byte_order() is provided to help  with  this  (see
786        above).
787
788
789 ERROR NAMES
790
791        The  error  PCRE_ERROR_BADUTF32  corresponds  to its 8-bit counterpart.
792        The error PCRE_ERROR_BADMODE is given when a compiled pattern is passed
793        to  a  function that processes patterns in the other mode, for example,
794        if a pattern compiled with pcre_compile() is passed to pcre32_exec().
795
796        There are new error codes whose names  begin  with  PCRE_UTF32_ERR  for
797        invalid  UTF-32  strings,  corresponding to the PCRE_UTF8_ERR codes for
798        UTF-8 strings that are described in the section entitled "Reason  codes
799        for  invalid UTF-8 strings" in the main pcreapi page. The UTF-32 errors
800        are:
801
802          PCRE_UTF32_ERR1  Surrogate character (range from 0xd800 to 0xdfff)
803          PCRE_UTF32_ERR2  Non-character
804          PCRE_UTF32_ERR3  Character > 0x10ffff
805
806
807 ERROR TEXTS
808
809        If there is an error while compiling a pattern, the error text that  is
810        passed  back by pcre32_compile() or pcre32_compile2() is still an 8-bit
811        character string, zero-terminated.
812
813
814 CALLOUTS
815
816        The subject and mark fields in the callout block that is  passed  to  a
817        callout function point to 32-bit vectors.
818
819
820 TESTING
821
822        The  pcretest  program continues to operate with 8-bit input and output
823        files, but it can be used for testing the 32-bit library. If it is  run
824        with the command line option -32, patterns and subject strings are con-
825        verted from 8-bit to 32-bit before being passed to PCRE, and the 32-bit
826        library  functions  are used instead of the 8-bit ones. Returned 32-bit
827        strings are converted to 8-bit for output. If both the  8-bit  and  the
828        16-bit libraries were not compiled, pcretest defaults to 32-bit and the
829        -32 option is ignored.
830
831        When PCRE is being built, the RunTest script that is  called  by  "make
832        check"  uses  the  pcretest  -C  option to discover which of the 8-bit,
833        16-bit and 32-bit libraries has been built, and runs the  tests  appro-
834        priately.
835
836
837 NOT SUPPORTED IN 32-BIT MODE
838
839        Not all the features of the 8-bit library are available with the 32-bit
840        library. The C++ and POSIX wrapper functions  support  only  the  8-bit
841        library, and the pcregrep program is at present 8-bit only.
842
843
844 AUTHOR
845
846        Philip Hazel
847        University Computing Service
848        Cambridge CB2 3QH, England.
849
850
851 REVISION
852
853        Last updated: 12 May 2013
854        Copyright (c) 1997-2013 University of Cambridge.
855 ------------------------------------------------------------------------------
856
857
858 PCREBUILD(3)               Library Functions Manual               PCREBUILD(3)
859
860
861
862 NAME
863        PCRE - Perl-compatible regular expressions
864
865 BUILDING PCRE
866
867        PCRE  is  distributed with a configure script that can be used to build
868        the library in Unix-like environments using the applications  known  as
869        Autotools.   Also  in  the  distribution  are files to support building
870        using CMake instead of configure. The text file README contains general
871        information  about  building  with Autotools (some of which is repeated
872        below), and also has some comments about building on various  operating
873        systems.  There  is  a lot more information about building PCRE without
874        using Autotools (including information about using CMake  and  building
875        "by  hand")  in  the  text file called NON-AUTOTOOLS-BUILD.  You should
876        consult this file as well as the README file if you are building  in  a
877        non-Unix-like environment.
878
879
880 PCRE BUILD-TIME OPTIONS
881
882        The  rest of this document describes the optional features of PCRE that
883        can be selected when the library is compiled. It  assumes  use  of  the
884        configure  script,  where  the  optional features are selected or dese-
885        lected by providing options to configure before running the  make  com-
886        mand.  However,  the same options can be selected in both Unix-like and
887        non-Unix-like environments using the GUI facility of cmake-gui  if  you
888        are using CMake instead of configure to build PCRE.
889
890        If  you  are not using Autotools or CMake, option selection can be done
891        by editing the config.h file, or by passing parameter settings  to  the
892        compiler, as described in NON-AUTOTOOLS-BUILD.
893
894        The complete list of options for configure (which includes the standard
895        ones such as the  selection  of  the  installation  directory)  can  be
896        obtained by running
897
898          ./configure --help
899
900        The  following  sections  include  descriptions  of options whose names
901        begin with --enable or --disable. These settings specify changes to the
902        defaults  for  the configure command. Because of the way that configure
903        works, --enable and --disable always come in pairs, so  the  complemen-
904        tary  option always exists as well, but as it specifies the default, it
905        is not described.
906
907
908 BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES
909
910        By default, a library called libpcre  is  built,  containing  functions
911        that  take  string  arguments  contained in vectors of bytes, either as
912        single-byte characters, or interpreted as UTF-8 strings. You  can  also
913        build  a  separate library, called libpcre16, in which strings are con-
914        tained in vectors of 16-bit data units and interpreted either  as  sin-
915        gle-unit characters or UTF-16 strings, by adding
916
917          --enable-pcre16
918
919        to  the  configure  command.  You  can  also build yet another separate
920        library, called libpcre32, in which strings are contained in vectors of
921        32-bit  data  units and interpreted either as single-unit characters or
922        UTF-32 strings, by adding
923
924          --enable-pcre32
925
926        to the configure command. If you do not want the 8-bit library, add
927
928          --disable-pcre8
929
930        as well. At least one of the three libraries must be built.  Note  that
931        the  C++  and  POSIX  wrappers are for the 8-bit library only, and that
932        pcregrep is an 8-bit program. None of these are  built  if  you  select
933        only the 16-bit or 32-bit libraries.
934
935
936 BUILDING SHARED AND STATIC LIBRARIES
937
938        The  Autotools  PCRE building process uses libtool to build both shared
939        and static libraries by default. You  can  suppress  one  of  these  by
940        adding one of
941
942          --disable-shared
943          --disable-static
944
945        to the configure command, as required.
946
947
948 C++ SUPPORT
949
950        By  default,  if the 8-bit library is being built, the configure script
951        will search for a C++ compiler and C++ header files. If it finds  them,
952        it  automatically  builds  the C++ wrapper library (which supports only
953        8-bit strings). You can disable this by adding
954
955          --disable-cpp
956
957        to the configure command.
958
959
960 UTF-8, UTF-16 AND UTF-32 SUPPORT
961
962        To build PCRE with support for UTF Unicode character strings, add
963
964          --enable-utf
965
966        to the configure command. This setting applies to all three  libraries,
967        adding  support  for  UTF-8 to the 8-bit library, support for UTF-16 to
968        the 16-bit library, and  support  for  UTF-32  to  the  to  the  32-bit
969        library.  There  are no separate options for enabling UTF-8, UTF-16 and
970        UTF-32 independently because that would allow ridiculous settings  such
971        as  requesting UTF-16 support while building only the 8-bit library. It
972        is not possible to build one library with UTF support and another with-
973        out  in the same configuration. (For backwards compatibility, --enable-
974        utf8 is a synonym of --enable-utf.)
975
976        Of itself, this setting does not make  PCRE  treat  strings  as  UTF-8,
977        UTF-16  or UTF-32. As well as compiling PCRE with this option, you also
978        have have to set the PCRE_UTF8, PCRE_UTF16  or  PCRE_UTF32  option  (as
979        appropriate) when you call one of the pattern compiling functions.
980
981        If  you  set --enable-utf when compiling in an EBCDIC environment, PCRE
982        expects its input to be either ASCII or UTF-8 (depending  on  the  run-
983        time option). It is not possible to support both EBCDIC and UTF-8 codes
984        in the same version of  the  library.  Consequently,  --enable-utf  and
985        --enable-ebcdic are mutually exclusive.
986
987
988 UNICODE CHARACTER PROPERTY SUPPORT
989
990        UTF  support allows the libraries to process character codepoints up to
991        0x10ffff in the strings that they handle. On its own, however, it  does
992        not provide any facilities for accessing the properties of such charac-
993        ters. If you want to be able to use the pattern escapes \P, \p, and \X,
994        which refer to Unicode character properties, you must add
995
996          --enable-unicode-properties
997
998        to  the  configure  command. This implies UTF support, even if you have
999        not explicitly requested it.
1000
1001        Including Unicode property support adds around 30K  of  tables  to  the
1002        PCRE  library.  Only  the general category properties such as Lu and Nd
1003        are supported. Details are given in the pcrepattern documentation.
1004
1005
1006 JUST-IN-TIME COMPILER SUPPORT
1007
1008        Just-in-time compiler support is included in the build by specifying
1009
1010          --enable-jit
1011
1012        This support is available only for certain hardware  architectures.  If
1013        this  option  is  set  for  an unsupported architecture, a compile time
1014        error occurs.  See the pcrejit documentation for a  discussion  of  JIT
1015        usage. When JIT support is enabled, pcregrep automatically makes use of
1016        it, unless you add
1017
1018          --disable-pcregrep-jit
1019
1020        to the "configure" command.
1021
1022
1023 CODE VALUE OF NEWLINE
1024
1025        By default, PCRE interprets the linefeed (LF) character  as  indicating
1026        the  end  of  a line. This is the normal newline character on Unix-like
1027        systems. You can compile PCRE to use carriage return (CR)  instead,  by
1028        adding
1029
1030          --enable-newline-is-cr
1031
1032        to  the  configure  command.  There  is  also  a --enable-newline-is-lf
1033        option, which explicitly specifies linefeed as the newline character.
1034
1035        Alternatively, you can specify that line endings are to be indicated by
1036        the two character sequence CRLF. If you want this, add
1037
1038          --enable-newline-is-crlf
1039
1040        to the configure command. There is a fourth option, specified by
1041
1042          --enable-newline-is-anycrlf
1043
1044        which  causes  PCRE  to recognize any of the three sequences CR, LF, or
1045        CRLF as indicating a line ending. Finally, a fifth option, specified by
1046
1047          --enable-newline-is-any
1048
1049        causes PCRE to recognize any Unicode newline sequence.
1050
1051        Whatever line ending convention is selected when PCRE is built  can  be
1052        overridden  when  the library functions are called. At build time it is
1053        conventional to use the standard for your operating system.
1054
1055
1056 WHAT \R MATCHES
1057
1058        By default, the sequence \R in a pattern matches  any  Unicode  newline
1059        sequence,  whatever  has  been selected as the line ending sequence. If
1060        you specify
1061
1062          --enable-bsr-anycrlf
1063
1064        the default is changed so that \R matches only CR, LF, or  CRLF.  What-
1065        ever  is selected when PCRE is built can be overridden when the library
1066        functions are called.
1067
1068
1069 POSIX MALLOC USAGE
1070
1071        When the 8-bit library is called through the POSIX interface  (see  the
1072        pcreposix  documentation),  additional  working storage is required for
1073        holding the pointers to capturing  substrings,  because  PCRE  requires
1074        three integers per substring, whereas the POSIX interface provides only
1075        two. If the number of expected substrings is small, the  wrapper  func-
1076        tion  uses  space  on the stack, because this is faster than using mal-
1077        loc() for each call. The default threshold above which the stack is  no
1078        longer used is 10; it can be changed by adding a setting such as
1079
1080          --with-posix-malloc-threshold=20
1081
1082        to the configure command.
1083
1084
1085 HANDLING VERY LARGE PATTERNS
1086
1087        Within  a  compiled  pattern,  offset values are used to point from one
1088        part to another (for example, from an opening parenthesis to an  alter-
1089        nation  metacharacter).  By default, in the 8-bit and 16-bit libraries,
1090        two-byte values are used for these offsets, leading to a  maximum  size
1091        for  a compiled pattern of around 64K. This is sufficient to handle all
1092        but the most gigantic patterns.  Nevertheless, some people do  want  to
1093        process  truly  enormous patterns, so it is possible to compile PCRE to
1094        use three-byte or four-byte offsets by adding a setting such as
1095
1096          --with-link-size=3
1097
1098        to the configure command. The value given must be 2, 3, or 4.  For  the
1099        16-bit  library,  a  value of 3 is rounded up to 4. In these libraries,
1100        using longer offsets slows down the operation of PCRE because it has to
1101        load  additional  data  when  handling them. For the 32-bit library the
1102        value is always 4 and cannot be overridden; the value  of  --with-link-
1103        size is ignored.
1104
1105
1106 AVOIDING EXCESSIVE STACK USAGE
1107
1108        When matching with the pcre_exec() function, PCRE implements backtrack-
1109        ing by making recursive calls to an internal function  called  match().
1110        In  environments  where  the size of the stack is limited, this can se-
1111        verely limit PCRE's operation. (The Unix environment does  not  usually
1112        suffer from this problem, but it may sometimes be necessary to increase
1113        the maximum stack size.  There is a discussion in the  pcrestack  docu-
1114        mentation.)  An alternative approach to recursion that uses memory from
1115        the heap to remember data, instead of using recursive  function  calls,
1116        has  been  implemented to work round the problem of limited stack size.
1117        If you want to build a version of PCRE that works this way, add
1118
1119          --disable-stack-for-recursion
1120
1121        to the configure command. With this configuration, PCRE  will  use  the
1122        pcre_stack_malloc  and pcre_stack_free variables to call memory manage-
1123        ment functions. By default these point to malloc() and free(), but  you
1124        can replace the pointers so that your own functions are used instead.
1125
1126        Separate  functions  are  provided  rather  than  using pcre_malloc and
1127        pcre_free because the  usage  is  very  predictable:  the  block  sizes
1128        requested  are  always  the  same,  and  the blocks are always freed in
1129        reverse order. A calling program might be able to  implement  optimized
1130        functions  that  perform  better  than  malloc()  and free(). PCRE runs
1131        noticeably more slowly when built in this way. This option affects only
1132        the pcre_exec() function; it is not relevant for pcre_dfa_exec().
1133
1134
1135 LIMITING PCRE RESOURCE USAGE
1136
1137        Internally,  PCRE has a function called match(), which it calls repeat-
1138        edly  (sometimes  recursively)  when  matching  a  pattern   with   the
1139        pcre_exec()  function.  By controlling the maximum number of times this
1140        function may be called during a single matching operation, a limit  can
1141        be  placed  on  the resources used by a single call to pcre_exec(). The
1142        limit can be changed at run time, as described in the pcreapi  documen-
1143        tation.  The default is 10 million, but this can be changed by adding a
1144        setting such as
1145
1146          --with-match-limit=500000
1147
1148        to  the  configure  command.  This  setting  has  no  effect   on   the
1149        pcre_dfa_exec() matching function.
1150
1151        In  some  environments  it is desirable to limit the depth of recursive
1152        calls of match() more strictly than the total number of calls, in order
1153        to  restrict  the maximum amount of stack (or heap, if --disable-stack-
1154        for-recursion is specified) that is used. A second limit controls this;
1155        it  defaults  to  the  value  that is set for --with-match-limit, which
1156        imposes no additional constraints. However, you can set a  lower  limit
1157        by adding, for example,
1158
1159          --with-match-limit-recursion=10000
1160
1161        to  the  configure  command.  This  value can also be overridden at run
1162        time.
1163
1164
1165 CREATING CHARACTER TABLES AT BUILD TIME
1166
1167        PCRE uses fixed tables for processing characters whose code values  are
1168        less  than 256. By default, PCRE is built with a set of tables that are
1169        distributed in the file pcre_chartables.c.dist. These  tables  are  for
1170        ASCII codes only. If you add
1171
1172          --enable-rebuild-chartables
1173
1174        to  the  configure  command, the distributed tables are no longer used.
1175        Instead, a program called dftables is compiled and  run.  This  outputs
1176        the source for new set of tables, created in the default locale of your
1177        C run-time system. (This method of replacing the tables does  not  work
1178        if  you are cross compiling, because dftables is run on the local host.
1179        If you need to create alternative tables when cross compiling, you will
1180        have to do so "by hand".)
1181
1182
1183 USING EBCDIC CODE
1184
1185        PCRE  assumes  by  default that it will run in an environment where the
1186        character code is ASCII (or Unicode, which is  a  superset  of  ASCII).
1187        This  is  the  case for most computer operating systems. PCRE can, how-
1188        ever, be compiled to run in an EBCDIC environment by adding
1189
1190          --enable-ebcdic
1191
1192        to the configure command. This setting implies --enable-rebuild-charta-
1193        bles.  You  should  only  use  it if you know that you are in an EBCDIC
1194        environment (for example,  an  IBM  mainframe  operating  system).  The
1195        --enable-ebcdic option is incompatible with --enable-utf.
1196
1197        The EBCDIC character that corresponds to an ASCII LF is assumed to have
1198        the value 0x15 by default. However, in some EBCDIC  environments,  0x25
1199        is used. In such an environment you should use
1200
1201          --enable-ebcdic-nl25
1202
1203        as well as, or instead of, --enable-ebcdic. The EBCDIC character for CR
1204        has the same value as in ASCII, namely, 0x0d.  Whichever  of  0x15  and
1205        0x25 is not chosen as LF is made to correspond to the Unicode NEL char-
1206        acter (which, in Unicode, is 0x85).
1207
1208        The options that select newline behaviour, such as --enable-newline-is-
1209        cr, and equivalent run-time options, refer to these character values in
1210        an EBCDIC environment.
1211
1212
1213 PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT
1214
1215        By default, pcregrep reads all files as plain text. You can build it so
1216        that it recognizes files whose names end in .gz or .bz2, and reads them
1217        with libz or libbz2, respectively, by adding one or both of
1218
1219          --enable-pcregrep-libz
1220          --enable-pcregrep-libbz2
1221
1222        to the configure command. These options naturally require that the rel-
1223        evant  libraries  are installed on your system. Configuration will fail
1224        if they are not.
1225
1226
1227 PCREGREP BUFFER SIZE
1228
1229        pcregrep uses an internal buffer to hold a "window" on the file  it  is
1230        scanning, in order to be able to output "before" and "after" lines when
1231        it finds a match. The size of the buffer is controlled by  a  parameter
1232        whose default value is 20K. The buffer itself is three times this size,
1233        but because of the way it is used for holding "before" lines, the long-
1234        est  line  that  is guaranteed to be processable is the parameter size.
1235        You can change the default parameter value by adding, for example,
1236
1237          --with-pcregrep-bufsize=50K
1238
1239        to the configure command. The caller of pcregrep can, however, override
1240        this value by specifying a run-time option.
1241
1242
1243 PCRETEST OPTION FOR LIBREADLINE SUPPORT
1244
1245        If you add
1246
1247          --enable-pcretest-libreadline
1248
1249        to  the  configure  command,  pcretest  is  linked with the libreadline
1250        library, and when its input is from a terminal, it reads it  using  the
1251        readline() function. This provides line-editing and history facilities.
1252        Note that libreadline is GPL-licensed, so if you distribute a binary of
1253        pcretest linked in this way, there may be licensing issues.
1254
1255        Setting  this  option  causes  the -lreadline option to be added to the
1256        pcretest build. In many operating environments with  a  sytem-installed
1257        libreadline this is sufficient. However, in some environments (e.g.  if
1258        an unmodified distribution version of readline is in use),  some  extra
1259        configuration  may  be necessary. The INSTALL file for libreadline says
1260        this:
1261
1262          "Readline uses the termcap functions, but does not link with the
1263          termcap or curses library itself, allowing applications which link
1264          with readline the to choose an appropriate library."
1265
1266        If your environment has not been set up so that an appropriate  library
1267        is automatically included, you may need to add something like
1268
1269          LIBS="-ncurses"
1270
1271        immediately before the configure command.
1272
1273
1274 DEBUGGING WITH VALGRIND SUPPORT
1275
1276        By adding the
1277
1278          --enable-valgrind
1279
1280        option  to to the configure command, PCRE will use valgrind annotations
1281        to mark certain memory regions as  unaddressable.  This  allows  it  to
1282        detect invalid memory accesses, and is mostly useful for debugging PCRE
1283        itself.
1284
1285
1286 CODE COVERAGE REPORTING
1287
1288        If your C compiler is gcc, you can build a version  of  PCRE  that  can
1289        generate a code coverage report for its test suite. To enable this, you
1290        must install lcov version 1.6 or above. Then specify
1291
1292          --enable-coverage
1293
1294        to the configure command and build PCRE in the usual way.
1295
1296        Note that using ccache (a caching C compiler) is incompatible with code
1297        coverage  reporting. If you have configured ccache to run automatically
1298        on your system, you must set the environment variable
1299
1300          CCACHE_DISABLE=1
1301
1302        before running make to build PCRE, so that ccache is not used.
1303
1304        When --enable-coverage is used,  the  following  addition  targets  are
1305        added to the Makefile:
1306
1307          make coverage
1308
1309        This  creates  a  fresh  coverage report for the PCRE test suite. It is
1310        equivalent to running "make coverage-reset", "make  coverage-baseline",
1311        "make check", and then "make coverage-report".
1312
1313          make coverage-reset
1314
1315        This zeroes the coverage counters, but does nothing else.
1316
1317          make coverage-baseline
1318
1319        This captures baseline coverage information.
1320
1321          make coverage-report
1322
1323        This creates the coverage report.
1324
1325          make coverage-clean-report
1326
1327        This  removes the generated coverage report without cleaning the cover-
1328        age data itself.
1329
1330          make coverage-clean-data
1331
1332        This removes the captured coverage data without removing  the  coverage
1333        files created at compile time (*.gcno).
1334
1335          make coverage-clean
1336
1337        This  cleans all coverage data including the generated coverage report.
1338        For more information about code coverage, see the gcov and  lcov  docu-
1339        mentation.
1340
1341
1342 SEE ALSO
1343
1344        pcreapi(3), pcre16, pcre32, pcre_config(3).
1345
1346
1347 AUTHOR
1348
1349        Philip Hazel
1350        University Computing Service
1351        Cambridge CB2 3QH, England.
1352
1353
1354 REVISION
1355
1356        Last updated: 12 May 2013
1357        Copyright (c) 1997-2013 University of Cambridge.
1358 ------------------------------------------------------------------------------
1359
1360
1361 PCREMATCHING(3)            Library Functions Manual            PCREMATCHING(3)
1362
1363
1364
1365 NAME
1366        PCRE - Perl-compatible regular expressions
1367
1368 PCRE MATCHING ALGORITHMS
1369
1370        This document describes the two different algorithms that are available
1371        in PCRE for matching a compiled regular expression against a given sub-
1372        ject  string.  The  "standard"  algorithm  is  the  one provided by the
1373        pcre_exec(), pcre16_exec() and pcre32_exec() functions. These  work  in
1374        the  same as as Perl's matching function, and provide a Perl-compatible
1375        matching  operation.   The  just-in-time  (JIT)  optimization  that  is
1376        described  in  the pcrejit documentation is compatible with these func-
1377        tions.
1378
1379        An  alternative  algorithm  is   provided   by   the   pcre_dfa_exec(),
1380        pcre16_dfa_exec()  and  pcre32_dfa_exec()  functions; they operate in a
1381        different way, and are not Perl-compatible. This alternative has advan-
1382        tages and disadvantages compared with the standard algorithm, and these
1383        are described below.
1384
1385        When there is only one possible way in which a given subject string can
1386        match  a pattern, the two algorithms give the same answer. A difference
1387        arises, however, when there are multiple possibilities. For example, if
1388        the pattern
1389
1390          ^<.*>
1391
1392        is matched against the string
1393
1394          <something> <something else> <something further>
1395
1396        there are three possible answers. The standard algorithm finds only one
1397        of them, whereas the alternative algorithm finds all three.
1398
1399
1400 REGULAR EXPRESSIONS AS TREES
1401
1402        The set of strings that are matched by a regular expression can be rep-
1403        resented  as  a  tree structure. An unlimited repetition in the pattern
1404        makes the tree of infinite size, but it is still a tree.  Matching  the
1405        pattern  to a given subject string (from a given starting point) can be
1406        thought of as a search of the tree.  There are two  ways  to  search  a
1407        tree:  depth-first  and  breadth-first, and these correspond to the two
1408        matching algorithms provided by PCRE.
1409
1410
1411 THE STANDARD MATCHING ALGORITHM
1412
1413        In the terminology of Jeffrey Friedl's book "Mastering Regular  Expres-
1414        sions",  the  standard  algorithm  is an "NFA algorithm". It conducts a
1415        depth-first search of the pattern tree. That is, it  proceeds  along  a
1416        single path through the tree, checking that the subject matches what is
1417        required. When there is a mismatch, the algorithm  tries  any  alterna-
1418        tives  at  the  current point, and if they all fail, it backs up to the
1419        previous branch point in the  tree,  and  tries  the  next  alternative
1420        branch  at  that  level.  This often involves backing up (moving to the
1421        left) in the subject string as well.  The  order  in  which  repetition
1422        branches  are  tried  is controlled by the greedy or ungreedy nature of
1423        the quantifier.
1424
1425        If a leaf node is reached, a matching string has  been  found,  and  at
1426        that  point the algorithm stops. Thus, if there is more than one possi-
1427        ble match, this algorithm returns the first one that it finds.  Whether
1428        this  is the shortest, the longest, or some intermediate length depends
1429        on the way the greedy and ungreedy repetition quantifiers are specified
1430        in the pattern.
1431
1432        Because  it  ends  up  with a single path through the tree, it is rela-
1433        tively straightforward for this algorithm to keep  track  of  the  sub-
1434        strings  that  are  matched  by portions of the pattern in parentheses.
1435        This provides support for capturing parentheses and back references.
1436
1437
1438 THE ALTERNATIVE MATCHING ALGORITHM
1439
1440        This algorithm conducts a breadth-first search of  the  tree.  Starting
1441        from  the  first  matching  point  in the subject, it scans the subject
1442        string from left to right, once, character by character, and as it does
1443        this,  it remembers all the paths through the tree that represent valid
1444        matches. In Friedl's terminology, this is a kind  of  "DFA  algorithm",
1445        though  it is not implemented as a traditional finite state machine (it
1446        keeps multiple states active simultaneously).
1447
1448        Although the general principle of this matching algorithm  is  that  it
1449        scans  the subject string only once, without backtracking, there is one
1450        exception: when a lookaround assertion is encountered,  the  characters
1451        following  or  preceding  the  current  point  have to be independently
1452        inspected.
1453
1454        The scan continues until either the end of the subject is  reached,  or
1455        there  are  no more unterminated paths. At this point, terminated paths
1456        represent the different matching possibilities (if there are none,  the
1457        match  has  failed).   Thus,  if there is more than one possible match,
1458        this algorithm finds all of them, and in particular, it finds the long-
1459        est.  The  matches are returned in decreasing order of length. There is
1460        an option to stop the algorithm after the first match (which is  neces-
1461        sarily the shortest) is found.
1462
1463        Note that all the matches that are found start at the same point in the
1464        subject. If the pattern
1465
1466          cat(er(pillar)?)?
1467
1468        is matched against the string "the caterpillar catchment",  the  result
1469        will  be the three strings "caterpillar", "cater", and "cat" that start
1470        at the fifth character of the subject. The algorithm does not automati-
1471        cally move on to find matches that start at later positions.
1472
1473        PCRE's  "auto-possessification" optimization usually applies to charac-
1474        ter repeats at the end of a pattern (as well as internally). For  exam-
1475        ple, the pattern "a\d+" is compiled as if it were "a\d++" because there
1476        is no point even considering the possibility of backtracking  into  the
1477        repeated  digits.  For  DFA matching, this means that only one possible
1478        match is found. If you really do want multiple matches in  such  cases,
1479        either use an ungreedy repeat ("a\d+?") or set the PCRE_NO_AUTO_POSSESS
1480        option when compiling.
1481
1482        There are a number of features of PCRE regular expressions that are not
1483        supported by the alternative matching algorithm. They are as follows:
1484
1485        1.  Because  the  algorithm  finds  all possible matches, the greedy or
1486        ungreedy nature of repetition quantifiers is not relevant.  Greedy  and
1487        ungreedy quantifiers are treated in exactly the same way. However, pos-
1488        sessive quantifiers can make a difference when what follows could  also
1489        match what is quantified, for example in a pattern like this:
1490
1491          ^a++\w!
1492
1493        This  pattern matches "aaab!" but not "aaa!", which would be matched by
1494        a non-possessive quantifier. Similarly, if an atomic group is  present,
1495        it  is matched as if it were a standalone pattern at the current point,
1496        and the longest match is then "locked in" for the rest of  the  overall
1497        pattern.
1498
1499        2. When dealing with multiple paths through the tree simultaneously, it
1500        is not straightforward to keep track of  captured  substrings  for  the
1501        different  matching  possibilities,  and  PCRE's implementation of this
1502        algorithm does not attempt to do this. This means that no captured sub-
1503        strings are available.
1504
1505        3.  Because no substrings are captured, back references within the pat-
1506        tern are not supported, and cause errors if encountered.
1507
1508        4. For the same reason, conditional expressions that use  a  backrefer-
1509        ence  as  the  condition or test for a specific group recursion are not
1510        supported.
1511
1512        5. Because many paths through the tree may be  active,  the  \K  escape
1513        sequence, which resets the start of the match when encountered (but may
1514        be on some paths and not on others), is not  supported.  It  causes  an
1515        error if encountered.
1516
1517        6.  Callouts  are  supported, but the value of the capture_top field is
1518        always 1, and the value of the capture_last field is always -1.
1519
1520        7. The \C escape sequence, which (in  the  standard  algorithm)  always
1521        matches  a  single data unit, even in UTF-8, UTF-16 or UTF-32 modes, is
1522        not supported in these modes, because the alternative  algorithm  moves
1523        through the subject string one character (not data unit) at a time, for
1524        all active paths through the tree.
1525
1526        8. Except for (*FAIL), the backtracking control verbs such as  (*PRUNE)
1527        are  not  supported.  (*FAIL)  is supported, and behaves like a failing
1528        negative assertion.
1529
1530
1531 ADVANTAGES OF THE ALTERNATIVE ALGORITHM
1532
1533        Using the alternative matching algorithm provides the following  advan-
1534        tages:
1535
1536        1. All possible matches (at a single point in the subject) are automat-
1537        ically found, and in particular, the longest match is  found.  To  find
1538        more than one match using the standard algorithm, you have to do kludgy
1539        things with callouts.
1540
1541        2. Because the alternative algorithm  scans  the  subject  string  just
1542        once, and never needs to backtrack (except for lookbehinds), it is pos-
1543        sible to pass very long subject strings to  the  matching  function  in
1544        several pieces, checking for partial matching each time. Although it is
1545        possible to do multi-segment matching using the standard  algorithm  by
1546        retaining  partially  matched  substrings,  it is more complicated. The
1547        pcrepartial documentation gives details of partial  matching  and  dis-
1548        cusses multi-segment matching.
1549
1550
1551 DISADVANTAGES OF THE ALTERNATIVE ALGORITHM
1552
1553        The alternative algorithm suffers from a number of disadvantages:
1554
1555        1.  It  is  substantially  slower  than the standard algorithm. This is
1556        partly because it has to search for all possible matches, but  is  also
1557        because it is less susceptible to optimization.
1558
1559        2. Capturing parentheses and back references are not supported.
1560
1561        3. Although atomic groups are supported, their use does not provide the
1562        performance advantage that it does for the standard algorithm.
1563
1564
1565 AUTHOR
1566
1567        Philip Hazel
1568        University Computing Service
1569        Cambridge CB2 3QH, England.
1570
1571
1572 REVISION
1573
1574        Last updated: 12 November 2013
1575        Copyright (c) 1997-2012 University of Cambridge.
1576 ------------------------------------------------------------------------------
1577
1578
1579 PCREAPI(3)                 Library Functions Manual                 PCREAPI(3)
1580
1581
1582
1583 NAME
1584        PCRE - Perl-compatible regular expressions
1585
1586        #include <pcre.h>
1587
1588
1589 PCRE NATIVE API BASIC FUNCTIONS
1590
1591        pcre *pcre_compile(const char *pattern, int options,
1592             const char **errptr, int *erroffset,
1593             const unsigned char *tableptr);
1594
1595        pcre *pcre_compile2(const char *pattern, int options,
1596             int *errorcodeptr,
1597             const char **errptr, int *erroffset,
1598             const unsigned char *tableptr);
1599
1600        pcre_extra *pcre_study(const pcre *code, int options,
1601             const char **errptr);
1602
1603        void pcre_free_study(pcre_extra *extra);
1604
1605        int pcre_exec(const pcre *code, const pcre_extra *extra,
1606             const char *subject, int length, int startoffset,
1607             int options, int *ovector, int ovecsize);
1608
1609        int pcre_dfa_exec(const pcre *code, const pcre_extra *extra,
1610             const char *subject, int length, int startoffset,
1611             int options, int *ovector, int ovecsize,
1612             int *workspace, int wscount);
1613
1614
1615 PCRE NATIVE API STRING EXTRACTION FUNCTIONS
1616
1617        int pcre_copy_named_substring(const pcre *code,
1618             const char *subject, int *ovector,
1619             int stringcount, const char *stringname,
1620             char *buffer, int buffersize);
1621
1622        int pcre_copy_substring(const char *subject, int *ovector,
1623             int stringcount, int stringnumber, char *buffer,
1624             int buffersize);
1625
1626        int pcre_get_named_substring(const pcre *code,
1627             const char *subject, int *ovector,
1628             int stringcount, const char *stringname,
1629             const char **stringptr);
1630
1631        int pcre_get_stringnumber(const pcre *code,
1632             const char *name);
1633
1634        int pcre_get_stringtable_entries(const pcre *code,
1635             const char *name, char **first, char **last);
1636
1637        int pcre_get_substring(const char *subject, int *ovector,
1638             int stringcount, int stringnumber,
1639             const char **stringptr);
1640
1641        int pcre_get_substring_list(const char *subject,
1642             int *ovector, int stringcount, const char ***listptr);
1643
1644        void pcre_free_substring(const char *stringptr);
1645
1646        void pcre_free_substring_list(const char **stringptr);
1647
1648
1649 PCRE NATIVE API AUXILIARY FUNCTIONS
1650
1651        int pcre_jit_exec(const pcre *code, const pcre_extra *extra,
1652             const char *subject, int length, int startoffset,
1653             int options, int *ovector, int ovecsize,
1654             pcre_jit_stack *jstack);
1655
1656        pcre_jit_stack *pcre_jit_stack_alloc(int startsize, int maxsize);
1657
1658        void pcre_jit_stack_free(pcre_jit_stack *stack);
1659
1660        void pcre_assign_jit_stack(pcre_extra *extra,
1661             pcre_jit_callback callback, void *data);
1662
1663        const unsigned char *pcre_maketables(void);
1664
1665        int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
1666             int what, void *where);
1667
1668        int pcre_refcount(pcre *code, int adjust);
1669
1670        int pcre_config(int what, void *where);
1671
1672        const char *pcre_version(void);
1673
1674        int pcre_pattern_to_host_byte_order(pcre *code,
1675             pcre_extra *extra, const unsigned char *tables);
1676
1677
1678 PCRE NATIVE API INDIRECTED FUNCTIONS
1679
1680        void *(*pcre_malloc)(size_t);
1681
1682        void (*pcre_free)(void *);
1683
1684        void *(*pcre_stack_malloc)(size_t);
1685
1686        void (*pcre_stack_free)(void *);
1687
1688        int (*pcre_callout)(pcre_callout_block *);
1689
1690        int (*pcre_stack_guard)(void);
1691
1692
1693 PCRE 8-BIT, 16-BIT, AND 32-BIT LIBRARIES
1694
1695        As  well  as  support  for  8-bit character strings, PCRE also supports
1696        16-bit strings (from release 8.30) and  32-bit  strings  (from  release
1697        8.32),  by means of two additional libraries. They can be built as well
1698        as, or instead of, the 8-bit library. To avoid too  much  complication,
1699        this  document describes the 8-bit versions of the functions, with only
1700        occasional references to the 16-bit and 32-bit libraries.
1701
1702        The 16-bit and 32-bit functions operate in the same way as their  8-bit
1703        counterparts;  they  just  use different data types for their arguments
1704        and results, and their names start with pcre16_ or pcre32_  instead  of
1705        pcre_.  For  every  option  that  has  UTF8  in  its name (for example,
1706        PCRE_UTF8), there are corresponding 16-bit and 32-bit names  with  UTF8
1707        replaced by UTF16 or UTF32, respectively. This facility is in fact just
1708        cosmetic; the 16-bit and 32-bit option names define the same  bit  val-
1709        ues.
1710
1711        References to bytes and UTF-8 in this document should be read as refer-
1712        ences to 16-bit data units and UTF-16 when using the 16-bit library, or
1713        32-bit  data  units  and  UTF-32  when using the 32-bit library, unless
1714        specified otherwise.  More details of the specific differences for  the
1715        16-bit and 32-bit libraries are given in the pcre16 and pcre32 pages.
1716
1717
1718 PCRE API OVERVIEW
1719
1720        PCRE has its own native API, which is described in this document. There
1721        are also some wrapper functions (for the 8-bit library only) that  cor-
1722        respond  to  the  POSIX  regular  expression  API, but they do not give
1723        access to all the functionality. They are described  in  the  pcreposix
1724        documentation.  Both  of these APIs define a set of C function calls. A
1725        C++ wrapper (again for the 8-bit library only) is also distributed with
1726        PCRE. It is documented in the pcrecpp page.
1727
1728        The  native  API  C  function prototypes are defined in the header file
1729        pcre.h, and on Unix-like systems the (8-bit) library itself  is  called
1730        libpcre.  It  can  normally be accessed by adding -lpcre to the command
1731        for linking an application that uses PCRE. The header file defines  the
1732        macros PCRE_MAJOR and PCRE_MINOR to contain the major and minor release
1733        numbers for the library. Applications can use these to include  support
1734        for different releases of PCRE.
1735
1736        In a Windows environment, if you want to statically link an application
1737        program against a non-dll pcre.a  file,  you  must  define  PCRE_STATIC
1738        before  including  pcre.h or pcrecpp.h, because otherwise the pcre_mal-
1739        loc()   and   pcre_free()   exported   functions   will   be   declared
1740        __declspec(dllimport), with unwanted results.
1741
1742        The   functions   pcre_compile(),  pcre_compile2(),  pcre_study(),  and
1743        pcre_exec() are used for compiling and matching regular expressions  in
1744        a  Perl-compatible  manner. A sample program that demonstrates the sim-
1745        plest way of using them is provided in the file  called  pcredemo.c  in
1746        the PCRE source distribution. A listing of this program is given in the
1747        pcredemo documentation, and the pcresample documentation describes  how
1748        to compile and run it.
1749
1750        Just-in-time  compiler  support is an optional feature of PCRE that can
1751        be built in appropriate hardware environments. It greatly speeds up the
1752        matching  performance  of  many  patterns.  Simple  programs can easily
1753        request that it be used if available, by  setting  an  option  that  is
1754        ignored  when  it is not relevant. More complicated programs might need
1755        to    make    use    of    the    functions     pcre_jit_stack_alloc(),
1756        pcre_jit_stack_free(),  and pcre_assign_jit_stack() in order to control
1757        the JIT code's memory usage.
1758
1759        From release 8.32 there is also a direct interface for  JIT  execution,
1760        which  gives  improved performance. The JIT-specific functions are dis-
1761        cussed in the pcrejit documentation.
1762
1763        A second matching function, pcre_dfa_exec(), which is not Perl-compati-
1764        ble,  is  also provided. This uses a different algorithm for the match-
1765        ing. The alternative algorithm finds all possible matches (at  a  given
1766        point  in  the  subject), and scans the subject just once (unless there
1767        are lookbehind assertions). However, this  algorithm  does  not  return
1768        captured  substrings.  A description of the two matching algorithms and
1769        their advantages and disadvantages is given in the  pcrematching  docu-
1770        mentation.
1771
1772        In  addition  to  the  main compiling and matching functions, there are
1773        convenience functions for extracting captured substrings from a subject
1774        string that is matched by pcre_exec(). They are:
1775
1776          pcre_copy_substring()
1777          pcre_copy_named_substring()
1778          pcre_get_substring()
1779          pcre_get_named_substring()
1780          pcre_get_substring_list()
1781          pcre_get_stringnumber()
1782          pcre_get_stringtable_entries()
1783
1784        pcre_free_substring() and pcre_free_substring_list() are also provided,
1785        to free the memory used for extracted strings.
1786
1787        The function pcre_maketables() is used to  build  a  set  of  character
1788        tables   in   the   current   locale  for  passing  to  pcre_compile(),
1789        pcre_exec(), or pcre_dfa_exec(). This is an optional facility  that  is
1790        provided  for  specialist  use.  Most  commonly,  no special tables are
1791        passed, in which case internal tables that are generated when  PCRE  is
1792        built are used.
1793
1794        The  function  pcre_fullinfo()  is used to find out information about a
1795        compiled pattern. The function pcre_version() returns a  pointer  to  a
1796        string containing the version of PCRE and its date of release.
1797
1798        The  function  pcre_refcount()  maintains  a  reference count in a data
1799        block containing a compiled pattern. This is provided for  the  benefit
1800        of object-oriented applications.
1801
1802        The  global  variables  pcre_malloc and pcre_free initially contain the
1803        entry points of the standard malloc()  and  free()  functions,  respec-
1804        tively. PCRE calls the memory management functions via these variables,
1805        so a calling program can replace them if it  wishes  to  intercept  the
1806        calls. This should be done before calling any PCRE functions.
1807
1808        The  global  variables  pcre_stack_malloc  and pcre_stack_free are also
1809        indirections to memory management functions.  These  special  functions
1810        are  used  only  when  PCRE is compiled to use the heap for remembering
1811        data, instead of recursive function calls, when running the pcre_exec()
1812        function.  See  the  pcrebuild  documentation  for details of how to do
1813        this. It is a non-standard way of building PCRE, for  use  in  environ-
1814        ments  that  have  limited stacks. Because of the greater use of memory
1815        management, it runs more slowly. Separate  functions  are  provided  so
1816        that  special-purpose  external  code  can  be used for this case. When
1817        used, these functions always allocate memory blocks of the  same  size.
1818        There  is  a discussion about PCRE's stack usage in the pcrestack docu-
1819        mentation.
1820
1821        The global variable pcre_callout initially contains NULL. It can be set
1822        by  the  caller  to  a "callout" function, which PCRE will then call at
1823        specified points during a matching operation. Details are given in  the
1824        pcrecallout documentation.
1825
1826        The global variable pcre_stack_guard initially contains NULL. It can be
1827        set by the caller to a function that is  called  by  PCRE  whenever  it
1828        starts  to  compile a parenthesized part of a pattern. When parentheses
1829        are nested, PCRE uses recursive function calls, which use up the system
1830        stack.  This  function is provided so that applications with restricted
1831        stacks can force a compilation error if the stack runs out.  The  func-
1832        tion should return zero if all is well, or non-zero to force an error.
1833
1834
1835 NEWLINES
1836
1837        PCRE  supports five different conventions for indicating line breaks in
1838        strings: a single CR (carriage return) character, a  single  LF  (line-
1839        feed) character, the two-character sequence CRLF, any of the three pre-
1840        ceding, or any Unicode newline sequence. The Unicode newline  sequences
1841        are  the  three just mentioned, plus the single characters VT (vertical
1842        tab, U+000B), FF (form feed, U+000C), NEL (next line, U+0085), LS (line
1843        separator, U+2028), and PS (paragraph separator, U+2029).
1844
1845        Each  of  the first three conventions is used by at least one operating
1846        system as its standard newline sequence. When PCRE is built, a  default
1847        can  be  specified.  The default default is LF, which is the Unix stan-
1848        dard. When PCRE is run, the default can be overridden,  either  when  a
1849        pattern is compiled, or when it is matched.
1850
1851        At compile time, the newline convention can be specified by the options
1852        argument of pcre_compile(), or it can be specified by special  text  at
1853        the start of the pattern itself; this overrides any other settings. See
1854        the pcrepattern page for details of the special character sequences.
1855
1856        In the PCRE documentation the word "newline" is used to mean "the char-
1857        acter  or pair of characters that indicate a line break". The choice of
1858        newline convention affects the handling of  the  dot,  circumflex,  and
1859        dollar metacharacters, the handling of #-comments in /x mode, and, when
1860        CRLF is a recognized line ending sequence, the match position  advance-
1861        ment for a non-anchored pattern. There is more detail about this in the
1862        section on pcre_exec() options below.
1863
1864        The choice of newline convention does not affect the interpretation  of
1865        the  \n  or  \r  escape  sequences, nor does it affect what \R matches,
1866        which is controlled in a similar way, but by separate options.
1867
1868
1869 MULTITHREADING
1870
1871        The PCRE functions can be used in  multi-threading  applications,  with
1872        the  proviso  that  the  memory  management  functions  pointed  to  by
1873        pcre_malloc, pcre_free, pcre_stack_malloc, and pcre_stack_free, and the
1874        callout  and  stack-checking  functions  pointed to by pcre_callout and
1875        pcre_stack_guard, are shared by all threads.
1876
1877        The compiled form of a regular expression is not altered during  match-
1878        ing, so the same compiled pattern can safely be used by several threads
1879        at once.
1880
1881        If the just-in-time optimization feature is being used, it needs  sepa-
1882        rate  memory stack areas for each thread. See the pcrejit documentation
1883        for more details.
1884
1885
1886 SAVING PRECOMPILED PATTERNS FOR LATER USE
1887
1888        The compiled form of a regular expression can be saved and re-used at a
1889        later  time,  possibly by a different program, and even on a host other
1890        than the one on which  it  was  compiled.  Details  are  given  in  the
1891        pcreprecompile  documentation,  which  includes  a  description  of the
1892        pcre_pattern_to_host_byte_order() function. However, compiling a  regu-
1893        lar  expression  with one version of PCRE for use with a different ver-
1894        sion is not guaranteed to work and may cause crashes.
1895
1896
1897 CHECKING BUILD-TIME OPTIONS
1898
1899        int pcre_config(int what, void *where);
1900
1901        The function pcre_config() makes it possible for a PCRE client to  dis-
1902        cover which optional features have been compiled into the PCRE library.
1903        The pcrebuild documentation has more details about these optional  fea-
1904        tures.
1905
1906        The  first  argument  for pcre_config() is an integer, specifying which
1907        information is required; the second argument is a pointer to a variable
1908        into  which  the  information  is placed. The returned value is zero on
1909        success, or the negative error code PCRE_ERROR_BADOPTION if  the  value
1910        in  the  first argument is not recognized. The following information is
1911        available:
1912
1913          PCRE_CONFIG_UTF8
1914
1915        The output is an integer that is set to one if UTF-8 support is  avail-
1916        able;  otherwise it is set to zero. This value should normally be given
1917        to the 8-bit version of this function, pcre_config(). If it is given to
1918        the   16-bit  or  32-bit  version  of  this  function,  the  result  is
1919        PCRE_ERROR_BADOPTION.
1920
1921          PCRE_CONFIG_UTF16
1922
1923        The output is an integer that is set to one if UTF-16 support is avail-
1924        able;  otherwise it is set to zero. This value should normally be given
1925        to the 16-bit version of this function, pcre16_config(). If it is given
1926        to  the  8-bit  or  32-bit  version  of  this  function,  the result is
1927        PCRE_ERROR_BADOPTION.
1928
1929          PCRE_CONFIG_UTF32
1930
1931        The output is an integer that is set to one if UTF-32 support is avail-
1932        able;  otherwise it is set to zero. This value should normally be given
1933        to the 32-bit version of this function, pcre32_config(). If it is given
1934        to  the  8-bit  or  16-bit  version  of  this  function,  the result is
1935        PCRE_ERROR_BADOPTION.
1936
1937          PCRE_CONFIG_UNICODE_PROPERTIES
1938
1939        The output is an integer that is set to  one  if  support  for  Unicode
1940        character properties is available; otherwise it is set to zero.
1941
1942          PCRE_CONFIG_JIT
1943
1944        The output is an integer that is set to one if support for just-in-time
1945        compiling is available; otherwise it is set to zero.
1946
1947          PCRE_CONFIG_JITTARGET
1948
1949        The output is a pointer to a zero-terminated "const char *" string.  If
1950        JIT support is available, the string contains the name of the architec-
1951        ture for which the JIT compiler is configured, for example  "x86  32bit
1952        (little  endian  +  unaligned)".  If  JIT support is not available, the
1953        result is NULL.
1954
1955          PCRE_CONFIG_NEWLINE
1956
1957        The output is an integer whose value specifies  the  default  character
1958        sequence  that  is recognized as meaning "newline". The values that are
1959        supported in ASCII/Unicode environments are: 10 for LF, 13 for CR, 3338
1960        for  CRLF,  -2 for ANYCRLF, and -1 for ANY. In EBCDIC environments, CR,
1961        ANYCRLF, and ANY yield the same values. However, the value  for  LF  is
1962        normally  21, though some EBCDIC environments use 37. The corresponding
1963        values for CRLF are 3349 and 3365. The default should  normally  corre-
1964        spond to the standard sequence for your operating system.
1965
1966          PCRE_CONFIG_BSR
1967
1968        The output is an integer whose value indicates what character sequences
1969        the \R escape sequence matches by default. A value of 0 means  that  \R
1970        matches  any  Unicode  line ending sequence; a value of 1 means that \R
1971        matches only CR, LF, or CRLF. The default can be overridden when a pat-
1972        tern is compiled or matched.
1973
1974          PCRE_CONFIG_LINK_SIZE
1975
1976        The  output  is  an  integer that contains the number of bytes used for
1977        internal  linkage  in  compiled  regular  expressions.  For  the  8-bit
1978        library, the value can be 2, 3, or 4. For the 16-bit library, the value
1979        is either 2 or 4 and is  still  a  number  of  bytes.  For  the  32-bit
1980        library, the value is either 2 or 4 and is still a number of bytes. The
1981        default value of 2 is sufficient for all but the most massive patterns,
1982        since  it  allows  the compiled pattern to be up to 64K in size. Larger
1983        values allow larger regular expressions to be compiled, at the  expense
1984        of slower matching.
1985
1986          PCRE_CONFIG_POSIX_MALLOC_THRESHOLD
1987
1988        The  output  is  an integer that contains the threshold above which the
1989        POSIX interface uses malloc() for output vectors. Further  details  are
1990        given in the pcreposix documentation.
1991
1992          PCRE_CONFIG_PARENS_LIMIT
1993
1994        The output is a long integer that gives the maximum depth of nesting of
1995        parentheses (of any kind) in a pattern. This limit is  imposed  to  cap
1996        the amount of system stack used when a pattern is compiled. It is spec-
1997        ified when PCRE is built; the default is 250. This limit does not  take
1998        into account the stack that may already be used by the calling applica-
1999        tion. For finer control over compilation stack usage,  you  can  set  a
2000        pointer to an external checking function in pcre_stack_guard.
2001
2002          PCRE_CONFIG_MATCH_LIMIT
2003
2004        The  output is a long integer that gives the default limit for the num-
2005        ber of internal matching function calls  in  a  pcre_exec()  execution.
2006        Further details are given with pcre_exec() below.
2007
2008          PCRE_CONFIG_MATCH_LIMIT_RECURSION
2009
2010        The output is a long integer that gives the default limit for the depth
2011        of  recursion  when  calling  the  internal  matching  function  in   a
2012        pcre_exec()  execution.  Further  details  are  given  with pcre_exec()
2013        below.
2014
2015          PCRE_CONFIG_STACKRECURSE
2016
2017        The output is an integer that is set to one if internal recursion  when
2018        running pcre_exec() is implemented by recursive function calls that use
2019        the stack to remember their state. This is the usual way that  PCRE  is
2020        compiled. The output is zero if PCRE was compiled to use blocks of data
2021        on the  heap  instead  of  recursive  function  calls.  In  this  case,
2022        pcre_stack_malloc  and  pcre_stack_free  are  called  to  manage memory
2023        blocks on the heap, thus avoiding the use of the stack.
2024
2025
2026 COMPILING A PATTERN
2027
2028        pcre *pcre_compile(const char *pattern, int options,
2029             const char **errptr, int *erroffset,
2030             const unsigned char *tableptr);
2031
2032        pcre *pcre_compile2(const char *pattern, int options,
2033             int *errorcodeptr,
2034             const char **errptr, int *erroffset,
2035             const unsigned char *tableptr);
2036
2037        Either of the functions pcre_compile() or pcre_compile2() can be called
2038        to compile a pattern into an internal form. The only difference between
2039        the two interfaces is that pcre_compile2() has an additional  argument,
2040        errorcodeptr,  via  which  a  numerical  error code can be returned. To
2041        avoid too much repetition, we refer just to pcre_compile()  below,  but
2042        the information applies equally to pcre_compile2().
2043
2044        The pattern is a C string terminated by a binary zero, and is passed in
2045        the pattern argument. A pointer to a single block  of  memory  that  is
2046        obtained  via  pcre_malloc is returned. This contains the compiled code
2047        and related data. The pcre type is defined for the returned block; this
2048        is a typedef for a structure whose contents are not externally defined.
2049        It is up to the caller to free the memory (via pcre_free) when it is no
2050        longer required.
2051
2052        Although  the compiled code of a PCRE regex is relocatable, that is, it
2053        does not depend on memory location, the complete pcre data block is not
2054        fully  relocatable, because it may contain a copy of the tableptr argu-
2055        ment, which is an address (see below).
2056
2057        The options argument contains various bit settings that affect the com-
2058        pilation.  It  should be zero if no options are required. The available
2059        options are described below. Some of them (in  particular,  those  that
2060        are  compatible with Perl, but some others as well) can also be set and
2061        unset from within the pattern (see  the  detailed  description  in  the
2062        pcrepattern  documentation). For those options that can be different in
2063        different parts of the pattern, the contents of  the  options  argument
2064        specifies their settings at the start of compilation and execution. The
2065        PCRE_ANCHORED, PCRE_BSR_xxx, PCRE_NEWLINE_xxx, PCRE_NO_UTF8_CHECK,  and
2066        PCRE_NO_START_OPTIMIZE  options  can  be set at the time of matching as
2067        well as at compile time.
2068
2069        If errptr is NULL, pcre_compile() returns NULL immediately.  Otherwise,
2070        if  compilation  of  a  pattern fails, pcre_compile() returns NULL, and
2071        sets the variable pointed to by errptr to point to a textual error mes-
2072        sage. This is a static string that is part of the library. You must not
2073        try to free it. Normally, the offset from the start of the  pattern  to
2074        the data unit that was being processed when the error was discovered is
2075        placed in the variable pointed to by erroffset, which must not be  NULL
2076        (if  it is, an immediate error is given). However, for an invalid UTF-8
2077        or UTF-16 string, the offset is that of the  first  data  unit  of  the
2078        failing character.
2079
2080        Some  errors are not detected until the whole pattern has been scanned;
2081        in these cases, the offset passed back is the length  of  the  pattern.
2082        Note  that  the  offset is in data units, not characters, even in a UTF
2083        mode. It may sometimes point into the middle of a UTF-8 or UTF-16 char-
2084        acter.
2085
2086        If  pcre_compile2()  is  used instead of pcre_compile(), and the error-
2087        codeptr argument is not NULL, a non-zero error code number is  returned
2088        via  this argument in the event of an error. This is in addition to the
2089        textual error message. Error codes and messages are listed below.
2090
2091        If the final argument, tableptr, is NULL, PCRE uses a  default  set  of
2092        character  tables  that  are  built  when  PCRE  is compiled, using the
2093        default C locale. Otherwise, tableptr must be an address  that  is  the
2094        result  of  a  call to pcre_maketables(). This value is stored with the
2095        compiled pattern, and used again  by  pcre_exec()  and  pcre_dfa_exec()
2096        when  the  pattern  is matched. For more discussion, see the section on
2097        locale support below.
2098
2099        This code fragment shows a typical straightforward  call  to  pcre_com-
2100        pile():
2101
2102          pcre *re;
2103          const char *error;
2104          int erroffset;
2105          re = pcre_compile(
2106            "^A.*Z",          /* the pattern */
2107            0,                /* default options */
2108            &error,           /* for error message */
2109            &erroffset,       /* for error offset */
2110            NULL);            /* use default character tables */
2111
2112        The  following  names  for option bits are defined in the pcre.h header
2113        file:
2114
2115          PCRE_ANCHORED
2116
2117        If this bit is set, the pattern is forced to be "anchored", that is, it
2118        is  constrained to match only at the first matching point in the string
2119        that is being searched (the "subject string"). This effect can also  be
2120        achieved  by appropriate constructs in the pattern itself, which is the
2121        only way to do it in Perl.
2122
2123          PCRE_AUTO_CALLOUT
2124
2125        If this bit is set, pcre_compile() automatically inserts callout items,
2126        all  with  number  255, before each pattern item. For discussion of the
2127        callout facility, see the pcrecallout documentation.
2128
2129          PCRE_BSR_ANYCRLF
2130          PCRE_BSR_UNICODE
2131
2132        These options (which are mutually exclusive) control what the \R escape
2133        sequence  matches.  The choice is either to match only CR, LF, or CRLF,
2134        or to match any Unicode newline sequence. The default is specified when
2135        PCRE is built. It can be overridden from within the pattern, or by set-
2136        ting an option when a compiled pattern is matched.
2137
2138          PCRE_CASELESS
2139
2140        If this bit is set, letters in the pattern match both upper  and  lower
2141        case  letters.  It  is  equivalent  to  Perl's /i option, and it can be
2142        changed within a pattern by a (?i) option setting. In UTF-8 mode,  PCRE
2143        always  understands the concept of case for characters whose values are
2144        less than 128, so caseless matching is always possible. For  characters
2145        with  higher  values,  the concept of case is supported if PCRE is com-
2146        piled with Unicode property support, but not otherwise. If you want  to
2147        use  caseless  matching  for  characters 128 and above, you must ensure
2148        that PCRE is compiled with Unicode property support  as  well  as  with
2149        UTF-8 support.
2150
2151          PCRE_DOLLAR_ENDONLY
2152
2153        If  this bit is set, a dollar metacharacter in the pattern matches only
2154        at the end of the subject string. Without this option,  a  dollar  also
2155        matches  immediately before a newline at the end of the string (but not
2156        before any other newlines). The PCRE_DOLLAR_ENDONLY option  is  ignored
2157        if  PCRE_MULTILINE  is  set.   There is no equivalent to this option in
2158        Perl, and no way to set it within a pattern.
2159
2160          PCRE_DOTALL
2161
2162        If this bit is set, a dot metacharacter in the pattern matches a  char-
2163        acter of any value, including one that indicates a newline. However, it
2164        only ever matches one character, even if newlines are  coded  as  CRLF.
2165        Without  this option, a dot does not match when the current position is
2166        at a newline. This option is equivalent to Perl's /s option, and it can
2167        be  changed within a pattern by a (?s) option setting. A negative class
2168        such as [^a] always matches newline characters, independent of the set-
2169        ting of this option.
2170
2171          PCRE_DUPNAMES
2172
2173        If  this  bit is set, names used to identify capturing subpatterns need
2174        not be unique. This can be helpful for certain types of pattern when it
2175        is  known  that  only  one instance of the named subpattern can ever be
2176        matched. There are more details of named subpatterns  below;  see  also
2177        the pcrepattern documentation.
2178
2179          PCRE_EXTENDED
2180
2181        If  this  bit  is  set,  most white space characters in the pattern are
2182        totally ignored except when escaped or inside a character  class.  How-
2183        ever,  white  space  is  not  allowed within sequences such as (?> that
2184        introduce various parenthesized subpatterns,  nor  within  a  numerical
2185        quantifier  such as {1,3}.  However, ignorable white space is permitted
2186        between an item and a following quantifier and between a quantifier and
2187        a following + that indicates possessiveness.
2188
2189        White space did not used to include the VT character (code 11), because
2190        Perl did not treat this character as white space. However, Perl changed
2191        at  release  5.18,  so  PCRE  followed  at  release 8.34, and VT is now
2192        treated as white space.
2193
2194        PCRE_EXTENDED also causes characters between an unescaped #  outside  a
2195        character  class  and  the  next  newline,  inclusive,  to  be ignored.
2196        PCRE_EXTENDED is equivalent to Perl's /x option, and it can be  changed
2197        within a pattern by a (?x) option setting.
2198
2199        Which  characters  are  interpreted  as  newlines  is controlled by the
2200        options passed to pcre_compile() or by a special sequence at the  start
2201        of  the  pattern, as described in the section entitled "Newline conven-
2202        tions" in the pcrepattern documentation. Note that the end of this type
2203        of  comment  is  a  literal  newline  sequence  in  the pattern; escape
2204        sequences that happen to represent a newline do not count.
2205
2206        This option makes it possible to include  comments  inside  complicated
2207        patterns.   Note,  however,  that this applies only to data characters.
2208        White space  characters  may  never  appear  within  special  character
2209        sequences in a pattern, for example within the sequence (?( that intro-
2210        duces a conditional subpattern.
2211
2212          PCRE_EXTRA
2213
2214        This option was invented in order to turn on  additional  functionality
2215        of  PCRE  that  is  incompatible with Perl, but it is currently of very
2216        little use. When set, any backslash in a pattern that is followed by  a
2217        letter  that  has  no  special  meaning causes an error, thus reserving
2218        these combinations for future expansion. By  default,  as  in  Perl,  a
2219        backslash  followed by a letter with no special meaning is treated as a
2220        literal. (Perl can, however, be persuaded to give an error for this, by
2221        running  it with the -w option.) There are at present no other features
2222        controlled by this option. It can also be set by a (?X) option  setting
2223        within a pattern.
2224
2225          PCRE_FIRSTLINE
2226
2227        If  this  option  is  set,  an  unanchored pattern is required to match
2228        before or at the first  newline  in  the  subject  string,  though  the
2229        matched text may continue over the newline.
2230
2231          PCRE_JAVASCRIPT_COMPAT
2232
2233        If this option is set, PCRE's behaviour is changed in some ways so that
2234        it is compatible with JavaScript rather than Perl. The changes  are  as
2235        follows:
2236
2237        (1)  A  lone  closing square bracket in a pattern causes a compile-time
2238        error, because this is illegal in JavaScript (by default it is  treated
2239        as a data character). Thus, the pattern AB]CD becomes illegal when this
2240        option is set.
2241
2242        (2) At run time, a back reference to an unset subpattern group  matches
2243        an  empty  string (by default this causes the current matching alterna-
2244        tive to fail). A pattern such as (\1)(a) succeeds when this  option  is
2245        set  (assuming  it can find an "a" in the subject), whereas it fails by
2246        default, for Perl compatibility.
2247
2248        (3) \U matches an upper case "U" character; by default \U causes a com-
2249        pile time error (Perl uses \U to upper case subsequent characters).
2250
2251        (4) \u matches a lower case "u" character unless it is followed by four
2252        hexadecimal digits, in which case the hexadecimal  number  defines  the
2253        code  point  to match. By default, \u causes a compile time error (Perl
2254        uses it to upper case the following character).
2255
2256        (5) \x matches a lower case "x" character unless it is followed by  two
2257        hexadecimal  digits,  in  which case the hexadecimal number defines the
2258        code point to match. By default, as in Perl, a  hexadecimal  number  is
2259        always expected after \x, but it may have zero, one, or two digits (so,
2260        for example, \xz matches a binary zero character followed by z).
2261
2262          PCRE_MULTILINE
2263
2264        By default, for the purposes of matching "start of line"  and  "end  of
2265        line", PCRE treats the subject string as consisting of a single line of
2266        characters, even if it actually contains newlines. The "start of  line"
2267        metacharacter (^) matches only at the start of the string, and the "end
2268        of line" metacharacter ($) matches only at the end of  the  string,  or
2269        before  a terminating newline (except when PCRE_DOLLAR_ENDONLY is set).
2270        Note, however, that unless PCRE_DOTALL  is  set,  the  "any  character"
2271        metacharacter  (.)  does not match at a newline. This behaviour (for ^,
2272        $, and dot) is the same as Perl.
2273
2274        When PCRE_MULTILINE it is set, the "start of line" and  "end  of  line"
2275        constructs  match  immediately following or immediately before internal
2276        newlines in the subject string, respectively, as well as  at  the  very
2277        start  and  end.  This is equivalent to Perl's /m option, and it can be
2278        changed within a pattern by a (?m) option setting. If there are no new-
2279        lines  in  a  subject string, or no occurrences of ^ or $ in a pattern,
2280        setting PCRE_MULTILINE has no effect.
2281
2282          PCRE_NEVER_UTF
2283
2284        This option locks out interpretation of the pattern as UTF-8 (or UTF-16
2285        or  UTF-32  in the 16-bit and 32-bit libraries). In particular, it pre-
2286        vents the creator of the pattern from switching to  UTF  interpretation
2287        by starting the pattern with (*UTF). This may be useful in applications
2288        that  process  patterns  from  external  sources.  The  combination  of
2289        PCRE_UTF8 and PCRE_NEVER_UTF also causes an error.
2290
2291          PCRE_NEWLINE_CR
2292          PCRE_NEWLINE_LF
2293          PCRE_NEWLINE_CRLF
2294          PCRE_NEWLINE_ANYCRLF
2295          PCRE_NEWLINE_ANY
2296
2297        These  options  override the default newline definition that was chosen
2298        when PCRE was built. Setting the first or the second specifies  that  a
2299        newline  is  indicated  by a single character (CR or LF, respectively).
2300        Setting PCRE_NEWLINE_CRLF specifies that a newline is indicated by  the
2301        two-character  CRLF  sequence.  Setting  PCRE_NEWLINE_ANYCRLF specifies
2302        that any of the three preceding sequences should be recognized. Setting
2303        PCRE_NEWLINE_ANY  specifies that any Unicode newline sequence should be
2304        recognized.
2305
2306        In an ASCII/Unicode environment, the Unicode newline sequences are  the
2307        three  just  mentioned,  plus  the  single characters VT (vertical tab,
2308        U+000B), FF (form feed, U+000C), NEL (next line, U+0085), LS (line sep-
2309        arator,  U+2028),  and  PS (paragraph separator, U+2029). For the 8-bit
2310        library, the last two are recognized only in UTF-8 mode.
2311
2312        When PCRE is compiled to run in an EBCDIC (mainframe) environment,  the
2313        code for CR is 0x0d, the same as ASCII. However, the character code for
2314        LF is normally 0x15, though in some EBCDIC environments 0x25  is  used.
2315        Whichever  of  these  is  not LF is made to correspond to Unicode's NEL
2316        character. EBCDIC codes are all less than 256. For  more  details,  see
2317        the pcrebuild documentation.
2318
2319        The  newline  setting  in  the  options  word  uses three bits that are
2320        treated as a number, giving eight possibilities. Currently only six are
2321        used  (default  plus the five values above). This means that if you set
2322        more than one newline option, the combination may or may not be  sensi-
2323        ble. For example, PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to
2324        PCRE_NEWLINE_CRLF, but other combinations may yield unused numbers  and
2325        cause an error.
2326
2327        The  only  time  that a line break in a pattern is specially recognized
2328        when compiling is when PCRE_EXTENDED is set. CR and LF are white  space
2329        characters,  and so are ignored in this mode. Also, an unescaped # out-
2330        side a character class indicates a comment that lasts until  after  the
2331        next  line break sequence. In other circumstances, line break sequences
2332        in patterns are treated as literal data.
2333
2334        The newline option that is set at compile time becomes the default that
2335        is used for pcre_exec() and pcre_dfa_exec(), but it can be overridden.
2336
2337          PCRE_NO_AUTO_CAPTURE
2338
2339        If this option is set, it disables the use of numbered capturing paren-
2340        theses in the pattern. Any opening parenthesis that is not followed  by
2341        ?  behaves as if it were followed by ?: but named parentheses can still
2342        be used for capturing (and they acquire  numbers  in  the  usual  way).
2343        There is no equivalent of this option in Perl.
2344
2345          PCRE_NO_AUTO_POSSESS
2346
2347        If  this option is set, it disables "auto-possessification". This is an
2348        optimization that, for example, turns a+b into a++b in order  to  avoid
2349        backtracks  into  a+ that can never be successful. However, if callouts
2350        are in use, auto-possessification means that some  of  them  are  never
2351        taken. You can set this option if you want the matching functions to do
2352        a full unoptimized search and run all the callouts, but  it  is  mainly
2353        provided for testing purposes.
2354
2355          PCRE_NO_START_OPTIMIZE
2356
2357        This  is an option that acts at matching time; that is, it is really an
2358        option for pcre_exec() or pcre_dfa_exec(). If  it  is  set  at  compile
2359        time,  it is remembered with the compiled pattern and assumed at match-
2360        ing time. This is necessary if you want to use JIT  execution,  because
2361        the  JIT  compiler needs to know whether or not this option is set. For
2362        details see the discussion of PCRE_NO_START_OPTIMIZE below.
2363
2364          PCRE_UCP
2365
2366        This option changes the way PCRE processes \B, \b, \D, \d, \S, \s,  \W,
2367        \w,  and  some  of  the POSIX character classes. By default, only ASCII
2368        characters are recognized, but if PCRE_UCP is set,  Unicode  properties
2369        are  used instead to classify characters. More details are given in the
2370        section on generic character types in the pcrepattern page. If you  set
2371        PCRE_UCP,  matching  one of the items it affects takes much longer. The
2372        option is available only if PCRE has been compiled with  Unicode  prop-
2373        erty support.
2374
2375          PCRE_UNGREEDY
2376
2377        This  option  inverts  the "greediness" of the quantifiers so that they
2378        are not greedy by default, but become greedy if followed by "?". It  is
2379        not  compatible  with Perl. It can also be set by a (?U) option setting
2380        within the pattern.
2381
2382          PCRE_UTF8
2383
2384        This option causes PCRE to regard both the pattern and the  subject  as
2385        strings of UTF-8 characters instead of single-byte strings. However, it
2386        is available only when PCRE is built to include UTF  support.  If  not,
2387        the  use  of  this option provokes an error. Details of how this option
2388        changes the behaviour of PCRE are given in the pcreunicode page.
2389
2390          PCRE_NO_UTF8_CHECK
2391
2392        When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is
2393        automatically  checked.  There  is  a  discussion about the validity of
2394        UTF-8 strings in the pcreunicode page. If an invalid UTF-8 sequence  is
2395        found,  pcre_compile()  returns an error. If you already know that your
2396        pattern is valid, and you want to skip this check for performance  rea-
2397        sons,  you  can set the PCRE_NO_UTF8_CHECK option.  When it is set, the
2398        effect of passing an invalid UTF-8 string as a pattern is undefined. It
2399        may cause your program to crash or loop. Note that this option can also
2400        be passed to pcre_exec() and pcre_dfa_exec(), to suppress the  validity
2401        checking  of  subject strings only. If the same string is being matched
2402        many times, the option can be safely set for the second and  subsequent
2403        matchings to improve performance.
2404
2405
2406 COMPILATION ERROR CODES
2407
2408        The  following  table  lists  the  error  codes than may be returned by
2409        pcre_compile2(), along with the error messages that may be returned  by
2410        both  compiling  functions.  Note  that error messages are always 8-bit
2411        ASCII strings, even in 16-bit or 32-bit mode. As  PCRE  has  developed,
2412        some  error codes have fallen out of use. To avoid confusion, they have
2413        not been re-used.
2414
2415           0  no error
2416           1  \ at end of pattern
2417           2  \c at end of pattern
2418           3  unrecognized character follows \
2419           4  numbers out of order in {} quantifier
2420           5  number too big in {} quantifier
2421           6  missing terminating ] for character class
2422           7  invalid escape sequence in character class
2423           8  range out of order in character class
2424           9  nothing to repeat
2425          10  [this code is not in use]
2426          11  internal error: unexpected repeat
2427          12  unrecognized character after (? or (?-
2428          13  POSIX named classes are supported only within a class
2429          14  missing )
2430          15  reference to non-existent subpattern
2431          16  erroffset passed as NULL
2432          17  unknown option bit(s) set
2433          18  missing ) after comment
2434          19  [this code is not in use]
2435          20  regular expression is too large
2436          21  failed to get memory
2437          22  unmatched parentheses
2438          23  internal error: code overflow
2439          24  unrecognized character after (?<
2440          25  lookbehind assertion is not fixed length
2441          26  malformed number or name after (?(
2442          27  conditional group contains more than two branches
2443          28  assertion expected after (?(
2444          29  (?R or (?[+-]digits must be followed by )
2445          30  unknown POSIX class name
2446          31  POSIX collating elements are not supported
2447          32  this version of PCRE is compiled without UTF support
2448          33  [this code is not in use]
2449          34  character value in \x{} or \o{} is too large
2450          35  invalid condition (?(0)
2451          36  \C not allowed in lookbehind assertion
2452          37  PCRE does not support \L, \l, \N{name}, \U, or \u
2453          38  number after (?C is > 255
2454          39  closing ) for (?C expected
2455          40  recursive call could loop indefinitely
2456          41  unrecognized character after (?P
2457          42  syntax error in subpattern name (missing terminator)
2458          43  two named subpatterns have the same name
2459          44  invalid UTF-8 string (specifically UTF-8)
2460          45  support for \P, \p, and \X has not been compiled
2461          46  malformed \P or \p sequence
2462          47  unknown property name after \P or \p
2463          48  subpattern name is too long (maximum 32 characters)
2464          49  too many named subpatterns (maximum 10000)
2465          50  [this code is not in use]
2466          51  octal value is greater than \377 in 8-bit non-UTF-8 mode
2467          52  internal error: overran compiling workspace
2468          53  internal error: previously-checked referenced subpattern
2469                not found
2470          54  DEFINE group contains more than one branch
2471          55  repeating a DEFINE group is not allowed
2472          56  inconsistent NEWLINE options
2473          57  \g is not followed by a braced, angle-bracketed, or quoted
2474                name/number or by a plain number
2475          58  a numbered reference must not be zero
2476          59  an argument is not allowed for (*ACCEPT), (*FAIL), or (*COMMIT)
2477          60  (*VERB) not recognized or malformed
2478          61  number is too big
2479          62  subpattern name expected
2480          63  digit expected after (?+
2481          64  ] is an invalid data character in JavaScript compatibility mode
2482          65  different names for subpatterns of the same number are
2483                not allowed
2484          66  (*MARK) must have an argument
2485          67  this version of PCRE is not compiled with Unicode property
2486                support
2487          68  \c must be followed by an ASCII character
2488          69  \k is not followed by a braced, angle-bracketed, or quoted name
2489          70  internal error: unknown opcode in find_fixedlength()
2490          71  \N is not supported in a class
2491          72  too many forward references
2492          73  disallowed Unicode code point (>= 0xd800 && <= 0xdfff)
2493          74  invalid UTF-16 string (specifically UTF-16)
2494          75  name is too long in (*MARK), (*PRUNE), (*SKIP), or (*THEN)
2495          76  character value in \u.... sequence is too large
2496          77  invalid UTF-32 string (specifically UTF-32)
2497          78  setting UTF is disabled by the application
2498          79  non-hex character in \x{} (closing brace missing?)
2499          80  non-octal character in \o{} (closing brace missing?)
2500          81  missing opening brace after \o
2501          82  parentheses are too deeply nested
2502          83  invalid range in character class
2503          84  group name must start with a non-digit
2504          85  parentheses are too deeply nested (stack check)
2505
2506        The numbers 32 and 10000 in errors 48 and 49  are  defaults;  different
2507        values may be used if the limits were changed when PCRE was built.
2508
2509
2510 STUDYING A PATTERN
2511
2512        pcre_extra *pcre_study(const pcre *code, int options,
2513             const char **errptr);
2514
2515        If  a  compiled  pattern is going to be used several times, it is worth
2516        spending more time analyzing it in order to speed up the time taken for
2517        matching.  The function pcre_study() takes a pointer to a compiled pat-
2518        tern as its first argument. If studying the pattern produces additional
2519        information  that  will  help speed up matching, pcre_study() returns a
2520        pointer to a pcre_extra block, in which the study_data field points  to
2521        the results of the study.
2522
2523        The  returned  value  from  pcre_study()  can  be  passed  directly  to
2524        pcre_exec() or pcre_dfa_exec(). However, a pcre_extra block  also  con-
2525        tains  other  fields  that can be set by the caller before the block is
2526        passed; these are described below in the section on matching a pattern.
2527
2528        If studying the  pattern  does  not  produce  any  useful  information,
2529        pcre_study()  returns  NULL  by  default.  In that circumstance, if the
2530        calling program wants to pass any of the other fields to pcre_exec() or
2531        pcre_dfa_exec(),  it  must set up its own pcre_extra block. However, if
2532        pcre_study() is called  with  the  PCRE_STUDY_EXTRA_NEEDED  option,  it
2533        returns a pcre_extra block even if studying did not find any additional
2534        information. It may still return NULL, however, if an error  occurs  in
2535        pcre_study().
2536
2537        The  second  argument  of  pcre_study() contains option bits. There are
2538        three further options in addition to PCRE_STUDY_EXTRA_NEEDED:
2539
2540          PCRE_STUDY_JIT_COMPILE
2541          PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE
2542          PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE
2543
2544        If any of these are set, and the just-in-time  compiler  is  available,
2545        the  pattern  is  further compiled into machine code that executes much
2546        faster than the pcre_exec()  interpretive  matching  function.  If  the
2547        just-in-time  compiler is not available, these options are ignored. All
2548        undefined bits in the options argument must be zero.
2549
2550        JIT compilation is a heavyweight optimization. It can  take  some  time
2551        for  patterns  to  be analyzed, and for one-off matches and simple pat-
2552        terns the benefit of faster execution might be offset by a much  slower
2553        study time.  Not all patterns can be optimized by the JIT compiler. For
2554        those that cannot be handled, matching automatically falls back to  the
2555        pcre_exec()  interpreter.  For more details, see the pcrejit documenta-
2556        tion.
2557
2558        The third argument for pcre_study() is a pointer for an error  message.
2559        If  studying  succeeds  (even  if no data is returned), the variable it
2560        points to is set to NULL. Otherwise it is set to  point  to  a  textual
2561        error message. This is a static string that is part of the library. You
2562        must not try to free it. You should test the  error  pointer  for  NULL
2563        after calling pcre_study(), to be sure that it has run successfully.
2564
2565        When  you are finished with a pattern, you can free the memory used for
2566        the study data by calling pcre_free_study(). This function was added to
2567        the  API  for  release  8.20. For earlier versions, the memory could be
2568        freed with pcre_free(), just like the pattern itself. This  will  still
2569        work  in  cases where JIT optimization is not used, but it is advisable
2570        to change to the new function when convenient.
2571
2572        This is a typical way in which pcre_study() is used (except that  in  a
2573        real application there should be tests for errors):
2574
2575          int rc;
2576          pcre *re;
2577          pcre_extra *sd;
2578          re = pcre_compile("pattern", 0, &error, &erroroffset, NULL);
2579          sd = pcre_study(
2580            re,             /* result of pcre_compile() */
2581            0,              /* no options */
2582            &error);        /* set to NULL or points to a message */
2583          rc = pcre_exec(   /* see below for details of pcre_exec() options */
2584            re, sd, "subject", 7, 0, 0, ovector, 30);
2585          ...
2586          pcre_free_study(sd);
2587          pcre_free(re);
2588
2589        Studying a pattern does two things: first, a lower bound for the length
2590        of subject string that is needed to match the pattern is computed. This
2591        does not mean that there are any strings of that length that match, but
2592        it does guarantee that no shorter strings match. The value is  used  to
2593        avoid wasting time by trying to match strings that are shorter than the
2594        lower bound. You can find out the value in a calling  program  via  the
2595        pcre_fullinfo() function.
2596
2597        Studying a pattern is also useful for non-anchored patterns that do not
2598        have a single fixed starting character. A bitmap of  possible  starting
2599        bytes  is  created. This speeds up finding a position in the subject at
2600        which to start matching. (In 16-bit mode, the bitmap is used for 16-bit
2601        values  less  than  256.  In 32-bit mode, the bitmap is used for 32-bit
2602        values less than 256.)
2603
2604        These two optimizations apply to both pcre_exec() and  pcre_dfa_exec(),
2605        and  the  information  is also used by the JIT compiler.  The optimiza-
2606        tions can be disabled by  setting  the  PCRE_NO_START_OPTIMIZE  option.
2607        You  might want to do this if your pattern contains callouts or (*MARK)
2608        and you want to make use of these facilities in  cases  where  matching
2609        fails.
2610
2611        PCRE_NO_START_OPTIMIZE  can be specified at either compile time or exe-
2612        cution  time.  However,  if   PCRE_NO_START_OPTIMIZE   is   passed   to
2613        pcre_exec(), (that is, after any JIT compilation has happened) JIT exe-
2614        cution is disabled. For JIT execution to work with  PCRE_NO_START_OPTI-
2615        MIZE, the option must be set at compile time.
2616
2617        There is a longer discussion of PCRE_NO_START_OPTIMIZE below.
2618
2619
2620 LOCALE SUPPORT
2621
2622        PCRE  handles  caseless matching, and determines whether characters are
2623        letters, digits, or whatever, by reference to a set of tables,  indexed
2624        by  character  code point. When running in UTF-8 mode, or in the 16- or
2625        32-bit libraries, this applies only to characters with code points less
2626        than  256.  By  default,  higher-valued code points never match escapes
2627        such as \w or \d. However, if PCRE is built with Unicode property  sup-
2628        port,  all  characters can be tested with \p and \P, or, alternatively,
2629        the PCRE_UCP option can be set when a pattern is compiled; this  causes
2630        \w  and friends to use Unicode property support instead of the built-in
2631        tables.
2632
2633        The use of locales with Unicode is discouraged.  If  you  are  handling
2634        characters  with  code  points  greater than 128, you should either use
2635        Unicode support, or use locales, but not try to mix the two.
2636
2637        PCRE contains an internal set of tables that are used  when  the  final
2638        argument  of  pcre_compile()  is  NULL.  These  are sufficient for many
2639        applications.  Normally, the internal tables recognize only ASCII char-
2640        acters. However, when PCRE is built, it is possible to cause the inter-
2641        nal tables to be rebuilt in the default "C" locale of the local system,
2642        which may cause them to be different.
2643
2644        The  internal tables can always be overridden by tables supplied by the
2645        application that calls PCRE. These may be created in a different locale
2646        from  the  default.  As more and more applications change to using Uni-
2647        code, the need for this locale support is expected to die away.
2648
2649        External tables are built by calling  the  pcre_maketables()  function,
2650        which  has no arguments, in the relevant locale. The result can then be
2651        passed to pcre_compile() as often as necessary. For example,  to  build
2652        and  use  tables  that  are  appropriate  for  the French locale (where
2653        accented characters with values greater than 128 are  treated  as  let-
2654        ters), the following code could be used:
2655
2656          setlocale(LC_CTYPE, "fr_FR");
2657          tables = pcre_maketables();
2658          re = pcre_compile(..., tables);
2659
2660        The  locale  name "fr_FR" is used on Linux and other Unix-like systems;
2661        if you are using Windows, the name for the French locale is "french".
2662
2663        When pcre_maketables() runs, the tables are built  in  memory  that  is
2664        obtained  via  pcre_malloc. It is the caller's responsibility to ensure
2665        that the memory containing the tables remains available for as long  as
2666        it is needed.
2667
2668        The pointer that is passed to pcre_compile() is saved with the compiled
2669        pattern, and the same tables are used via this pointer by  pcre_study()
2670        and  also by pcre_exec() and pcre_dfa_exec(). Thus, for any single pat-
2671        tern, compilation, studying and matching all happen in the same locale,
2672        but different patterns can be processed in different locales.
2673
2674        It  is  possible to pass a table pointer or NULL (indicating the use of
2675        the internal tables) to pcre_exec() or pcre_dfa_exec() (see the discus-
2676        sion below in the section on matching a pattern). This facility is pro-
2677        vided for use with pre-compiled  patterns  that  have  been  saved  and
2678        reloaded.   Character  tables are not saved with patterns, so if a non-
2679        standard table was used at compile time, it must be provided again when
2680        the  reloaded  pattern  is  matched. Attempting to use this facility to
2681        match a pattern in a different locale from the one in which it was com-
2682        piled is likely to lead to anomalous (usually incorrect) results.
2683
2684
2685 INFORMATION ABOUT A PATTERN
2686
2687        int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
2688             int what, void *where);
2689
2690        The  pcre_fullinfo() function returns information about a compiled pat-
2691        tern. It replaces the pcre_info() function, which was removed from  the
2692        library at version 8.30, after more than 10 years of obsolescence.
2693
2694        The  first  argument  for  pcre_fullinfo() is a pointer to the compiled
2695        pattern. The second argument is the result of pcre_study(), or NULL  if
2696        the  pattern  was not studied. The third argument specifies which piece
2697        of information is required, and the fourth argument is a pointer  to  a
2698        variable  to  receive  the  data. The yield of the function is zero for
2699        success, or one of the following negative numbers:
2700
2701          PCRE_ERROR_NULL           the argument code was NULL
2702                                    the argument where was NULL
2703          PCRE_ERROR_BADMAGIC       the "magic number" was not found
2704          PCRE_ERROR_BADENDIANNESS  the pattern was compiled with different
2705                                    endianness
2706          PCRE_ERROR_BADOPTION      the value of what was invalid
2707          PCRE_ERROR_UNSET          the requested field is not set
2708
2709        The "magic number" is placed at the start of each compiled  pattern  as
2710        an  simple check against passing an arbitrary memory pointer. The endi-
2711        anness error can occur if a compiled pattern is saved and reloaded on a
2712        different  host.  Here  is a typical call of pcre_fullinfo(), to obtain
2713        the length of the compiled pattern:
2714
2715          int rc;
2716          size_t length;
2717          rc = pcre_fullinfo(
2718            re,               /* result of pcre_compile() */
2719            sd,               /* result of pcre_study(), or NULL */
2720            PCRE_INFO_SIZE,   /* what is required */
2721            &length);         /* where to put the data */
2722
2723        The possible values for the third argument are defined in  pcre.h,  and
2724        are as follows:
2725
2726          PCRE_INFO_BACKREFMAX
2727
2728        Return  the  number  of  the highest back reference in the pattern. The
2729        fourth argument should point to an int variable. Zero  is  returned  if
2730        there are no back references.
2731
2732          PCRE_INFO_CAPTURECOUNT
2733
2734        Return  the  number of capturing subpatterns in the pattern. The fourth
2735        argument should point to an int variable.
2736
2737          PCRE_INFO_DEFAULT_TABLES
2738
2739        Return a pointer to the internal default character tables within  PCRE.
2740        The  fourth  argument should point to an unsigned char * variable. This
2741        information call is provided for internal use by the pcre_study() func-
2742        tion.  External  callers  can  cause PCRE to use its internal tables by
2743        passing a NULL table pointer.
2744
2745          PCRE_INFO_FIRSTBYTE (deprecated)
2746
2747        Return information about the first data unit of any matched string, for
2748        a  non-anchored  pattern.  The  name of this option refers to the 8-bit
2749        library, where data units are bytes. The fourth argument  should  point
2750        to  an  int  variable. Negative values are used for special cases. How-
2751        ever, this means that when the 32-bit library is  in  non-UTF-32  mode,
2752        the  full  32-bit range of characters cannot be returned. For this rea-
2753        son, this value is deprecated;  use  PCRE_INFO_FIRSTCHARACTERFLAGS  and
2754        PCRE_INFO_FIRSTCHARACTER instead.
2755
2756        If  there  is  a  fixed first value, for example, the letter "c" from a
2757        pattern such as (cat|cow|coyote), its value is returned. In  the  8-bit
2758        library,  the  value is always less than 256. In the 16-bit library the
2759        value can be up to 0xffff. In the 32-bit library the value can be up to
2760        0x10ffff.
2761
2762        If there is no fixed first value, and if either
2763
2764        (a)  the pattern was compiled with the PCRE_MULTILINE option, and every
2765        branch starts with "^", or
2766
2767        (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not
2768        set (if it were set, the pattern would be anchored),
2769
2770        -1  is  returned, indicating that the pattern matches only at the start
2771        of a subject string or after any newline within the  string.  Otherwise
2772        -2 is returned. For anchored patterns, -2 is returned.
2773
2774          PCRE_INFO_FIRSTCHARACTER
2775
2776        Return  the  value  of  the  first data unit (non-UTF character) of any
2777        matched string in  the  situation  where  PCRE_INFO_FIRSTCHARACTERFLAGS
2778        returns  1;  otherwise return 0. The fourth argument should point to an
2779        uint_t variable.
2780
2781        In the 8-bit library, the value is always less than 256. In the  16-bit
2782        library  the value can be up to 0xffff. In the 32-bit library in UTF-32
2783        mode the value can be up to 0x10ffff, and up  to  0xffffffff  when  not
2784        using UTF-32 mode.
2785
2786          PCRE_INFO_FIRSTCHARACTERFLAGS
2787
2788        Return information about the first data unit of any matched string, for
2789        a non-anchored pattern. The fourth argument  should  point  to  an  int
2790        variable.
2791
2792        If  there  is  a  fixed first value, for example, the letter "c" from a
2793        pattern such as (cat|cow|coyote), 1  is  returned,  and  the  character
2794        value  can  be retrieved using PCRE_INFO_FIRSTCHARACTER. If there is no
2795        fixed first value, and if either
2796
2797        (a) the pattern was compiled with the PCRE_MULTILINE option, and  every
2798        branch starts with "^", or
2799
2800        (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not
2801        set (if it were set, the pattern would be anchored),
2802
2803        2 is returned, indicating that the pattern matches only at the start of
2804        a subject string or after any newline within the string. Otherwise 0 is
2805        returned. For anchored patterns, 0 is returned.
2806
2807          PCRE_INFO_FIRSTTABLE
2808
2809        If the pattern was studied, and this resulted in the construction of  a
2810        256-bit  table indicating a fixed set of values for the first data unit
2811        in any matching string, a pointer to the table is  returned.  Otherwise
2812        NULL  is returned. The fourth argument should point to an unsigned char
2813        * variable.
2814
2815          PCRE_INFO_HASCRORLF
2816
2817        Return 1 if the pattern contains any explicit  matches  for  CR  or  LF
2818        characters,  otherwise  0.  The  fourth argument should point to an int
2819        variable. An explicit match is either a literal CR or LF character,  or
2820        \r or \n.
2821
2822          PCRE_INFO_JCHANGED
2823
2824        Return  1  if  the (?J) or (?-J) option setting is used in the pattern,
2825        otherwise 0. The fourth argument should point to an int variable.  (?J)
2826        and (?-J) set and unset the local PCRE_DUPNAMES option, respectively.
2827
2828          PCRE_INFO_JIT
2829
2830        Return  1  if  the pattern was studied with one of the JIT options, and
2831        just-in-time compiling was successful. The fourth argument should point
2832        to  an  int variable. A return value of 0 means that JIT support is not
2833        available in this version of PCRE, or that the pattern was not  studied
2834        with  a JIT option, or that the JIT compiler could not handle this par-
2835        ticular pattern. See the pcrejit documentation for details of what  can
2836        and cannot be handled.
2837
2838          PCRE_INFO_JITSIZE
2839
2840        If  the  pattern was successfully studied with a JIT option, return the
2841        size of the JIT compiled code, otherwise return zero. The fourth  argu-
2842        ment should point to a size_t variable.
2843
2844          PCRE_INFO_LASTLITERAL
2845
2846        Return  the value of the rightmost literal data unit that must exist in
2847        any matched string, other than at its start, if such a value  has  been
2848        recorded. The fourth argument should point to an int variable. If there
2849        is no such value, -1 is returned. For anchored patterns, a last literal
2850        value  is recorded only if it follows something of variable length. For
2851        example, for the pattern /^a\d+z\d+/ the returned value is "z", but for
2852        /^a\dz\d/ the returned value is -1.
2853
2854        Since  for  the 32-bit library using the non-UTF-32 mode, this function
2855        is unable to return the full 32-bit range of characters, this value  is
2856        deprecated;     instead     the     PCRE_INFO_REQUIREDCHARFLAGS     and
2857        PCRE_INFO_REQUIREDCHAR values should be used.
2858
2859          PCRE_INFO_MATCH_EMPTY
2860
2861        Return 1 if the pattern can match an empty  string,  otherwise  0.  The
2862        fourth argument should point to an int variable.
2863
2864          PCRE_INFO_MATCHLIMIT
2865
2866        If  the  pattern  set  a  match  limit by including an item of the form
2867        (*LIMIT_MATCH=nnnn) at the start, the value  is  returned.  The  fourth
2868        argument  should  point to an unsigned 32-bit integer. If no such value
2869        has  been  set,  the  call  to  pcre_fullinfo()   returns   the   error
2870        PCRE_ERROR_UNSET.
2871
2872          PCRE_INFO_MAXLOOKBEHIND
2873
2874        Return  the  number  of  characters  (NB not data units) in the longest
2875        lookbehind assertion in the pattern. This information  is  useful  when
2876        doing  multi-segment  matching  using  the partial matching facilities.
2877        Note that the simple assertions \b and \B require a one-character look-
2878        behind.  \A  also  registers a one-character lookbehind, though it does
2879        not actually inspect the previous character. This is to ensure that  at
2880        least one character from the old segment is retained when a new segment
2881        is processed. Otherwise, if there are no lookbehinds in the pattern, \A
2882        might match incorrectly at the start of a new segment.
2883
2884          PCRE_INFO_MINLENGTH
2885
2886        If  the  pattern  was studied and a minimum length for matching subject
2887        strings was computed, its value is  returned.  Otherwise  the  returned
2888        value is -1. The value is a number of characters, which in UTF mode may
2889        be different from the number of data units. The fourth argument  should
2890        point  to an int variable. A non-negative value is a lower bound to the
2891        length of any matching string. There may not be  any  strings  of  that
2892        length  that  do actually match, but every string that does match is at
2893        least that long.
2894
2895          PCRE_INFO_NAMECOUNT
2896          PCRE_INFO_NAMEENTRYSIZE
2897          PCRE_INFO_NAMETABLE
2898
2899        PCRE supports the use of named as well as numbered capturing  parenthe-
2900        ses.  The names are just an additional way of identifying the parenthe-
2901        ses, which still acquire numbers. Several convenience functions such as
2902        pcre_get_named_substring()  are  provided  for extracting captured sub-
2903        strings by name. It is also possible to extract the data  directly,  by
2904        first  converting  the  name to a number in order to access the correct
2905        pointers in the output vector (described with pcre_exec() below). To do
2906        the  conversion,  you  need  to  use  the  name-to-number map, which is
2907        described by these three values.
2908
2909        The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT
2910        gives the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size
2911        of each entry; both of these  return  an  int  value.  The  entry  size
2912        depends  on the length of the longest name. PCRE_INFO_NAMETABLE returns
2913        a pointer to the first entry of the table. This is a pointer to char in
2914        the 8-bit library, where the first two bytes of each entry are the num-
2915        ber of the capturing parenthesis, most significant byte first.  In  the
2916        16-bit  library,  the pointer points to 16-bit data units, the first of
2917        which contains the parenthesis  number.  In  the  32-bit  library,  the
2918        pointer  points  to  32-bit data units, the first of which contains the
2919        parenthesis number. The rest of the entry is  the  corresponding  name,
2920        zero terminated.
2921
2922        The  names are in alphabetical order. If (?| is used to create multiple
2923        groups with the same number, as described in the section  on  duplicate
2924        subpattern numbers in the pcrepattern page, the groups may be given the
2925        same name, but there is only one entry in the  table.  Different  names
2926        for  groups  of the same number are not permitted.  Duplicate names for
2927        subpatterns with different numbers are permitted, but only if PCRE_DUP-
2928        NAMES  is set. They appear in the table in the order in which they were
2929        found in the pattern. In the absence  of  (?|  this  is  the  order  of
2930        increasing  number;  when  (?| is used this is not necessarily the case
2931        because later subpatterns may have lower numbers.
2932
2933        As a simple example of the name/number table,  consider  the  following
2934        pattern after compilation by the 8-bit library (assume PCRE_EXTENDED is
2935        set, so white space - including newlines - is ignored):
2936
2937          (?<date> (?<year>(\d\d)?\d\d) -
2938          (?<month>\d\d) - (?<day>\d\d) )
2939
2940        There are four named subpatterns, so the table has  four  entries,  and
2941        each  entry  in the table is eight bytes long. The table is as follows,
2942        with non-printing bytes shows in hexadecimal, and undefined bytes shown
2943        as ??:
2944
2945          00 01 d  a  t  e  00 ??
2946          00 05 d  a  y  00 ?? ??
2947          00 04 m  o  n  t  h  00
2948          00 02 y  e  a  r  00 ??
2949
2950        When  writing  code  to  extract  data from named subpatterns using the
2951        name-to-number map, remember that the length of the entries  is  likely
2952        to be different for each compiled pattern.
2953
2954          PCRE_INFO_OKPARTIAL
2955
2956        Return  1  if  the  pattern  can  be  used  for  partial  matching with
2957        pcre_exec(), otherwise 0. The fourth argument should point  to  an  int
2958        variable.  From  release  8.00,  this  always  returns  1,  because the
2959        restrictions that previously applied  to  partial  matching  have  been
2960        lifted.  The  pcrepartial documentation gives details of partial match-
2961        ing.
2962
2963          PCRE_INFO_OPTIONS
2964
2965        Return a copy of the options with which the pattern was  compiled.  The
2966        fourth  argument  should  point to an unsigned long int variable. These
2967        option bits are those specified in the call to pcre_compile(), modified
2968        by any top-level option settings at the start of the pattern itself. In
2969        other words, they are the options that will be in force  when  matching
2970        starts.  For  example, if the pattern /(?im)abc(?-i)d/ is compiled with
2971        the PCRE_EXTENDED option, the result is PCRE_CASELESS,  PCRE_MULTILINE,
2972        and PCRE_EXTENDED.
2973
2974        A  pattern  is  automatically  anchored by PCRE if all of its top-level
2975        alternatives begin with one of the following:
2976
2977          ^     unless PCRE_MULTILINE is set
2978          \A    always
2979          \G    always
2980          .*    if PCRE_DOTALL is set and there are no back
2981                  references to the subpattern in which .* appears
2982
2983        For such patterns, the PCRE_ANCHORED bit is set in the options returned
2984        by pcre_fullinfo().
2985
2986          PCRE_INFO_RECURSIONLIMIT
2987
2988        If  the  pattern set a recursion limit by including an item of the form
2989        (*LIMIT_RECURSION=nnnn) at the start, the value is returned. The fourth
2990        argument  should  point to an unsigned 32-bit integer. If no such value
2991        has  been  set,  the  call  to  pcre_fullinfo()   returns   the   error
2992        PCRE_ERROR_UNSET.
2993
2994          PCRE_INFO_SIZE
2995
2996        Return  the  size  of  the  compiled  pattern  in  bytes (for all three
2997        libraries). The fourth argument should point to a size_t variable. This
2998        value  does not include the size of the pcre structure that is returned
2999        by pcre_compile().  The  value  that  is  passed  as  the  argument  to
3000        pcre_malloc()  when  pcre_compile() is getting memory in which to place
3001        the compiled data is the value returned by this option plus the size of
3002        the  pcre  structure. Studying a compiled pattern, with or without JIT,
3003        does not alter the value returned by this option.
3004
3005          PCRE_INFO_STUDYSIZE
3006
3007        Return the size in bytes (for all three libraries) of  the  data  block
3008        pointed to by the study_data field in a pcre_extra block. If pcre_extra
3009        is NULL, or there is no study data, zero is returned. The fourth  argu-
3010        ment  should point to a size_t variable. The study_data field is set by
3011        pcre_study() to record information that will speed up matching (see the
3012        section  entitled  "Studying  a  pattern"  above).  The  format  of the
3013        study_data block is private, but its length is made available via  this
3014        option  so  that  it  can be saved and restored (see the pcreprecompile
3015        documentation for details).
3016
3017          PCRE_INFO_REQUIREDCHARFLAGS
3018
3019        Returns 1 if there is a rightmost literal data unit that must exist  in
3020        any matched string, other than at its start. The fourth argument should
3021        point to an int variable. If there is no such value, 0 is returned.  If
3022        returning  1,  the  character  value  itself  can  be  retrieved  using
3023        PCRE_INFO_REQUIREDCHAR.
3024
3025        For anchored patterns, a last literal value is recorded only if it fol-
3026        lows  something  of  variable  length.  For  example,  for  the pattern
3027        /^a\d+z\d+/  the   returned   value   1   (with   "z"   returned   from
3028        PCRE_INFO_REQUIREDCHAR), but for /^a\dz\d/ the returned value is 0.
3029
3030          PCRE_INFO_REQUIREDCHAR
3031
3032        Return  the value of the rightmost literal data unit that must exist in
3033        any matched string, other than at its start, if such a value  has  been
3034        recorded.  The fourth argument should point to an uint32_t variable. If
3035        there is no such value, 0 is returned.
3036
3037
3038 REFERENCE COUNTS
3039
3040        int pcre_refcount(pcre *code, int adjust);
3041
3042        The pcre_refcount() function is used to maintain a reference  count  in
3043        the data block that contains a compiled pattern. It is provided for the
3044        benefit of applications that  operate  in  an  object-oriented  manner,
3045        where different parts of the application may be using the same compiled
3046        pattern, but you want to free the block when they are all done.
3047
3048        When a pattern is compiled, the reference count field is initialized to
3049        zero.   It is changed only by calling this function, whose action is to
3050        add the adjust value (which may be positive or  negative)  to  it.  The
3051        yield of the function is the new value. However, the value of the count
3052        is constrained to lie between 0 and 65535, inclusive. If the new  value
3053        is outside these limits, it is forced to the appropriate limit value.
3054
3055        Except  when it is zero, the reference count is not correctly preserved
3056        if a pattern is compiled on one host and then  transferred  to  a  host
3057        whose byte-order is different. (This seems a highly unlikely scenario.)
3058
3059
3060 MATCHING A PATTERN: THE TRADITIONAL FUNCTION
3061
3062        int pcre_exec(const pcre *code, const pcre_extra *extra,
3063             const char *subject, int length, int startoffset,
3064             int options, int *ovector, int ovecsize);
3065
3066        The  function pcre_exec() is called to match a subject string against a
3067        compiled pattern, which is passed in the code argument. If the  pattern
3068        was  studied,  the  result  of  the study should be passed in the extra
3069        argument. You can call pcre_exec() with the same code and  extra  argu-
3070        ments  as  many  times as you like, in order to match different subject
3071        strings with the same pattern.
3072
3073        This function is the main matching facility  of  the  library,  and  it
3074        operates  in  a  Perl-like  manner. For specialist use there is also an
3075        alternative matching function, which is described below in the  section
3076        about the pcre_dfa_exec() function.
3077
3078        In  most applications, the pattern will have been compiled (and option-
3079        ally studied) in the same process that calls pcre_exec().  However,  it
3080        is possible to save compiled patterns and study data, and then use them
3081        later in different processes, possibly even on different hosts.  For  a
3082        discussion about this, see the pcreprecompile documentation.
3083
3084        Here is an example of a simple call to pcre_exec():
3085
3086          int rc;
3087          int ovector[30];
3088          rc = pcre_exec(
3089            re,             /* result of pcre_compile() */
3090            NULL,           /* we didn't study the pattern */
3091            "some string",  /* the subject string */
3092            11,             /* the length of the subject string */
3093            0,              /* start at offset 0 in the subject */
3094            0,              /* default options */
3095            ovector,        /* vector of integers for substring information */
3096            30);            /* number of elements (NOT size in bytes) */
3097
3098    Extra data for pcre_exec()
3099
3100        If  the  extra argument is not NULL, it must point to a pcre_extra data
3101        block. The pcre_study() function returns such a block (when it  doesn't
3102        return  NULL), but you can also create one for yourself, and pass addi-
3103        tional information in it. The pcre_extra block contains  the  following
3104        fields (not necessarily in this order):
3105
3106          unsigned long int flags;
3107          void *study_data;
3108          void *executable_jit;
3109          unsigned long int match_limit;
3110          unsigned long int match_limit_recursion;
3111          void *callout_data;
3112          const unsigned char *tables;
3113          unsigned char **mark;
3114
3115        In  the  16-bit  version  of  this  structure,  the mark field has type
3116        "PCRE_UCHAR16 **".
3117
3118        In the 32-bit version of  this  structure,  the  mark  field  has  type
3119        "PCRE_UCHAR32 **".
3120
3121        The  flags  field is used to specify which of the other fields are set.
3122        The flag bits are:
3123
3124          PCRE_EXTRA_CALLOUT_DATA
3125          PCRE_EXTRA_EXECUTABLE_JIT
3126          PCRE_EXTRA_MARK
3127          PCRE_EXTRA_MATCH_LIMIT
3128          PCRE_EXTRA_MATCH_LIMIT_RECURSION
3129          PCRE_EXTRA_STUDY_DATA
3130          PCRE_EXTRA_TABLES
3131
3132        Other flag bits should be set to zero. The study_data field  and  some-
3133        times  the executable_jit field are set in the pcre_extra block that is
3134        returned by pcre_study(), together with the appropriate flag bits.  You
3135        should  not set these yourself, but you may add to the block by setting
3136        other fields and their corresponding flag bits.
3137
3138        The match_limit field provides a means of preventing PCRE from using up
3139        a  vast amount of resources when running patterns that are not going to
3140        match, but which have a very large number  of  possibilities  in  their
3141        search  trees. The classic example is a pattern that uses nested unlim-
3142        ited repeats.
3143
3144        Internally, pcre_exec() uses a function called match(), which it  calls
3145        repeatedly  (sometimes  recursively).  The  limit set by match_limit is
3146        imposed on the number of times this function is called during a  match,
3147        which  has  the  effect of limiting the amount of backtracking that can
3148        take place. For patterns that are not anchored, the count restarts from
3149        zero for each position in the subject string.
3150
3151        When pcre_exec() is called with a pattern that was successfully studied
3152        with a JIT option, the way that the matching is  executed  is  entirely
3153        different.  However, there is still the possibility of runaway matching
3154        that goes on for a very long time, and so the match_limit value is also
3155        used in this case (but in a different way) to limit how long the match-
3156        ing can continue.
3157
3158        The default value for the limit can be set  when  PCRE  is  built;  the
3159        default  default  is 10 million, which handles all but the most extreme
3160        cases. You can override the default  by  suppling  pcre_exec()  with  a
3161        pcre_extra     block    in    which    match_limit    is    set,    and
3162        PCRE_EXTRA_MATCH_LIMIT is set in the  flags  field.  If  the  limit  is
3163        exceeded, pcre_exec() returns PCRE_ERROR_MATCHLIMIT.
3164
3165        A  value  for  the  match  limit may also be supplied by an item at the
3166        start of a pattern of the form
3167
3168          (*LIMIT_MATCH=d)
3169
3170        where d is a decimal number. However, such a setting is ignored  unless
3171        d  is  less  than  the limit set by the caller of pcre_exec() or, if no
3172        such limit is set, less than the default.
3173
3174        The match_limit_recursion field is similar to match_limit, but  instead
3175        of limiting the total number of times that match() is called, it limits
3176        the depth of recursion. The recursion depth is a  smaller  number  than
3177        the  total number of calls, because not all calls to match() are recur-
3178        sive.  This limit is of use only if it is set smaller than match_limit.
3179
3180        Limiting the recursion depth limits the amount of  machine  stack  that
3181        can  be used, or, when PCRE has been compiled to use memory on the heap
3182        instead of the stack, the amount of heap memory that can be used.  This
3183        limit  is not relevant, and is ignored, when matching is done using JIT
3184        compiled code.
3185
3186        The default value for match_limit_recursion can be  set  when  PCRE  is
3187        built;  the  default  default  is  the  same  value  as the default for
3188        match_limit. You can override the default by suppling pcre_exec()  with
3189        a   pcre_extra   block  in  which  match_limit_recursion  is  set,  and
3190        PCRE_EXTRA_MATCH_LIMIT_RECURSION is set in  the  flags  field.  If  the
3191        limit is exceeded, pcre_exec() returns PCRE_ERROR_RECURSIONLIMIT.
3192
3193        A  value for the recursion limit may also be supplied by an item at the
3194        start of a pattern of the form
3195
3196          (*LIMIT_RECURSION=d)
3197
3198        where d is a decimal number. However, such a setting is ignored  unless
3199        d  is  less  than  the limit set by the caller of pcre_exec() or, if no
3200        such limit is set, less than the default.
3201
3202        The callout_data field is used in conjunction with the  "callout"  fea-
3203        ture, and is described in the pcrecallout documentation.
3204
3205        The  tables field is provided for use with patterns that have been pre-
3206        compiled using custom character tables, saved to disc or elsewhere, and
3207        then  reloaded,  because the tables that were used to compile a pattern
3208        are not saved with it. See the pcreprecompile documentation for a  dis-
3209        cussion  of  saving  compiled patterns for later use. If NULL is passed
3210        using this mechanism, it forces PCRE's internal tables to be used.
3211
3212        Warning: The tables that pcre_exec() uses must be  the  same  as  those
3213        that  were used when the pattern was compiled. If this is not the case,
3214        the behaviour of pcre_exec() is undefined. Therefore, when a pattern is
3215        compiled  and  matched  in the same process, this field should never be
3216        set. In this (the most common) case, the correct table pointer is auto-
3217        matically  passed  with  the  compiled  pattern  from pcre_compile() to
3218        pcre_exec().
3219
3220        If PCRE_EXTRA_MARK is set in the flags field, the mark  field  must  be
3221        set  to point to a suitable variable. If the pattern contains any back-
3222        tracking control verbs such as (*MARK:NAME), and the execution ends  up
3223        with  a  name  to  pass back, a pointer to the name string (zero termi-
3224        nated) is placed in the variable pointed to  by  the  mark  field.  The
3225        names  are  within  the  compiled pattern; if you wish to retain such a
3226        name you must copy it before freeing the memory of a compiled  pattern.
3227        If  there  is no name to pass back, the variable pointed to by the mark
3228        field is set to NULL. For details of the  backtracking  control  verbs,
3229        see the section entitled "Backtracking control" in the pcrepattern doc-
3230        umentation.
3231
3232    Option bits for pcre_exec()
3233
3234        The unused bits of the options argument for pcre_exec() must  be  zero.
3235        The  only  bits  that  may  be set are PCRE_ANCHORED, PCRE_NEWLINE_xxx,
3236        PCRE_NOTBOL,   PCRE_NOTEOL,    PCRE_NOTEMPTY,    PCRE_NOTEMPTY_ATSTART,
3237        PCRE_NO_START_OPTIMIZE,   PCRE_NO_UTF8_CHECK,   PCRE_PARTIAL_HARD,  and
3238        PCRE_PARTIAL_SOFT.
3239
3240        If the pattern was successfully studied with one  of  the  just-in-time
3241        (JIT) compile options, the only supported options for JIT execution are
3242        PCRE_NO_UTF8_CHECK,    PCRE_NOTBOL,     PCRE_NOTEOL,     PCRE_NOTEMPTY,
3243        PCRE_NOTEMPTY_ATSTART,  PCRE_PARTIAL_HARD, and PCRE_PARTIAL_SOFT. If an
3244        unsupported option is used, JIT execution is disabled  and  the  normal
3245        interpretive code in pcre_exec() is run.
3246
3247          PCRE_ANCHORED
3248
3249        The  PCRE_ANCHORED  option  limits pcre_exec() to matching at the first
3250        matching position. If a pattern was  compiled  with  PCRE_ANCHORED,  or
3251        turned  out to be anchored by virtue of its contents, it cannot be made
3252        unachored at matching time.
3253
3254          PCRE_BSR_ANYCRLF
3255          PCRE_BSR_UNICODE
3256
3257        These options (which are mutually exclusive) control what the \R escape
3258        sequence  matches.  The choice is either to match only CR, LF, or CRLF,
3259        or to match any Unicode newline sequence. These  options  override  the
3260        choice that was made or defaulted when the pattern was compiled.
3261
3262          PCRE_NEWLINE_CR
3263          PCRE_NEWLINE_LF
3264          PCRE_NEWLINE_CRLF
3265          PCRE_NEWLINE_ANYCRLF
3266          PCRE_NEWLINE_ANY
3267
3268        These  options  override  the  newline  definition  that  was chosen or
3269        defaulted when the pattern was compiled. For details, see the  descrip-
3270        tion  of  pcre_compile()  above.  During  matching,  the newline choice
3271        affects the behaviour of the dot, circumflex,  and  dollar  metacharac-
3272        ters.  It may also alter the way the match position is advanced after a
3273        match failure for an unanchored pattern.
3274
3275        When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF,  or  PCRE_NEWLINE_ANY  is
3276        set,  and a match attempt for an unanchored pattern fails when the cur-
3277        rent position is at a  CRLF  sequence,  and  the  pattern  contains  no