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

NAME

6       PCRE - Perl-compatible regular expressions (original API)
7

PLEASE TAKE NOTE

9
10       This  document relates to PCRE releases that use the original API, with
11       library names libpcre, libpcre16, and libpcre32. January 2015  saw  the
12       first release of a new API, known as PCRE2, with release numbers start‐
13       ing  at  10.00  and  library   names   libpcre2-8,   libpcre2-16,   and
14       libpcre2-32.  The  old  libraries  (now called PCRE1) are now at end of
15       life, and 8.45 is the final release. New projects are  advised  to  use
16       the new PCRE2 libraries.
17

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  (in‐
30       cluding UTF-8 strings), and a second library that supports 16-bit char‐
31       acter strings (including UTF-16 strings). The build process allows  ei‐
32       ther  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

SECURITY CONSIDERATIONS

96
97       If you are using PCRE in a non-UTF application that  permits  users  to
98       supply  arbitrary  patterns  for  compilation, you should be aware of a
99       feature that allows users to turn on UTF support from within a pattern,
100       provided  that  PCRE  was built with UTF support. For example, an 8-bit
101       pattern that begins with "(*UTF8)" or "(*UTF)"  turns  on  UTF-8  mode,
102       which  interprets  patterns and subjects as strings of UTF-8 characters
103       instead of individual 8-bit characters.  This causes both  the  pattern
104       and any data against which it is matched to be checked for UTF-8 valid‐
105       ity. If the data string is very long, such a  check  might  use  suffi‐
106       ciently  many  resources  as  to cause your application to lose perfor‐
107       mance.
108
109       One  way  of  guarding  against  this  possibility  is   to   use   the
110       pcre_fullinfo()  function  to  check the compiled pattern's options for
111       UTF.  Alternatively, from release 8.33, you can set the  PCRE_NEVER_UTF
112       option  at  compile time. This causes a compile time error if a pattern
113       contains a UTF-setting sequence.
114
115       If your application is one that supports UTF, be  aware  that  validity
116       checking  can  take time. If the same data string is to be matched many
117       times, you can use the PCRE_NO_UTF[8|16|32]_CHECK option for the second
118       and subsequent matches to save redundant checks.
119
120       Another  way  that  performance can be hit is by running a pattern that
121       has a very large search tree against a string that  will  never  match.
122       Nested  unlimited  repeats in a pattern are a common example. PCRE pro‐
123       vides some protection against this: see the PCRE_EXTRA_MATCH_LIMIT fea‐
124       ture in the pcreapi page.
125

USER DOCUMENTATION

127
128       The  user  documentation  for PCRE comprises a number of different sec‐
129       tions. In the "man" format, each of these is a separate "man page".  In
130       the  HTML  format, each is a separate page, linked from the index page.
131       In the plain text format, the descriptions of the pcregrep and pcretest
132       programs  are  in  files  called pcregrep.txt and pcretest.txt, respec‐
133       tively. The remaining sections, except for the pcredemo section  (which
134       is  a  program  listing),  are  concatenated  in  pcre.txt, for ease of
135       searching. The sections are as follows:
136
137         pcre              this document
138         pcre-config       show PCRE installation configuration information
139         pcre16            details of the 16-bit library
140         pcre32            details of the 32-bit library
141         pcreapi           details of PCRE's native C API
142         pcrebuild         building PCRE
143         pcrecallout       details of the callout feature
144         pcrecompat        discussion of Perl compatibility
145         pcrecpp           details of the C++ wrapper for the 8-bit library
146         pcredemo          a demonstration C program that uses PCRE
147         pcregrep          description of the pcregrep command (8-bit only)
148         pcrejit           discussion of the just-in-time optimization support
149         pcrelimits        details of size and other limits
150         pcrematching      discussion of the two matching algorithms
151         pcrepartial       details of the partial matching facility
152         pcrepattern       syntax and semantics of supported
153                             regular expressions
154         pcreperform       discussion of performance issues
155         pcreposix         the POSIX-compatible C API for the 8-bit library
156         pcreprecompile    details of saving and re-using precompiled patterns
157         pcresample        discussion of the pcredemo program
158         pcrestack         discussion of stack usage
159         pcresyntax        quick syntax reference
160         pcretest          description of the pcretest testing command
161         pcreunicode       discussion of Unicode and UTF-8/16/32 support
162
163       In the "man" and HTML formats, there is also a short page  for  each  C
164       library function, listing its arguments and results.
165

AUTHOR

167
168       Philip Hazel
169       University Computing Service
170       Cambridge CB2 3QH, England.
171
172       Putting  an actual email address here seems to have been a spam magnet,
173       so I've taken it away. If you want to email me, use  my  two  initials,
174       followed by the two digits 10, at the domain cam.ac.uk.
175

REVISION

177
178       Last updated: 14 June 2021
179       Copyright (c) 1997-2021 University of Cambridge.
180
181
182
183PCRE 8.45                        14 June 2021                          PCRE(3)
Impressum