1PCRE2(3)                   Library Functions Manual                   PCRE2(3)
2
3
4

NAME

6       PCRE2 - Perl-compatible regular expressions (revised API)
7

INTRODUCTION

9
10       PCRE2 is the name used for a revised API for the PCRE library, which is
11       a set of functions, written in C,  that  implement  regular  expression
12       pattern matching using the same syntax and semantics as Perl, with just
13       a few differences. After nearly two decades,  the  limitations  of  the
14       original  API  were  making development increasingly difficult. The new
15       API is more extensible, and it was simplified by abolishing  the  sepa‐
16       rate  "study" optimizing function; in PCRE2, patterns are automatically
17       optimized where possible. Since forking from PCRE1, the code  has  been
18       extensively refactored and new features introduced.
19
20       As  well  as Perl-style regular expression patterns, some features that
21       appeared in Python and the original PCRE before they appeared  in  Perl
22       are  available  using the Python syntax. There is also some support for
23       one or two .NET and Oniguruma syntax items, and there are  options  for
24       requesting   some  minor  changes  that  give  better  ECMAScript  (aka
25       JavaScript) compatibility.
26
27       The source code for PCRE2 can be compiled to support 8-bit, 16-bit,  or
28       32-bit  code units, which means that up to three separate libraries may
29       be installed.  The original work to extend PCRE to  16-bit  and  32-bit
30       code  units  was  done  by Zoltan Herczeg and Christian Persch, respec‐
31       tively. In all three cases, strings can be interpreted  either  as  one
32       character  per  code  unit, or as UTF-encoded Unicode, with support for
33       Unicode general category properties. Unicode  support  is  optional  at
34       build  time  (but  is  the default). However, processing strings as UTF
35       code units must be enabled explicitly at run time. The version of  Uni‐
36       code in use can be discovered by running
37
38         pcre2test -C
39
40       The  three  libraries  contain  identical sets of functions, with names
41       ending in _8,  _16,  or  _32,  respectively  (for  example,  pcre2_com‐
42       pile_8()).  However,  by defining PCRE2_CODE_UNIT_WIDTH to be 8, 16, or
43       32, a program that uses just one code unit width can be  written  using
44       generic names such as pcre2_compile(), and the documentation is written
45       assuming that this is the case.
46
47       In addition to the Perl-compatible matching function, PCRE2 contains an
48       alternative  function that matches the same compiled patterns in a dif‐
49       ferent way. In certain circumstances, the alternative function has some
50       advantages.   For  a discussion of the two matching algorithms, see the
51       pcre2matching page.
52
53       Details of exactly which Perl regular expression features are  and  are
54       not  supported  by  PCRE2  are  given  in  separate  documents. See the
55       pcre2pattern and pcre2compat pages. There is a syntax  summary  in  the
56       pcre2syntax page.
57
58       Some  features  of PCRE2 can be included, excluded, or changed when the
59       library is built. The pcre2_config() function makes it possible  for  a
60       client  to  discover  which  features are available. The features them‐
61       selves are described in the pcre2build page. Documentation about build‐
62       ing  PCRE2 for various operating systems can be found in the README and
63       NON-AUTOTOOLS_BUILD files in the source distribution.
64
65       The libraries contains a number of undocumented internal functions  and
66       data  tables  that  are  used by more than one of the exported external
67       functions, but which are not intended  for  use  by  external  callers.
68       Their  names  all begin with "_pcre2", which hopefully will not provoke
69       any name clashes. In some environments, it is possible to control which
70       external  symbols  are  exported when a shared library is built, and in
71       these cases the undocumented symbols are not exported.
72

SECURITY CONSIDERATIONS

