|
|
<html><head><title>pcre2 specification</title></head><body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"><h1>pcre2 man page</h1><p>Return to the <a href="index.html">PCRE2 index page</a>.</p><p>This page is part of the PCRE2 HTML documentation. It was generatedautomatically from the original man page. If there is any nonsense in it,please consult the man page, in case the conversion went wrong.<br><ul><li><a name="TOC1" href="#SEC1">INTRODUCTION</a><li><a name="TOC2" href="#SEC2">SECURITY CONSIDERATIONS</a><li><a name="TOC3" href="#SEC3">USER DOCUMENTATION</a><li><a name="TOC4" href="#SEC4">AUTHOR</a><li><a name="TOC5" href="#SEC5">REVISION</a></ul><br><a name="SEC1" href="#TOC1">INTRODUCTION</a><br><P>PCRE2 is the name used for a revised API for the PCRE library, which is a setof functions, written in C, that implement regular expression pattern matchingusing the same syntax and semantics as Perl, with just a few differences. Afternearly two decades, the limitations of the original API were making developmentincreasingly difficult. The new API is more extensible, and it was simplifiedby abolishing the separate "study" optimizing function; in PCRE2, patterns areautomatically optimized where possible. Since forking from PCRE1, the code hasbeen extensively refactored and new features introduced. The old library is nowobsolete and is no longer maintained.</P><P>As well as Perl-style regular expression patterns, some features that appearedin Python and the original PCRE before they appeared in Perl are availableusing the Python syntax. There is also some support for one or two .NET andOniguruma syntax items, and there are options for requesting some minor changesthat give better ECMAScript (aka JavaScript) compatibility.</P><P>The source code for PCRE2 can be compiled to support strings of 8-bit, 16-bit,or 32-bit code units, which means that up to three separate libraries may beinstalled, one for each code unit size. The size of code unit is not related tothe bit size of the underlying hardware. In a 64-bit environment that alsosupports 32-bit applications, versions of PCRE2 that are compiled in both64-bit and 32-bit modes may be needed.</P><P>The original work to extend PCRE to 16-bit and 32-bit code units was done byZoltan Herczeg and Christian Persch, respectively. In all three cases, stringscan be interpreted either as one character per code unit, or as UTF-encodedUnicode, with support for Unicode general category properties. Unicode supportis optional at build time (but is the default). However, processing strings asUTF code units must be enabled explicitly at run time. The version of Unicodein use can be discovered by running<pre> pcre2test -C</PRE></P><P>The three libraries contain identical sets of functions, with names ending in_8, _16, or _32, respectively (for example, <b>pcre2_compile_8()</b>). However,by defining PCRE2_CODE_UNIT_WIDTH to be 8, 16, or 32, a program that uses justone code unit width can be written using generic names such as<b>pcre2_compile()</b>, and the documentation is written assuming that this isthe case.</P><P>In addition to the Perl-compatible matching function, PCRE2 contains analternative function that matches the same compiled patterns in a differentway. In certain circumstances, the alternative function has some advantages.For a discussion of the two matching algorithms, see the<a href="pcre2matching.html"><b>pcre2matching</b></a>page.</P><P>Details of exactly which Perl regular expression features are and are notsupported by PCRE2 are given in separate documents. See the<a href="pcre2pattern.html"><b>pcre2pattern</b></a>and<a href="pcre2compat.html"><b>pcre2compat</b></a>pages. There is a syntax summary in the<a href="pcre2syntax.html"><b>pcre2syntax</b></a>page.</P><P>Some features of PCRE2 can be included, excluded, or changed when the libraryis built. The<a href="pcre2_config.html"><b>pcre2_config()</b></a>function makes it possible for a client to discover which features areavailable. The features themselves are described in the<a href="pcre2build.html"><b>pcre2build</b></a>page. Documentation about building PCRE2 for various operating systems can befound in the<a href="README.txt"><b>README</b></a>and<a href="NON-AUTOTOOLS-BUILD.txt"><b>NON-AUTOTOOLS_BUILD</b></a>files in the source distribution.</P><P>The libraries contains a number of undocumented internal functions and datatables that are used by more than one of the exported external functions, butwhich are not intended for use by external callers. Their names all begin with"_pcre2", which hopefully will not provoke any name clashes. In someenvironments, it is possible to control which external symbols are exportedwhen a shared library is built, and in these cases the undocumented symbols arenot exported.</P><br><a name="SEC2" href="#TOC1">SECURITY CONSIDERATIONS</a><br><P>If you are using PCRE2 in a non-UTF application that permits users to supplyarbitrary patterns for compilation, you should be aware of a feature thatallows users to turn on UTF support from within a pattern. For example, an8-bit pattern that begins with "(*UTF)" turns on UTF-8 mode, which interpretspatterns and subjects as strings of UTF-8 code units instead of individual8-bit characters. This causes both the pattern and any data against which it ismatched to be checked for UTF-8 validity. If the data string is very long, sucha check might use sufficiently many resources as to cause your application tolose performance.</P><P>One way of guarding against this possibility is to use the<b>pcre2_pattern_info()</b> function to check the compiled pattern's options forPCRE2_UTF. Alternatively, you can set the PCRE2_NEVER_UTF option when calling<b>pcre2_compile()</b>. This causes a compile time error if the pattern containsa UTF-setting sequence.</P><P>The use of Unicode properties for character types such as \d can also beenabled from within the pattern, by specifying "(*UCP)". This feature can bedisallowed by setting the PCRE2_NEVER_UCP option.</P><P>If your application is one that supports UTF, be aware that validity checkingcan take time. If the same data string is to be matched many times, you can usethe PCRE2_NO_UTF_CHECK option for the second and subsequent matches to avoidrunning redundant checks.</P><P>The use of the \C escape sequence in a UTF-8 or UTF-16 pattern can lead toproblems, because it may leave the current matching point in the middle of amulti-code-unit character. The PCRE2_NEVER_BACKSLASH_C option can be used by anapplication to lock out the use of \C, causing a compile-time error if it isencountered. It is also possible to build PCRE2 with the use of \C permanentlydisabled.</P><P>Another way that performance can be hit is by running a pattern that has a verylarge search tree against a string that will never match. Nested unlimitedrepeats in a pattern are a common example. PCRE2 provides some protectionagainst this: see the <b>pcre2_set_match_limit()</b> function in the<a href="pcre2api.html"><b>pcre2api</b></a>page. There is a similar function called <b>pcre2_set_depth_limit()</b> that canbe used to restrict the amount of memory that is used.</P><br><a name="SEC3" href="#TOC1">USER DOCUMENTATION</a><br><P>The user documentation for PCRE2 comprises a number of different sections. Inthe "man" format, each of these is a separate "man page". In the HTML format,each is a separate page, linked from the index page. In the plain text format,the descriptions of the <b>pcre2grep</b> and <b>pcre2test</b> programs are infiles called <b>pcre2grep.txt</b> and <b>pcre2test.txt</b>, respectively. Theremaining sections, except for the <b>pcre2demo</b> section (which is a programlisting), and the short pages for individual functions, are concatenated in<b>pcre2.txt</b>, for ease of searching. The sections are as follows:<pre> pcre2 this document pcre2-config show PCRE2 installation configuration information pcre2api details of PCRE2's native C API pcre2build building PCRE2 pcre2callout details of the pattern callout feature pcre2compat discussion of Perl compatibility pcre2convert details of pattern conversion functions pcre2demo a demonstration C program that uses PCRE2 pcre2grep description of the <b>pcre2grep</b> command (8-bit only) pcre2jit discussion of just-in-time optimization support pcre2limits details of size and other limits pcre2matching discussion of the two matching algorithms pcre2partial details of the partial matching facility pcre2pattern syntax and semantics of supported regular expression patterns pcre2perform discussion of performance issues pcre2posix the POSIX-compatible C API for the 8-bit library pcre2sample discussion of the pcre2demo program pcre2serialize details of pattern serialization pcre2syntax quick syntax reference pcre2test description of the <b>pcre2test</b> command pcre2unicode discussion of Unicode and UTF support</pre>In the "man" and HTML formats, there is also a short page for each C libraryfunction, listing its arguments and results.</P><br><a name="SEC4" href="#TOC1">AUTHOR</a><br><P>Philip Hazel<br>Retired from University Computing Service<br>Cambridge, England.<br></P><P>Putting an actual email address here is a spam magnet. If you want to email me,use my two names separated by a dot at gmail.com.</P><br><a name="SEC5" href="#TOC1">REVISION</a><br><P>Last updated: 27 August 2021<br>Copyright © 1997-2021 University of Cambridge.<br><p>Return to the <a href="index.html">PCRE2 index page</a>.</p>
|
