Spaces:
Running
Running
| <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 generated | |
| automatically 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 set | |
| of functions, written in C, that implement regular expression pattern matching | |
| using the same syntax and semantics as Perl, with just a few differences. After | |
| nearly two decades, the limitations of the original API were making development | |
| increasingly difficult. The new API is more extensible, and it was simplified | |
| by abolishing the separate "study" optimizing function; in PCRE2, patterns are | |
| automatically optimized where possible. Since forking from PCRE1, the code has | |
| been extensively refactored and new features introduced. The old library is now | |
| obsolete and is no longer maintained. | |
| </P> | |
| <P> | |
| As well as Perl-style regular expression patterns, some features that appeared | |
| in Python and the original PCRE before they appeared in Perl are available | |
| using the Python syntax. There is also some support for one or two .NET and | |
| Oniguruma syntax items, and there are options for requesting some minor changes | |
| that 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 be | |
| installed, one for each code unit size. The size of code unit is not related to | |
| the bit size of the underlying hardware. In a 64-bit environment that also | |
| supports 32-bit applications, versions of PCRE2 that are compiled in both | |
| 64-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 by | |
| Zoltan Herczeg and Christian Persch, respectively. In all three cases, strings | |
| can be interpreted either as one character per code unit, or as UTF-encoded | |
| Unicode, with support for Unicode general category properties. Unicode support | |
| is optional at build time (but is the default). However, processing strings as | |
| UTF code units must be enabled explicitly at run time. The version of Unicode | |
| in 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 just | |
| one code unit width can be written using generic names such as | |
| <b>pcre2_compile()</b>, and the documentation is written assuming that this is | |
| the case. | |
| </P> | |
| <P> | |
| In addition to the Perl-compatible matching function, PCRE2 contains an | |
| alternative function that matches the same compiled patterns in a different | |
| way. 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 not | |
| supported 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 library | |
| is built. The | |
| <a href="pcre2_config.html"><b>pcre2_config()</b></a> | |
| function makes it possible for a client to discover which features are | |
| available. 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 be | |
| found 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 data | |
| tables that are used by more than one of the exported external functions, but | |
| which are not intended for use by external callers. Their names all begin with | |
| "_pcre2", which hopefully will not provoke any name clashes. In some | |
| environments, it is possible to control which external symbols are exported | |
| when a shared library is built, and in these cases the undocumented symbols are | |
| not 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 supply | |
| arbitrary patterns for compilation, you should be aware of a feature that | |
| allows users to turn on UTF support from within a pattern. For example, an | |
| 8-bit pattern that begins with "(*UTF)" turns on UTF-8 mode, which interprets | |
| patterns and subjects as strings of UTF-8 code units instead of individual | |
| 8-bit characters. This causes both the pattern and any data against which it is | |
| matched to be checked for UTF-8 validity. If the data string is very long, such | |
| a check might use sufficiently many resources as to cause your application to | |
| lose 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 for | |
| PCRE2_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 contains | |
| a UTF-setting sequence. | |
| </P> | |
| <P> | |
| The use of Unicode properties for character types such as \d can also be | |
| enabled from within the pattern, by specifying "(*UCP)". This feature can be | |
| disallowed by setting the PCRE2_NEVER_UCP option. | |
| </P> | |
| <P> | |
| If your application is one that supports UTF, be aware that validity checking | |
| can take time. If the same data string is to be matched many times, you can use | |
| the PCRE2_NO_UTF_CHECK option for the second and subsequent matches to avoid | |
| running redundant checks. | |
| </P> | |
| <P> | |
| The use of the \C escape sequence in a UTF-8 or UTF-16 pattern can lead to | |
| problems, because it may leave the current matching point in the middle of a | |
| multi-code-unit character. The PCRE2_NEVER_BACKSLASH_C option can be used by an | |
| application to lock out the use of \C, causing a compile-time error if it is | |
| encountered. It is also possible to build PCRE2 with the use of \C permanently | |
| disabled. | |
| </P> | |
| <P> | |
| Another way that performance can be hit is by running a pattern that has a very | |
| large search tree against a string that will never match. Nested unlimited | |
| repeats in a pattern are a common example. PCRE2 provides some protection | |
| against 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 can | |
| be 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. In | |
| the "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 in | |
| files called <b>pcre2grep.txt</b> and <b>pcre2test.txt</b>, respectively. The | |
| remaining sections, except for the <b>pcre2demo</b> section (which is a program | |
| listing), 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 library | |
| function, 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> | |