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