74
75       If you are using PCRE2 in a non-UTF application that permits  users  to
76       supply  arbitrary  patterns  for  compilation, you should be aware of a
77       feature that allows users to turn on UTF support from within a pattern.
78       For  example, an 8-bit pattern that begins with "(*UTF)" turns on UTF-8
79       mode, which interprets patterns and subjects as strings of  UTF-8  code
80       units instead of individual 8-bit characters. This causes both the pat‐
81       tern and any data against which it is matched to be checked  for  UTF-8
82       validity.  If the data string is very long, such a check might use suf‐
83       ficiently many resources as to cause your application to  lose  perfor‐
84       mance.
85
86       One  way  of guarding against this possibility is to use the pcre2_pat‐
87       tern_info() function  to  check  the  compiled  pattern's  options  for
88       PCRE2_UTF.  Alternatively,  you can set the PCRE2_NEVER_UTF option when
89       calling pcre2_compile(). This causes a compile time error if  the  pat‐
90       tern contains a UTF-setting sequence.
91
92       The  use  of Unicode properties for character types such as \d can also
93       be enabled from within the pattern, by specifying "(*UCP)".  This  fea‐
94       ture can be disallowed by setting the PCRE2_NEVER_UCP option.
95
96       If  your  application  is one that supports UTF, be aware that validity
97       checking can take time. If the same data string is to be  matched  many
98       times,  you  can  use  the PCRE2_NO_UTF_CHECK option for the second and
99       subsequent matches to avoid running redundant checks.
100
101       The use of the \C escape sequence in a UTF-8 or UTF-16 pattern can lead
102       to  problems,  because  it  may leave the current matching point in the
103       middle of  a  multi-code-unit  character.  The  PCRE2_NEVER_BACKSLASH_C
104       option can be used by an application to lock out the use of \C, causing
105       a compile-time error if it is encountered. It is also possible to build
106       PCRE2 with the use of \C permanently disabled.
107
108       Another  way  that  performance can be hit is by running a pattern that
109       has a very large search tree against a string that  will  never  match.
110       Nested  unlimited repeats in a pattern are a common example. PCRE2 pro‐
111       vides some protection against  this:  see  the  pcre2_set_match_limit()
112       function  in  the  pcre2api  page.  There  is a similar function called
113       pcre2_set_depth_limit() that can be used to restrict the amount of mem‐
114       ory that is used.
115

USER DOCUMENTATION

117
118       The  user  documentation for PCRE2 comprises a number of different sec‐
119       tions. In the "man" format, each of these is a separate "man page".  In
120       the  HTML  format, each is a separate page, linked from the index page.
121       In the plain  text  format,  the  descriptions  of  the  pcre2grep  and
122       pcre2test programs are in files called pcre2grep.txt and pcre2test.txt,
123       respectively. The remaining sections, except for the pcre2demo  section
124       (which  is a program listing), and the short pages for individual func‐
125       tions, are concatenated in pcre2.txt, for ease of searching.  The  sec‐
126       tions are as follows:
127
128         pcre2              this document
129         pcre2-config       show PCRE2 installation configuration information
130         pcre2api           details of PCRE2's native C API
131         pcre2build         building PCRE2
132         pcre2callout       details of the pattern callout feature
133         pcre2compat        discussion of Perl compatibility
134         pcre2convert       details of pattern conversion functions
135         pcre2demo          a demonstration C program that uses PCRE2
136         pcre2grep          description of the pcre2grep command (8-bit only)
137         pcre2jit           discussion of just-in-time optimization support
138         pcre2limits        details of size and other limits
139         pcre2matching      discussion of the two matching algorithms
140         pcre2partial       details of the partial matching facility
141         pcre2pattern       syntax and semantics of supported regular
142                              expression patterns
143         pcre2perform       discussion of performance issues
144         pcre2posix         the POSIX-compatible C API for the 8-bit library
145         pcre2sample        discussion of the pcre2demo program
146         pcre2serialize     details of pattern serialization
147         pcre2syntax        quick syntax reference
148         pcre2test          description of the pcre2test command
149         pcre2unicode       discussion of Unicode and UTF support
150
151       In  the  "man"  and HTML formats, there is also a short page for each C
152       library function, listing its arguments and results.
153

AUTHOR

155
156       Philip Hazel
157       University Computing Service
158       Cambridge, England.
159
160       Putting an actual email address here is a spam magnet. If you  want  to
161       email  me,  use  my two initials, followed by the two digits 10, at the
162       domain cam.ac.uk.
163

REVISION

165
166       Last updated: 17 September 2018
167       Copyright (c) 1997-2018 University of Cambridge.
168
169
170
171PCRE2 10.33                    17 September 2018                      PCRE2(3)
Impressum