github/doc/pcre2_compile.3

.TH PCRE2_COMPILE 3 "19 January 2024" "PCRE2 10.43"
.SH NAME
PCRE2 - Perl-compatible regular expressions (revised API)
.SH SYNOPSIS
.rs
.sp
.B #include <pcre2.h>
.PP
.nf
.B pcre2_code *pcre2_compile(PCRE2_SPTR \fIpattern\fP, PCRE2_SIZE \fIlength\fP,
.B "  uint32_t \fIoptions\fP, int *\fIerrorcode\fP, PCRE2_SIZE *\fIerroroffset,\fP"
.B "  pcre2_compile_context *\fIccontext\fP);"
.fi
.
.SH DESCRIPTION
.rs
.sp
This function compiles a regular expression pattern into an internal form. Its
arguments are:
.sp
  \fIpattern\fP       A string containing expression to be compiled
  \fIlength\fP        The length of the string or PCRE2_ZERO_TERMINATED
  \fIoptions\fP       Primary option bits
  \fIerrorcode\fP     Where to put an error code
  \fIerroffset\fP     Where to put an error offset
  \fIccontext\fP      Pointer to a compile context or NULL
.sp
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 \fBpcre2_set_compile_recursion_guard()\fP), or to change one or
more of these parameters:
.sp
  What \eR 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.
.sp
The primary option bits are:
.sp
  PCRE2_ANCHORED           Force pattern anchoring
  PCRE2_ALLOW_EMPTY_CLASS  Allow empty classes
  PCRE2_ALT_BSUX           Alternative handling of \eu, \eU, and \ex
  PCRE2_ALT_CIRCUMFLEX     Alternative handling of ^ in multiline mode
  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 \eC 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 \ed, \ew, 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
.sp
PCRE2 must be built with Unicode support (the default) in order to use
PCRE2_UTF, PCRE2_UCP and related options.
.P
Additional options may be set in the compile context via the
.\" HREF
\fBpcre2_set_compile_extra_options\fP
.\"
function.
.P
If either of \fIerrorcode\fP or \fIerroroffset\fP 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 \fIerrorcode\fP argument to the
\fBpcre2_get_error_message()\fP function. The offset (in code units) where the
error was encountered is returned via the \fIerroroffset\fP argument.
.P
If there is no error, the value passed via \fIerrorcode\fP returns the message
"no error" if passed to \fBpcre2_get_error_message()\fP, and the value passed
via \fIerroroffset\fP is zero.
.P
There is a complete description of the PCRE2 native API, with more detail on
each option, in the
.\" HREF
\fBpcre2api\fP
.\"
page, and a description of the POSIX API in the
.\" HREF
\fBpcre2posix\fP
.\"
page.