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

SECURITY CONSIDERATIONS

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

USER DOCUMENTATION

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

AUTHOR

144
145       Philip Hazel
146       University Computing Service
147       Cambridge, England.
148
149       Putting an actual email address here is a spam magnet. If you  want  to
150       email  me,  use  my two initials, followed by the two digits 10, at the
151       domain cam.ac.uk.
152

REVISION

154
155       Last updated: 16 October 2015
156       Copyright (c) 1997-2015 University of Cambridge.
157
158
159
160PCRE2 10.21                     16 October 2015                       PCRE2(3)
Impressum