pcre2_compile(3) — Linux manual page

NAME \| SYNOPSIS \| DESCRIPTION \| COLOPHON

PCRE2_COMPILE(3)         Library Functions Manual        PCRE2_COMPILE(3)

NAME top

       PCRE2 - Perl-compatible regular expressions (revised API)

SYNOPSIS top


       #include <pcre2.h>

       pcre2_code *pcre2_compile(PCRE2_SPTR pattern, PCRE2_SIZE length,
         uint32_t options, int *errorcode, PCRE2_SIZE *erroroffset,
         pcre2_compile_context *ccontext);

DESCRIPTION top


       This function compiles a regular expression pattern into an
       internal form. Its arguments are:

         pattern       A string containing expression to be compiled
         length        The length of the string or PCRE2_ZERO_TERMINATED
         options       Primary option bits
         errorcode     Where to put an error code
         erroffset     Where to put an error offset
         ccontext      Pointer to a compile context or NULL

       The length of the pattern and any error offset that is returned
       are in code units, not characters. A NULL pattern with zero length
       is treated as an empty string. A compile context is needed only if
       you want to provide custom memory allocation functions, or to
       provide an external function for system stack size checking (see
       pcre2_set_compile_recursion_guard()), or to change one or more of
       these parameters:

         What \R matches (Unicode newlines, or CR, LF, CRLF only);
         PCRE2's character tables;
         The newline character sequence;
         The compile time nested parentheses limit;
         The maximum pattern length (in code units) that is allowed;
         The additional options bits.

       The primary option bits are:

         PCRE2_ANCHORED           Force pattern anchoring
         PCRE2_ALLOW_EMPTY_CLASS  Allow empty classes
         PCRE2_ALT_BSUX           Alternative handling of \u, \U, and \x
         PCRE2_ALT_CIRCUMFLEX     Alternative handling of ^ in multiline
       mode
         PCRE2_ALT_EXTENDED_CLASS Alternative extended character class
       syntax
         PCRE2_ALT_VERBNAMES      Process backslashes in verb names
         PCRE2_AUTO_CALLOUT       Compile automatic callouts
         PCRE2_CASELESS           Do caseless matching
         PCRE2_DOLLAR_ENDONLY     $ not to match newline at end
         PCRE2_DOTALL             . matches anything including NL
         PCRE2_DUPNAMES           Allow duplicate names for subpatterns
         PCRE2_ENDANCHORED        Pattern can match only at end of
       subject
         PCRE2_EXTENDED           Ignore white space and # comments
         PCRE2_FIRSTLINE          Force matching to be before newline
         PCRE2_LITERAL            Pattern characters are all literal
         PCRE2_MATCH_INVALID_UTF  Enable support for matching invalid UTF
         PCRE2_MATCH_UNSET_BACKREF  Match unset backreferences
         PCRE2_MULTILINE          ^ and $ match newlines within data
         PCRE2_NEVER_BACKSLASH_C  Lock out the use of \C in patterns
         PCRE2_NEVER_UCP          Lock out PCRE2_UCP, e.g. via (*UCP)
         PCRE2_NEVER_UTF          Lock out PCRE2_UTF, e.g. via (*UTF)
         PCRE2_NO_AUTO_CAPTURE    Disable numbered capturing paren-
                                   theses (named ones available)
         PCRE2_NO_AUTO_POSSESS    Disable auto-possessification
         PCRE2_NO_DOTSTAR_ANCHOR  Disable automatic anchoring for .*
         PCRE2_NO_START_OPTIMIZE  Disable match-time start optimizations
         PCRE2_NO_UTF_CHECK       Do not check the pattern for UTF
       validity
                                    (only relevant if PCRE2_UTF is set)
         PCRE2_UCP                Use Unicode properties for \d, \w, etc.
         PCRE2_UNGREEDY           Invert greediness of quantifiers
         PCRE2_USE_OFFSET_LIMIT   Enable offset limit for unanchored
       matching
         PCRE2_UTF                Treat pattern and subjects as UTF
       strings

       PCRE2 must be built with Unicode support (the default) in order to
       use PCRE2_UTF, PCRE2_UCP and related options.

       Additional options may be set in the compile context via the
       pcre2_set_compile_extra_options function.

       If either of errorcode or erroroffset is NULL, the function
       returns NULL immediately. Otherwise, the yield of this function is
       a pointer to a private data structure that contains the compiled
       pattern, or NULL if an error was detected. In the error case, a
       text error message can be obtained by passing the value returned
       via the errorcode argument to the pcre2_get_error_message()
       function. The offset (in code units) where the error was
       encountered is returned via the erroroffset argument.

       If there is no error, the value passed via errorcode returns the
       message "no error" if passed to pcre2_get_error_message(), and the
       value passed via erroroffset is zero.

       There is a complete description of the PCRE2 native API, with more
       detail on each option, in the pcre2api page, and a description of
       the POSIX API in the pcre2posix page.

COLOPHON top

       This page is part of the PCRE (Perl Compatible Regular
       Expressions) project.  Information about the project can be found
       at ⟨http://www.pcre.org/⟩.  If you have a bug report for this
       manual page, see
       ⟨http://bugs.exim.org/enter_bug.cgi?product=PCRE⟩.  This page was
       obtained from the tarball fetched from
       ⟨https://github.com/PhilipHazel/pcre2.git⟩ on 2025-02-02.  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for the
       page, or you have corrections or improvements to the information
       in this COLOPHON (which is not part of the original manual page),
       send a mail to man-pages@man7.org

PCRE2 10.46-DEV              30 October 2024             PCRE2_COMPILE(3)