pcre2

PCRE2(3)                   Library Functions Manual                   PCRE2(3)

NAME
       PCRE2 - Perl-compatible regular expressions (revised API)

INTRODUCTION

       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  sepa-
       rate  "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.

       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.

       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.

       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 cate-
       gory  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

         pcre2test -C

       The three libraries contain identical sets  of  functions,  with  names
       ending  in  _8,  _16,  or  _32,  respectively  (for example, pcre2_com-
       pile_8()). 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 pcre2_compile(), and the documentation is written
       assuming that this is the case.

       In addition to the Perl-compatible matching function, PCRE2 contains an
       alternative function that matches the same compiled patterns in a  dif-
       ferent way. In certain circumstances, the alternative function has some
       advantages.  For a discussion of the two matching algorithms,  see  the
       pcre2matching page.

       Details  of  exactly which Perl regular expression features are and are
       not supported by  PCRE2  are  given  in  separate  documents.  See  the
       pcre2pattern  and  pcre2compat  pages. There is a syntax summary in the
       pcre2syntax page.

       Some features of PCRE2 can be included, excluded, or changed  when  the
       library  is  built. The pcre2_config() function makes it possible for a
       client to discover which features are  available.  The  features  them-
       selves are described in the pcre2build page. Documentation about build-
       ing PCRE2 for various operating systems can be found in the README  and
       NON-AUTOTOOLS_BUILD files in the source distribution.

       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.

SECURITY CONSIDERATIONS

       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 pat-
       tern  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  suf-
       ficiently  many  resources as to cause your application to lose perfor-
       mance.

       One way of guarding against this possibility is to use  the  pcre2_pat-
       tern_info()  function  to  check  the  compiled  pattern's  options for
       PCRE2_UTF. Alternatively, you can set the PCRE2_NEVER_UTF  option  when
       calling  pcre2_compile().  This causes a compile time error if the pat-
       tern contains a UTF-setting sequence.

       The use of Unicode properties for character types such as \d  can  also
       be  enabled  from within the pattern, by specifying "(*UCP)". This fea-
       ture can be disallowed by setting the PCRE2_NEVER_UCP option.

       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.

       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.

       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  pro-
       vides  some  protection  against  this: see the pcre2_set_match_limit()
       function in the pcre2api page.  There  is  a  similar  function  called
       pcre2_set_depth_limit() that can be used to restrict the amount of mem-
       ory that is used.

USER DOCUMENTATION

       The user documentation for PCRE2 comprises a number of  different  sec-
       tions.  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 pcre2grep and
       pcre2test programs are in files called pcre2grep.txt and pcre2test.txt,
       respectively.  The remaining sections, except for the pcre2demo section
       (which is a program listing), and the short pages for individual  func-
       tions,  are  concatenated in pcre2.txt, for ease of searching. The sec-
       tions are as follows:

         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 pcre2grep 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 pcre2test command
         pcre2unicode       discussion of Unicode and UTF support

       In the "man" and HTML formats, there is also a short page  for  each  C
       library function, listing its arguments and results.

AUTHOR

       Philip Hazel
       Retired from University Computing Service
       Cambridge, England.

       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.

REVISION

       Last updated: 27 August 2021
       Copyright (c) 1997-2021 University of Cambridge.

PCRE2 10.38                     27 August 2021                        PCRE2(3)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2022 Hurricane Electric. All Rights Reserved.